artisynth.core.mechmodels
Interface MechSystem

All Known Subinterfaces:
MechSystemModel
All Known Implementing Classes:
FemModel, FemModel3d, FemMuscleModel, HydrostatModel, LaymanModel, MechModel, MechSystemBase, MFreeModel3d, MFreeMuscleModel, PointToPointMuscle, SpongeModel

public interface MechSystem

Interface to a second order mechanical system that can be integrated by a variety of integrators.


Nested Class Summary
static class MechSystem.ConstraintInfo
          Contains information for a single constraint direction
static class MechSystem.FrictionInfo
          Contains information for a single friction constraint set.
 
Field Summary
static int COMPUTE_CONTACTS
          Flag passed to updateConstraints() indicating that contact information should be computed.
static int UPDATE_CONTACTS
          Flag passed to updateConstraints() indicating that contact information should be updated.
 
Method Summary
 void addActivePosImpulse(VectorNd q, double h, VectorNd u)
          Computes an adjustment to the active positions of the system (stored in the vector q) by applying a velocity u for time h.
 void addPosJacobian(SparseNumberedBlockMatrix S, VectorNd f, double h)
          Adds the current force-position Jacobian, scaled by h, to the matrix S, which should have been previously created with a call to buildSolveMatrix().
 void addVelJacobian(SparseNumberedBlockMatrix S, VectorNd f, double h)
          Adds the current force-velocity Jacobian, scaled by h, to the matrix S, which should have been previously created with a call to buildSolveMatrix().
 boolean buildMassMatrix(SparseBlockMatrix M)
          Builds a mass matrix for this system.
 void buildSolveMatrix(SparseNumberedBlockMatrix S)
          Builds a solve matrix for this system.
 void getActiveForces(VectorNd f)
          Returns the generalized forces acting on all the active components in this system.
 void getActivePosDerivative(VectorNd dxdt, double t)
          Gets the current value of the position derivative for all active components.
 void getActivePosState(VectorNd q)
          Gets the current position state for all active components.
 int getActivePosStateSize()
          Returns the size of the position state for all active components.
 void getActiveVelState(VectorNd u)
          Gets the current velocity state for all active components.
 int getActiveVelStateSize()
          Returns the size of the velocity state for all active components.
 int getBilateralConstraints(SparseBlockMatrix GT, VectorNd dg)
          Obtains the transpose of the current bilateral constraint matrix G for this system.
 void getBilateralImpulses(VectorNd lam)
          Returns from the system the most recently computed bilateral constraint impulses.
 void getBilateralInfo(MechSystem.ConstraintInfo[] ginfo)
          Obtains information for all the constraint directions returned by the most recent call to getBilateralConstraints().
 void getFrictionConstraints(SparseBlockMatrix DT, MechSystem.FrictionInfo[] finfo)
          Obtains the transpose of the current friction constraint matrix D for this system.
 void getInverseMassMatrix(SparseBlockMatrix Minv, SparseBlockMatrix M)
          Sets Minv to the inverse of the mass matrix M.
 void getMassMatrix(SparseBlockMatrix M, VectorNd f, double t)
          Sets M to the current value of the mass matrix for this system, evaluated at time t.
 void getParametricForces(VectorNd f)
          Gets the forces associated with parametric components.
 void getParametricPosState(VectorNd q)
          Gets the current position state for all parametric components.
 int getParametricPosStateSize()
          Returns the size of the position state for all parametric components.
 void getParametricPosTarget(VectorNd q, double s, double h)
          Obtains the desired target position for all parametric components at a particular time.
 void getParametricVelState(VectorNd u)
          Gets the current velocity state for all parametric components.
 int getParametricVelStateSize()
          Returns the size of the velocity state for all parametric components.
 void getParametricVelTarget(VectorNd u, double s, double h)
          Obtains the desired target velocity for all parametric components at a particular time.
 int getSolveMatrixType()
          Returns information about the solve matrix for this system.
 int getStructureVersion()
          Returns the current structure version of this system.
 void getUnilateralConstraints(SparseBlockMatrix NT, VectorNd dn)
          Obtains the transpose of the current unilateral constraint matrix N for this system.
 void getUnilateralImpulses(VectorNd the)
          Returns from the system the most recently computed unilateral constraint impulses.
 void getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo)
          Obtains information for all the constraint directions returned by the most recent call to getUnilateralConstraints().
 int maxFrictionConstraintSets()
          Returns that maximum number of friction constraint set that may be added by the method getFrictionConstraints().
 int numActiveComponents()
          Returns the current number of active components in this system.
 int numParametricComponents()
          Returns the current number of parametric components in this system.
 void setActiveForces(VectorNd f)
          Sets the generalized forces acting on all the active components in this system.
 void setActivePosState(VectorNd q)
          Sets the current position state for all active components.
 void setActiveVelState(VectorNd u)
          Sets the current velocity state for all active components.
 void setBilateralImpulses(VectorNd lam, double h)
          Supplies to the system the most recently computed bilateral constraint impulses.
 void setParametricForces(VectorNd f)
          Sets the forces associated with parametric components.
 void setParametricPosState(VectorNd q)
          Sets the current position state for all parametric components.
 void setParametricVelState(VectorNd u)
          Sets the current velocity state for all parametric components.
 void setUnilateralImpulses(VectorNd the, double h)
          Supplies to the system the most recently computed unilateral constraint impulses.
 void updateConstraints(double t, StepAdjustment stepAdjust, int flags)
          Updates the constraints associated with this system to be consistent with the current position and indicated time.
 void updateForces(double t)
          Updates all internal forces associated with this system to be consistent with the current position and velocity and the indicated time t.
 

Field Detail

COMPUTE_CONTACTS

static final int COMPUTE_CONTACTS
Flag passed to updateConstraints() indicating that contact information should be computed.

See Also:
Constant Field Values

UPDATE_CONTACTS

static final int UPDATE_CONTACTS
Flag passed to updateConstraints() indicating that contact information should be updated. This means that there has only been an adjustment in position and existing contacts between bodies should be maintained, though possibly with a modified set of constraints.

See Also:
Constant Field Values
Method Detail

getStructureVersion

int getStructureVersion()
Returns the current structure version of this system. The structure version should be incremented whenever the number and arrangement of active and parametric components changes, implying that any mass and solve matrices should be be rebuilt.

Returns:
current structure version number for this system

getActivePosStateSize

int getActivePosStateSize()
Returns the size of the position state for all active components. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
size of the active position state

getActivePosState

void getActivePosState(VectorNd q)
Gets the current position state for all active components. This is stored in the vector q (which will be sized appropriately by the system).

Parameters:
q - vector in which the state is stored

setActivePosState

void setActivePosState(VectorNd q)
Sets the current position state for all active components. This is supplied in the vector q, whose size should be greater than or equal to the value returned by getActivePosStateSize().

Parameters:
q - vector supplying the state information

getActiveVelStateSize

int getActiveVelStateSize()
Returns the size of the velocity state for all active components. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
size of the velocity state

getActiveVelState

void getActiveVelState(VectorNd u)
Gets the current velocity state for all active components. This is stored in the vector u (which will be sized appropriately by the system).

Parameters:
u - vector in which the state is stored

setActiveVelState

void setActiveVelState(VectorNd u)
Sets the current velocity state for all active components. This is supplied in the vector u, whose size should be greater than or equal to the value returned by getActiveVelStateSize().

Parameters:
u - vector supplying the state information

getParametricPosStateSize

int getParametricPosStateSize()
Returns the size of the position state for all parametric components. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
size of the parametric position state

getParametricPosTarget

void getParametricPosTarget(VectorNd q,
                            double s,
                            double h)
Obtains the desired target position for all parametric components at a particular time. This is stored in the vector q (which will be sized appropriately by the system). The system interpolates between the current parametric position values and those desired for the end of the time step, using a parameter s defined on the interval [0,1]. In particular, specifying s = 0 yields the current parametric positions, and s = 1 yields the positions desired for the end of the step. The actual time step size h is also provided, as this may be needed by some interpolation methods.

The interpolation uses the current parametric positions, and possibly the current parametric velocities as well. Hence this method should be called before either of these are changed using setParametricPosState() or setParametricVelState().

Parameters:
q - vector returning the state information
s - specifies time relative to the current time step
h - time step size

getParametricPosState

void getParametricPosState(VectorNd q)
Gets the current position state for all parametric components. This is stored in the vector q (which will be sized appropriately by the system).

Parameters:
q - vector in which the state is stored

setParametricPosState

void setParametricPosState(VectorNd q)
Sets the current position state for all parametric components. This is supplied in the vector q, whose size should be greater than or equal to the value returned by getParametricPosStateSize().

Parameters:
q - vector supplying the state information

getParametricVelStateSize

int getParametricVelStateSize()
Returns the size of the velocity state for all parametric components. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
size of the parametric velocity state

getParametricVelTarget

void getParametricVelTarget(VectorNd u,
                            double s,
                            double h)
Obtains the desired target velocity for all parametric components at a particular time. This is stored in the vector u (which will be sized appropriately by the system). The system interpolates between the current parametric velocity values and those desired for the end of the time step, using a parameter s defined on the interval [0,1]. In particular, specifying s = 0 yields the current parametric velocities, and s = 1 yields the velocities desired for the end of the step. The actual time step size h is also provided, as this may be needed by some interpolation methods.

The interpolation uses the current parametric velocities, and possibly the current parametric positions as well. Hence this method should be called before either of these are changed using setParametricPosState() or setParametricVelState().

Parameters:
u - vector returning the parametric target velocites
s - specifies time relative to the current time step
h - time step size

getParametricVelState

void getParametricVelState(VectorNd u)
Gets the current velocity state for all parametric components. This is stored in the vector u (which will be sized appropriately by the system).

Parameters:
u - vector in which state is stored

setParametricVelState

void setParametricVelState(VectorNd u)
Sets the current velocity state for all parametric components. This is supplied in the vector u, whose size should be greater than or equal to the value returned by getParametricVelStateSize().

Parameters:
u - vector supplying the state information

setParametricForces

void setParametricForces(VectorNd f)
Sets the forces associated with parametric components. This is supplied in the vector f, whose size should be greater or equal to the value returned by getParametricVelStateSize().

Parameters:
f - vector supplying the force information

getParametricForces

void getParametricForces(VectorNd f)
Gets the forces associated with parametric components. This is returned in the vector f (which will be sized appropriately by the system).

Parameters:
f - vector in which to return the force information

getActivePosDerivative

void getActivePosDerivative(VectorNd dxdt,
                            double t)
Gets the current value of the position derivative for all active components. This is stored in the vector dxdt (which will be sized appropriately by the system).

Parameters:
dxdt - vector in which the derivative is stored
t - current time value

getActiveForces

void getActiveForces(VectorNd f)
Returns the generalized forces acting on all the active components in this system. This is stored in the vector f (which will be sized appropriately by the system).

Parameters:
f - vector in which the forces are stored

setActiveForces

void setActiveForces(VectorNd f)
Sets the generalized forces acting on all the active components in this system. The values are specifies in the vector f, whose size should be greater or equal to the value returned by getActiveVelStateSize().

Parameters:
f - vector specifying the forces to be set

buildMassMatrix

boolean buildMassMatrix(SparseBlockMatrix M)
Builds a mass matrix for this system. This is done by adding blocks of an appropriate type to the sparse block matrix M. On input, M should be empty with zero size; it will be sized appropriately by the system.

This method returns true if the mass matrix is constant; i.e., does not vary with time. It does not place actual values in the matrix; that must be done by calling getMassMatrix().

A new mass matrix should be built whenever the system's structure version (as returned by getStructureVersion()) changes.

Parameters:
M - matrix in which the mass matrix will be built
Returns:
true if the mass matrix is constant.

getMassMatrix

void getMassMatrix(SparseBlockMatrix M,
                   VectorNd f,
                   double t)
Sets M to the current value of the mass matrix for this system, evaluated at time t. M should have been previously created with a call to buildMassMatrix(). The current mass forces are returned in the vector f, which should have a size greater or equal to the size of M. The mass forces (also known as the fictitious forces) are given by
 - dM/dt u
 
where u is the current system velocity. f will be sized appropriately by the system.

Parameters:
M - returns the mass matrix
f - returns the mass forces
t - current time

getInverseMassMatrix

void getInverseMassMatrix(SparseBlockMatrix Minv,
                          SparseBlockMatrix M)
Sets Minv to the inverse of the mass matrix M. Minv should have been previously created with a call to buildMassMatrix().

This method assumes that M is block diagonal and hence Minv has the same block structure. Although it is possible to compute Minv by simply inverting each block of M, the special structure of each mass block may permit the system to do this in a highly optimized way.

Parameters:
Minv - returns the inverted mass matrix
M - mass matrix to invert

buildSolveMatrix

void buildSolveMatrix(SparseNumberedBlockMatrix S)
Builds a solve matrix for this system. This is done by adding blocks of an appropriate type to the sparse block matrix S. On input, S should be empty with zero size; it will be sized appropriately by the system. The resulting matrix should have all the blocks required to store any combination of the mass matrix, the force-position Jacobian, and the force-velocity Jacobian. This method does not place actual values in the matrix; that must be done by adding a mass matrix to it, or by calling addVelJacobian() or addPosJacobian().

A new solve matrix should be built whenever the system's structure version (as returned by getStructureVersion()) changes.

Parameters:
S - matrix in which the solve matrix will be built

getSolveMatrixType

int getSolveMatrixType()
Returns information about the solve matrix for this system. This consists of an or-ed set of flags, including SYMMETRIC or POSITIVE_DEFINITE, which aid in determining the best way to solve the matrix.

Returns:
type information for the solve matrix

numActiveComponents

int numActiveComponents()
Returns the current number of active components in this system. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
number of active components

numParametricComponents

int numParametricComponents()
Returns the current number of parametric components in this system. This should remain unchanged as long as the current structure version (returned by getStructureVersion() remains unchanged.

Returns:
number of parametric components

addVelJacobian

void addVelJacobian(SparseNumberedBlockMatrix S,
                    VectorNd f,
                    double h)
Adds the current force-velocity Jacobian, scaled by h, to the matrix S, which should have been previously created with a call to buildSolveMatrix(). Addition fictitious forces associated with the Jacobian can be optionally returned in the vector f, which will be sized appropriately by the system.

Parameters:
S - matrix to which scaled Jacobian is to be added
f - if non-null, returns fictitious forces associated with the Jacobian
h - scale factor for the Jacobian

addPosJacobian

void addPosJacobian(SparseNumberedBlockMatrix S,
                    VectorNd f,
                    double h)
Adds the current force-position Jacobian, scaled by h, to the matrix S, which should have been previously created with a call to buildSolveMatrix(). Addition fictitious forces associated with the Jacobian can be optionally returned in the vector f, which will be sized appropriately by the system.

Parameters:
S - matrix to which scaled Jacobian is to be added
f - if non-null, returns fictitious forces associated with the Jacobian
h - scale factor for the Jacobian

getBilateralConstraints

int getBilateralConstraints(SparseBlockMatrix GT,
                            VectorNd dg)
Obtains the transpose of the current bilateral constraint matrix G for this system. This is built and stored in GT. On input, GT should be empty with zero size; it will be sized appropriately by the system. The derivative term is returned in dg; this is given by
 dG/dt u
 
where u is the current system velocity. dg will also be sized appropriately by the system.

The method returns a version number for the constraint structure. This number should be incremented whenever the block structure of the constraint matrix changes.

Parameters:
GT - returns the transpose of G
dg - returns the derivative term for G
Returns:
constraint structure version number

getBilateralInfo

void getBilateralInfo(MechSystem.ConstraintInfo[] ginfo)
Obtains information for all the constraint directions returned by the most recent call to getBilateralConstraints(). The information is returned in the array ginfo, which should contain preallocated ConstraintInfo structures and should have a length greater or equal to the column size of GT returned by getBilateralConstraints().

Parameters:
ginfo - Array of ConstraintInfo objects used to return the constraint information.

setBilateralImpulses

void setBilateralImpulses(VectorNd lam,
                          double h)
Supplies to the system the most recently computed bilateral constraint impulses. These are supplied by the vector lam, which should have a size greater or equal to the column size of GT returned by getBilateralConstraints().

Parameters:
lam - Bilateral constraint impulses being supplied to the system.
h - Time interval associated with the impulses. Dividing by this should give the average constraint forces.

getBilateralImpulses

void getBilateralImpulses(VectorNd lam)
Returns from the system the most recently computed bilateral constraint impulses. These are stored in the vector lam, which should have a size greater or equal to the column size of GT returned by getBilateralConstraints(). For constraints which where present in the previous solve step, the impulse values should equal those which were set by the prevous call to setBilateralImpulses(). Otherwise, values can be estimated from previous impulse values (where appropriate), or supplied as 0.

Parameters:
lam - Bilateral constraint impulses being returned from the system.

getUnilateralConstraints

void getUnilateralConstraints(SparseBlockMatrix NT,
                              VectorNd dn)
Obtains the transpose of the current unilateral constraint matrix N for this system. This is built and stored in NT. On input, NT should be empty with zero size; it will be sized appropriately by the system. The derivative term is returned in dn; this is given by
 dn/dt u
 
where u is the current system velocity. dn will also be sized appropriately by the system.

Parameters:
NT - returns the transpose of N
dn - returns the derivative term for N

getUnilateralInfo

void getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo)
Obtains information for all the constraint directions returned by the most recent call to getUnilateralConstraints(). The information is returned in the array ninfo, which should contain preallocated ConstraintInfo structures and should have a length greater or equal to the column size of NT returned by getUnilateralConstraints().

Parameters:
ninfo - Array of ConstraintInfo objects used to return the constraint information.

setUnilateralImpulses

void setUnilateralImpulses(VectorNd the,
                           double h)
Supplies to the system the most recently computed unilateral constraint impulses. These are supplied by the vector the, which should have a size greater or equal to the column size of NT returned by getUnilateralConstraints().

Parameters:
the - Unilateral constraint impulses being supplied to the system.
h - Time interval associated with the impulses. Dividing by this should give the average constraint forces.

getUnilateralImpulses

void getUnilateralImpulses(VectorNd the)
Returns from the system the most recently computed unilateral constraint impulses. These are stored in the vector the, which should have a size greater or equal to the column size of NT returned by getUnilateralConstraints(). For constraints which where present in the previous solve step, the impulse values should equal those which were set by the prevous call to setUnilateralImpulses(). Otherwise, values can be estimated from previous impulse values (where appropriate), or supplied as 0.

Parameters:
the - Unilateral constraint impulses being returned from the system.

maxFrictionConstraintSets

int maxFrictionConstraintSets()
Returns that maximum number of friction constraint set that may be added by the method getFrictionConstraints(). This is used to size the finfo array supplied to that method.

Returns:
maximum friction constraint sets

getFrictionConstraints

void getFrictionConstraints(SparseBlockMatrix DT,
                            MechSystem.FrictionInfo[] finfo)
Obtains the transpose of the current friction constraint matrix D for this system. This is built and stored in DT. On input, DT should be empty with zero size; it will be sized appropriately by the system.

Each column block in DT describes a friction constraint set associated with one unilateral or bilateral constraint. Information about each friction constraint set is returned in the array finfo, which should contain preallocated FrictionInfo structures and should have a length greater or equal to the value returned by FrictionConstraintSets().

Parameters:
DT - returns the transpose of D
finfo - returns information for each friction constraint set

addActivePosImpulse

void addActivePosImpulse(VectorNd q,
                         double h,
                         VectorNd u)
Computes an adjustment to the active positions of the system (stored in the vector q) by applying a velocity u for time h. Where velocity equals position derivative, this corresponds to computing
 q += h u.
 
In other situations, such as where position is orientation expressed as a quaternion and velocity is angular velocity, the system should perform the analagous computation. q should have a size greater or equal to the value returned by getActivePosStateSize(), and u should have a size greater or equal to the value returned by getActiveVelStateSize().

Parameters:
q - positions to be adjusted
h - length of time to apply velocity
u - velocity to be applied

updateConstraints

void updateConstraints(double t,
                       StepAdjustment stepAdjust,
                       int flags)
Updates the constraints associated with this system to be consistent with the current position and indicated time. This method should be called between any change to position values and any call that obtains constraint information (such as getBilateralConstraints().

Because contact computations are expensive, the constraints associated with contact should only be computed if the flags COMPUTE_CONTACTS or UPDATE_CONTACTS are specified. The former calls for contact information to be computed from scratch, while the latter calls for contact information to be modified to reflect changes in body positions, while preserving the general contact state between bodies.

In the process of updating the constraints, the system may determine that a smaller step size is needed. This is particulary true when contact calculations show an unacceptable level of interpenetration. A smaller step size can be recommended If so, it can indicate this through the optional argument stepAdjust, if present.

Parameters:
t - current time
stepAdjust - (optional) can be used to indicate whether the current advance should be redone with a smaller step size.

updateForces

void updateForces(double t)
Updates all internal forces associated with this system to be consistent with the current position and velocity and the indicated time t. This method should be called between any change to position or velocity values (such as through setActivePosState() or setActiveVelState(), and any call to getActiveForces().

In the process of updating the forces, the system may determine that a smaller step size is needed. If so, it can indicate this through the argument optional stepAdjust, if present.

Parameters:
t - current time