public interface MechSystem
Modifier and Type  Interface and Description 

static class 
MechSystem.ConstraintInfo
Contains information for a single constraint direction

Modifier and Type  Field and Description 

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. 
Modifier and Type  Method and Description 

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 forceposition 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 forcevelocity Jacobian, scaled by
h , to
the matrix S , which should have been previously created with
a call to buildSolveMatrix() . 
boolean 
buildMassMatrix(SparseNumberedBlockMatrix 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.

void 
getBilateralConstraints(SparseBlockMatrix GT,
VectorNd dg)
Obtains the transpose of the current bilateral constraint matrix G for
this system.

void 
getBilateralForces(VectorNd lam)
Returns from the system the most recently computed bilateral constraint
forces.

void 
getBilateralInfo(MechSystem.ConstraintInfo[] ginfo)
Obtains information for all the constraint directions returned
by the most recent call to
getBilateralConstraints() . 
int 
getFrictionConstraints(SparseBlockMatrix DT,
java.util.ArrayList<FrictionInfo> finfo,
boolean prune)
Obtains the transpose of the current friction constraint matrix D for
this system.

void 
getFrictionForces(VectorNd phi)
Returns from the system the most recently computed friction constraint
forces.

int 
getFrictionState(VectorNi state,
int idx) 
void 
getInverseMassMatrix(SparseBlockMatrix Minv,
SparseBlockMatrix M)
Sets
Minv to the inverse of the mass matrix M . 
void 
getMassMatrix(SparseNumberedBlockMatrix 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 
getUnilateralForces(VectorNd the)
Returns from the system the most recently computed unilateral constraint
forces.

void 
getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo)
Obtains information for all the constraint directions returned
by the most recent call to
getUnilateralConstraints() . 
int 
getUnilateralState(VectorNi state,
int idx) 
boolean 
isBilateralStructureConstant()
Queries whether or not the matrix structure of the bilateral constraints
returned by this system is constant for a given structure version.

int 
maxFrictionConstraintSets()
Returns that maximum number of friction constraint set that may be added by
the method
getFrictionConstraints() . 
void 
mulInverseMass(SparseBlockMatrix M,
VectorNd a,
VectorNd f) 
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 
setBilateralForces(VectorNd lam,
double s)
Supplies to the system the most recently computed bilateral constraint
forces.

void 
setFrictionForces(VectorNd phi,
double s)
Supplies to the system the most recently computed friction constraint
forces.

int 
setFrictionState(VectorNi state,
int idx) 
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 
setUnilateralForces(VectorNd the,
double s)
Supplies to the system the most recently computed unilateral constraint
forces.

int 
setUnilateralState(VectorNi state,
int idx) 
boolean 
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 . 
static final int COMPUTE_CONTACTS
updateConstraints()
indicating that contact information should be computed.static final int UPDATE_CONTACTS
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.int getStructureVersion()
int getActivePosStateSize()
getStructureVersion()
remains unchanged.void getActivePosState(VectorNd q)
q
(which will be sized appropriately by the
system).q
 vector in which the state is storedvoid setActivePosState(VectorNd q)
q
, whose size should be greater than
or equal to the value returned by getActivePosStateSize()
.q
 vector supplying the state informationint getActiveVelStateSize()
getStructureVersion()
remains unchanged.void getActiveVelState(VectorNd u)
u
(which will be sized appropriately by the
system).u
 vector in which the state is storedvoid setActiveVelState(VectorNd u)
u
, whose size should be greater than
or equal to the value returned by getActiveVelStateSize()
.u
 vector supplying the state informationint getParametricPosStateSize()
getStructureVersion()
remains unchanged.void getParametricPosTarget(VectorNd q, double s, double h)
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()
.
q
 vector returning the state informations
 specifies time relative to the current time steph
 time step sizevoid getParametricPosState(VectorNd q)
q
(which will be sized appropriately by
the system).q
 vector in which the state is storedvoid setParametricPosState(VectorNd q)
q
, whose size should be greater than
or equal to the value returned by getParametricPosStateSize()
.q
 vector supplying the state informationint getParametricVelStateSize()
getStructureVersion()
remains unchanged.void getParametricVelTarget(VectorNd u, double s, double h)
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()
.
u
 vector returning the parametric target velocitess
 specifies time relative to the current time steph
 time step sizevoid getParametricVelState(VectorNd u)
u
(which will be sized appropriately by
the system).u
 vector in which state is storedvoid setParametricVelState(VectorNd u)
u
, whose size should be greater than
or equal to the value returned by getParametricVelStateSize()
.u
 vector supplying the state informationvoid setParametricForces(VectorNd f)
f
, whose size should be greater or equal to
the value returned by getParametricVelStateSize()
.f
 vector supplying the force informationvoid getParametricForces(VectorNd f)
f
(which will be sized appropriately by the
system).f
 vector in which to return the force informationvoid getActivePosDerivative(VectorNd dxdt, double t)
dxdt
(which will be
sized appropriately by the system).dxdt
 vector in which the derivative is storedt
 current time valuevoid getActiveForces(VectorNd f)
f
(which will be
sized appropriately by the system).f
 vector in which the forces are storedvoid setActiveForces(VectorNd f)
f
, whose size
should be greater or equal to the value returned by
getActiveVelStateSize()
.f
 vector specifying the forces to be setboolean buildMassMatrix(SparseNumberedBlockMatrix M)
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.
M
 matrix in which the mass matrix will be builtvoid getMassMatrix(SparseNumberedBlockMatrix M, VectorNd f, double t)
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 uwhere
u
is the current system velocity.
f
will be sized appropriately by the system.M
 returns the mass matrixf
 returns the mass forcest
 current timevoid getInverseMassMatrix(SparseBlockMatrix Minv, SparseBlockMatrix M)
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.
Minv
 returns the inverted mass matrixM
 mass matrix to invertvoid mulInverseMass(SparseBlockMatrix M, VectorNd a, VectorNd f)
void buildSolveMatrix(SparseNumberedBlockMatrix S)
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
forceposition Jacobian, and the forcevelocity 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.
S
 matrix in which the solve matrix will be builtint getSolveMatrixType()
SYMMETRIC
or POSITIVE_DEFINITE
,
which aid in determining the best way to solve the matrix.int numActiveComponents()
getStructureVersion()
remains unchanged.int numParametricComponents()
getStructureVersion()
remains unchanged.void addVelJacobian(SparseNumberedBlockMatrix S, VectorNd f, double h)
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.S
 matrix to which scaled Jacobian is to be addedf
 if nonnull, returns fictitious forces associated with the Jacobianh
 scale factor for the Jacobianvoid addPosJacobian(SparseNumberedBlockMatrix S, VectorNd f, double h)
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.S
 matrix to which scaled Jacobian is to be addedf
 if nonnull, returns fictitious forces associated with the Jacobianh
 scale factor for the Jacobianboolean isBilateralStructureConstant()
true
if bilateral constraints have a constant structurevoid getBilateralConstraints(SparseBlockMatrix GT, VectorNd dg)
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 uwhere
u
is the current system velocity.
dg
will also be sized appropriately by the system.GT
 returns the transpose of Gdg
 returns the derivative term for Gvoid getBilateralInfo(MechSystem.ConstraintInfo[] ginfo)
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()
.ginfo
 Array of
ConstraintInfo
objects used to return the constraint information.void setBilateralForces(VectorNd lam, double s)
lam*s
, where lam
is a vector of impulses and s
is the inverse of the step size
used in the computation. lam
, which should have a size
greater or equal to the column size of GT
returned by getBilateralConstraints()
.lam
 When scaled by s
, gives the bilateral constraint forces
being supplied to the system.s
 Scaling factor to be applied to the lam
.void getBilateralForces(VectorNd lam)
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 force values should equal
those which were set by the prevous call to setBilateralForces()
.
Otherwise, values can be estimated from
previous force values (where appropriate), or supplied as 0.lam
 Bilateral constraint forces being returned from the system.void getUnilateralConstraints(SparseBlockMatrix NT, VectorNd dn)
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 uwhere
u
is the current system velocity.
dn
will also be sized appropriately by the system.NT
 returns the transpose of Ndn
 returns the derivative term for Nvoid getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo)
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()
.ninfo
 Array of
ConstraintInfo
objects used to return the constraint information.void setUnilateralForces(VectorNd the, double s)
the*s
, where the
is a vector of impulses and s
is the inverse of the step size
used in the computation. the
should have a size greater or
equal to the column size of NT
returned by getUnilateralConstraints()
.the
 When scaled by s
, gives the unilateral constraint forces
being supplied to the system.s
 Scaling factor to be applied to the the
.void getUnilateralForces(VectorNd the)
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
force values should equal those which were set by the previous call to
setUnilateralForces()
. Otherwise,
values can be estimated from previous force values (where appropriate),
or supplied as 0.the
 Unilateral constraint forces being returned from the system.int setUnilateralState(VectorNi state, int idx)
int getUnilateralState(VectorNi state, int idx)
int maxFrictionConstraintSets()
getFrictionConstraints()
.
This is used to size the finfo
array supplied to that
method.int getFrictionConstraints(SparseBlockMatrix DT, java.util.ArrayList<FrictionInfo> finfo, boolean prune)
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()
.
DT
 returns the transpose of Dfinfo
 returns information for each friction constraint setprune
 limit DT entries to those for which the corresponding
contact forces are > 0
void setFrictionForces(VectorNd phi, double s)
phi*s
, where phi
is a vector of impulses and s
is the inverse of the step size
used in the computation. phi
should have a size greater or
equal to the column size of DT
returned by getFrictionConstraints()
.phi
 When scaled by s
, gives the friction constraint forces
being supplied to the system.s
 Scaling factor to be applied to the phi
.void getFrictionForces(VectorNd phi)
phi
, which should
have a size greater or equal to the column size of DT
returned by getFrictionConstraints()
.
For constraints which where present in the previous solve step, the force
values should equal those which were set by the previous call to setFrictionForces()
. Otherwise, values can be
estimated from previous force values (where appropriate), or supplied as
0.phi
 Unilateral constraint forces being returned from the system.int setFrictionState(VectorNi state, int idx)
int getFrictionState(VectorNi state, int idx)
void addActivePosImpulse(VectorNd q, double h, VectorNd u)
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()
.q
 positions to be adjustedh
 length of time to apply velocityu
 velocity to be appliedboolean updateConstraints(double t, StepAdjustment stepAdjust, int flags)
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.
t
 current timestepAdjust
 (optional) can be used to indicate whether the current advance
should be redone with a smaller step size.flags
 information flagsvoid updateForces(double t)
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.
t
 current time