Constrainer (Artisynth API documentation)

All Known Subinterfaces:

BodyConstrainer

All Known Implementing Classes:

BodyConnector, CollisionHandler, CollisionManager, ConstrainerBase, CustomJoint, CylindricalJoint, EllipsoidJoint, EllipsoidJoint3d, FemModel, FemModel3d, FemModelDeformer, FemMuscleModel, FixedAxisJoint, FrameFem3dConstraint, FreeJoint, GimbalJoint, HingeJoint, HydrostatModel, JointBase, JointCoordinateCoupling, LinearPointConstraint, MFreeModel3d, MFreeMuscleModel, OpenSimCustomJoint, ParticleConstraintBase, ParticleLineConstraint, ParticleMeshConstraint, ParticlePlaneConstraint, PlanarConnector, PlanarJoint, PlanarTranslationJoint, PointToPointMuscle, RenderableConstrainerBase, RevoluteJoint, RollPitchJoint, SegmentedPlanarConnector, SimpleCoordinateCoupler, SkewedUniversalJoint, SliderJoint, SlottedHingeJoint, SolidJoint, SphericalJoint, SphericalJointBase, SphericalRpyJoint, SpongeModel, UniversalJoint
```
public interface Constrainer
```
Implements a constraint acting on one or more dynamic compnents. It provides the constraint matrices and other information that is used to assemble the KKT system or mixed linear complementarity problem (MLCP) used for constrained dynamic solves.
The bilateral constraints are associated with a velocity constraint matrix Gc, which is a sparse block matrix for which
```
 Gc vel = 0
 
```
where vel is the composite velocity vector for all dynamic components. The transpose of Gc is known as the bilateral force constraint matrix.
Likewise, the unilateral constraints are associated with a velocity constraint matrix Nc, for which
```
 Nc vel >= 0,
 
```
and the transpose of Nc is the unilateral force constraint matrix.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`addBilateralConstraints(SparseBlockMatrix GT, VectorNd dg, int numb)` Appends the current bilateral force constraint matrix `Gc^T` to the matrix `GT`, by appending block columns to it.
`int`	`addFrictionConstraints(SparseBlockMatrix DT, java.util.ArrayList<FrictionInfo> finfo, boolean prune, int idx)` Appends the friction force constraint matrix `Dc^T` to the matrix `DT`, by appending block columns to it.
`int`	`addUnilateralConstraints(SparseBlockMatrix NT, VectorNd dn, int numu)` Appends the current unilateral force constraint matrix `Nc^T` to the matrix `NT`, by appending block columns to it.
`int`	`getBilateralForces(VectorNd lam, int idx)` Returns the bilateral forces that were most recently set for this constrainer using `setBilateralForces(maspack.matrix.VectorNd, double, int)`.
`int`	`getBilateralInfo(MechSystem.ConstraintInfo[] ginfo, int idx)` Returns constraint information for each row of the bilateral constraint system
`void`	`getBilateralSizes(VectorNi sizes)` Returns the sizes of each block column in the bilateral force constraint matrix.
`void`	`getConstrainedComponents(java.util.HashSet<DynamicComponent> comps)` Collected all the dynamic components constrained by this constrainer.
`int`	`getFrictionForces(VectorNd phi, int idx)` Returns the friction forces that were most recently set for this constrainer using `setFrictionForces(maspack.matrix.VectorNd, double, int)`.
`int`	`getFrictionState(VectorNi state, int idx)`
`int`	`getUnilateralForces(VectorNd the, int idx)` Returns the unilateral forces that were most recently set for this constrainer using `setUnilateralForces(maspack.matrix.VectorNd, double, int)`.
`int`	`getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo, int idx)` Returns constraint information for each row of the unilateral constraint system
`void`	`getUnilateralSizes(VectorNi sizes)` Returns the sizes of each block column in the unilateral force constraint matrix.
`int`	`getUnilateralState(VectorNi state, int idx)`
`int`	`maxFrictionConstraintSets()` Returns the maximum number of friction constraint sets that can be expected for this constraint.
`int`	`setBilateralForces(VectorNd lam, double s, int idx)` Sets the bilateral forces that were computed to enforce this constraint.
`int`	`setFrictionForces(VectorNd phi, double s, int idx)` Sets the friction forces that were computed to enforce this constraint.
`int`	`setFrictionState(VectorNi state, int idx)`
`int`	`setUnilateralForces(VectorNd the, double s, int idx)` Sets the unilateral forces that were computed to enforce this constraint.
`int`	`setUnilateralState(VectorNi state, int idx)`
`double`	`updateConstraints(double t, int flags)` Updates the current set of constraints, and returns the maximum penetration `>` 0 associated with all of them.
`void`	`zeroForces()` Zeros all bilateral and unilateral constraint forces in this constraint.

- Method Detail
  - getBilateralSizes
```
void getBilateralSizes(VectorNi sizes)
```
    Returns the sizes of each block column in the bilateral force constraint matrix. The size for each block should be appended to the vector sizes.
    
    Parameters:
    
    sizes - vector to which the block column sizes are appended
  - addBilateralConstraints
```
int addBilateralConstraints(SparseBlockMatrix GT,
                            VectorNd dg,
                            int numb)
```
    Appends the current bilateral force constraint matrix Gc^T to the matrix GT, by appending block columns to it. If the argument dg is non-null, it should be used to return the velocity constraint time derivative, defined by
```
 \dot Gc vel
 
```
    starting at the location numb. In all cases, the method must return an updated value of numb, incremented by the total row size of Gc.
    Parameters:
    
    GT - matrix to which the bilateral force contraint matrix is appended.
    
    dg - if non-null, returns the velocity constraint time derivative
    
    numb - starting index for time derivative in dg
    
    Returns:
    
    updated value of numb
  - getBilateralInfo
```
int getBilateralInfo(MechSystem.ConstraintInfo[] ginfo,
                     int idx)
```
    Returns constraint information for each row of the bilateral constraint system
```
 Gc vel = 0.
 
```
    This information is placed in pre-allocated MechSystem.ConstraintInfo structures in ginfo, starting at idx. The method must return an updated value of idx, incremented by the number of rows of Gc.
    The constraint information to be set in ConstraintInfo includes:
```
   dist        // distance to the constraint surface.
   compliance  // if > 0, gives constraint compliance value
   damping     // damping; only used if compliance > 0
   force       // used for computing non-linear compliance
 
```
    Parameters:
    
    ginfo - returns the constraint information
    
    idx - starting location in ginfo for returning constraint info
    
    Returns:
    
    updated value of idx
  - setBilateralForces
```
int setBilateralForces(VectorNd lam,
                       double s,
                       int idx)
```
    Sets the bilateral forces that were computed to enforce this constraint. These are the Lagrange multipliers for the columns of the transposed bilateral constraint matrix. The forces are supplied in lam, starting at the index idx, and should be scaled by s. (In practice, s is used to convert from impulses to forces.) The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    lam - supplies the force impulses, which should be scaled by s
    
    s - scaling factor for the force values
    
    idx - starting index of forces in lam
    
    Returns:
    
    updated value of idx
  - getBilateralForces
```
int getBilateralForces(VectorNd lam,
                       int idx)
```
    Returns the bilateral forces that were most recently set for this constrainer using setBilateralForces(maspack.matrix.VectorNd, double, int). The forces are returned in lam, starting at the index idx. The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    lam - returns the forces
    
    idx - starting index for forces in lam
    
    Returns:
    
    updated value of idx
  - zeroForces
```
void zeroForces()
```
    Zeros all bilateral and unilateral constraint forces in this constraint.
  - getUnilateralSizes
```
void getUnilateralSizes(VectorNi sizes)
```
    Returns the sizes of each block column in the unilateral force constraint matrix. The size for each block should be appended to the vector sizes.
    
    Parameters:
    
    sizes - vector to which the block column sizes are appended
  - addUnilateralConstraints
```
int addUnilateralConstraints(SparseBlockMatrix NT,
                             VectorNd dn,
                             int numu)
```
    Appends the current unilateral force constraint matrix Nc^T to the matrix NT, by appending block columns to it. If the argument dn is non-null, it should be used to return the velocity constraint time derivative, defined by
```
 \dot Nc vel
 
```
    starting at the location numu. In all cases, the method must return an updated value of numu, incremented by the total row size of Nc.
    Parameters:
    
    NT - matrix to which the unilateral force contraint matrix is appended.
    
    dn - if non-null, returns the velocity constraint time derivative
    
    numu - starting index for time derivative in dn
    
    Returns:
    
    updated value of numu
  - getUnilateralInfo
```
int getUnilateralInfo(MechSystem.ConstraintInfo[] ninfo,
                      int idx)
```
    Returns constraint information for each row of the unilateral constraint system
```
 Nc vel > 0.
 
```
    This information is placed in pre-allocated MechSystem.ConstraintInfo structures in ninfo, starting at idx. The method must return an updated value of idx, incremented by the number of rows of Nc.
    The constraint information to be set in ConstraintInfo includes:
```
   dist        // distance to the constraint surface.
   compliance  // if > 0, gives constraint compliance value
   damping     // damping; only used if compliance > 0
   force       // used for computing non-linear compliance
 
```
    Parameters:
    
    ninfo - returns the constraint information
    
    idx - starting location in ninfo for returning constraint info
    
    Returns:
    
    updated value of idx
  - setUnilateralForces
```
int setUnilateralForces(VectorNd the,
                        double s,
                        int idx)
```
    Sets the unilateral forces that were computed to enforce this constraint. These are the Lagrange multipliers for the columns of the transposed unilateral constraint matrix. The forces are supplied in the, starting at the index idx, and should be scaled by s. (In practice, s is used to convert from impulses to forces.) The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    the - supplies the force impulses, which should be scaled by s
    
    s - scaling factor for the force values
    
    idx - starting index of forces in the
    
    Returns:
    
    updated value of idx
  - getUnilateralForces
```
int getUnilateralForces(VectorNd the,
                        int idx)
```
    Returns the unilateral forces that were most recently set for this constrainer using setUnilateralForces(maspack.matrix.VectorNd, double, int). The forces are returned in the, starting at the index idx. The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    the - returns the forces
    
    idx - starting index for forces in the
    
    Returns:
    
    updated value of idx
  - setUnilateralState
```
int setUnilateralState(VectorNi state,
                       int idx)
```
  - getUnilateralState
```
int getUnilateralState(VectorNi state,
                       int idx)
```
  - maxFrictionConstraintSets
```
int maxFrictionConstraintSets()
```
    Returns the maximum number of friction constraint sets that can be expected for this constraint. There should be one constraint set for each bilateral or unilateral constraint that may be associated with friction. This method is used for presizing the finfo argument that is passed to addFrictionConstraints(maspack.matrix.SparseBlockMatrix, java.util.ArrayList<maspack.spatialmotion.FrictionInfo>, boolean, int).
    
    Returns:
    
    maximum number of friction constraint sets
  - addFrictionConstraints
```
int addFrictionConstraints(SparseBlockMatrix DT,
                           java.util.ArrayList<FrictionInfo> finfo,
                           boolean prune,
                           int idx)
```
    Appends the friction force constraint matrix Dc^T to the matrix DT, by appending block columns to it. Each block column in Dc^T corresponds to a friction constraint set, for which information should be supplied in the pre-allocated FrictionInfo structures in finfo, starting at idx. The method must return an updated value of idx, incremented by the number of friction constraint sets.
    
    Parameters:
    
    DT - matrix to which the friction force contraint matrix is appended.
    
    finfo - returns friction constraint information for each block column in Dc^T
    
    prune - restrict entries of DT to friction constraints for which the contact force is > 0.
    
    idx - starting index for friction information in finfo
    
    Returns:
    
    updated value of idx
  - setFrictionForces
```
int setFrictionForces(VectorNd phi,
                      double s,
                      int idx)
```
    Sets the friction forces that were computed to enforce this constraint. These are the Lagrange multipliers for the columns of the transposed friction constraint matrix. The forces are supplied in phi, starting at the index idx, and should be scaled by s. (In practice, s is used to convert from impulses to forces.) The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    phi - supplies the force impulses, which should be scaled by s
    
    s - scaling factor for the force values
    
    idx - starting index of forces in phi
    
    Returns:
    
    updated value of idx
  - getFrictionForces
```
int getFrictionForces(VectorNd phi,
                      int idx)
```
    Returns the friction forces that were most recently set for this constrainer using setFrictionForces(maspack.matrix.VectorNd, double, int). The forces are returned in phi, starting at the index idx. The method must return an updated value of idx, incremented by the number of forces associated with this constraint.
    
    Parameters:
    
    phi - returns the forces
    
    idx - starting index for forces in phi
    
    Returns:
    
    updated value of idx
  - setFrictionState
```
int setFrictionState(VectorNi state,
                     int idx)
```
  - getFrictionState
```
int getFrictionState(VectorNi state,
                     int idx)
```
  - updateConstraints
```
double updateConstraints(double t,
                         int flags)
```
    Updates the current set of constraints, and returns the maximum penetration > 0 associated with all of them. If no constraints are presently active, returns -1.
  - getConstrainedComponents
```
void getConstrainedComponents(java.util.HashSet<DynamicComponent> comps)
```
    Collected all the dynamic components constrained by this constrainer.
    
    Parameters:
    
    comps - set to which constrained components should be added

Interface Constrainer

Method Summary

Method Detail

getBilateralSizes

addBilateralConstraints

getBilateralInfo

setBilateralForces

getBilateralForces

zeroForces

getUnilateralSizes

addUnilateralConstraints

getUnilateralInfo

setUnilateralForces

getUnilateralForces

setUnilateralState

getUnilateralState

maxFrictionConstraintSets

addFrictionConstraints

setFrictionForces

getFrictionForces

setFrictionState

getFrictionState

updateConstraints

getConstrainedComponents