chrono::ChConstraint Class Referenceabstract

Description

Base class for representing constraints to be used with variational inequality solvers, used with Linear/CCP/LCP problems including inequalities, equalities, nonlinearities, etc.

See ChSystemDescriptor for more information about the overall problem and data representation.

The jacobian matrix [Cq] is built row by row by jacobians [Cq_i] of the constraints.
[E] optionally includes 'cfm_i' terms on the diagonal.

In general, typical bilateral constraints must be solved to have residual c_i = 0 and unilaterals: c_i>0 where the following linearization is introduced: c_i= [Cq_i]*q + b_i

The base class introduces just the minimum requirements for the solver, that is the basic methods that will be called by the solver. It is up to the derived classes to implement these methods, and to add further features..

#include <ChConstraint.h>

Inheritance diagram for chrono::ChConstraint:

Public Member Functions

 ChConstraint ()
 Default constructor.
 
 ChConstraint (const ChConstraint &other)
 Copy constructor.
 
virtual ChConstraintClone () const =0
 "Virtual" copy constructor.
 
ChConstraintoperator= (const ChConstraint &other)
 Assignment operator: copy from other object.
 
bool operator== (const ChConstraint &other) const
 Comparison (compares only flags, not the jacobians etc.)
 
virtual bool IsValid () const
 Tells if the constraint data is currently valid.
 
virtual void SetValid (bool mon)
 Use this function to set the valid state (child class Children classes must use this function depending on the result of their implementations of RestoreReference();.
 
virtual bool IsDisabled () const
 Tells if the constraint is currently turned on or off by the user.
 
virtual void SetDisabled (bool mon)
 User can use this to enable/disable the constraint as desired.
 
virtual bool IsRedundant () const
 Tells if the constraint is redundant or singular.
 
virtual void SetRedundant (bool mon)
 Solvers may use the following to mark a constraint as redundant.
 
virtual bool IsBroken () const
 Tells if the constraint is broken, for excess of pulling/pushing.
 
virtual void SetBroken (bool mon)
 3rd party software can set the 'broken' status via this method (by default, constraints never break);
 
virtual bool IsUnilateral () const
 Tells if the constraint is unilateral (typical complementarity constraint).
 
virtual bool IsLinear () const
 Tells if the constraint is linear (if non linear, returns false).
 
eChConstraintMode GetMode () const
 Gets the mode of the constraint: free / lock / complementary A typical constraint has 'lock = true' by default.
 
void SetMode (eChConstraintMode mmode)
 Sets the mode of the constraint: free / lock / complementary.
 
virtual bool IsActive () const
 Tells if the constraint is currently active, in general, that is tells if it must be included into the system solver or not. More...
 
virtual void SetActive (bool isactive)
 Set the status of the constraint to active.
 
virtual double Compute_c_i ()
 Compute the residual of the constraint using the LINEAR expression. More...
 
double Get_c_i () const
 Return the residual 'c_i' of this constraint. // CURRENTLY NOT USED.
 
void Set_b_i (const double mb)
 Sets the known term b_i in [Cq_i]*q + b_i = 0, where: c_i = [Cq_i]*q + b_i = 0.
 
double Get_b_i () const
 Return the known term b_i in [Cq_i]*q + b_i = 0, where: c_i= [Cq_i]*q + b_i = 0.
 
void Set_cfm_i (const double mcfm)
 Sets the constraint force mixing term (default=0). More...
 
double Get_cfm_i () const
 Returns the constraint force mixing term.
 
virtual void Set_l_i (double ml_i)
 Sets the 'l_i' value (constraint reaction, see 'l' vector)
 
virtual double Get_l_i () const
 Return the 'l_i' value (constraint reaction, see 'l' vector)
 
virtual void Update_auxiliary ()
 This function must update jacobians and auxiliary data such as the 'g_i' product. More...
 
double Get_g_i () const
 Return the 'g_i' product , that is [Cq_i]*[invM_i]*[Cq_i]' (+cfm)
 
void Set_g_i (double m_g_i)
 Usually you should not use the Set_g_i function, because g_i should be automatically computed during the Update_auxiliary() .
 
virtual double Compute_Cq_q ()=0
 This function must computes the product between the row-jacobian of this constraint '[Cq_i]' and the vector of variables, 'q', that is, Cq_q=[Cq_i]*q. More...
 
virtual void Increment_q (const double deltal)=0
 This function must increment the vector of variables 'q' with the quantity [invM]*[Cq_i]'deltal,that is q+=[invM][Cq_i]'*deltal This is used for some iterative solvers. More...
 
virtual void MultiplyAndAdd (double &result, const ChVectorDynamic< double > &vect) const =0
 Computes the product of the corresponding block in the system matrix by 'vect', and add to 'result'. More...
 
virtual void MultiplyTandAdd (ChVectorDynamic< double > &result, double l)=0
 Computes the product of the corresponding transposed block in the system matrix (ie. More...
 
virtual void Project ()
 For iterative solvers: project the value of a possible 'l_i' value of constraint reaction onto admissible orthant/set. More...
 
virtual double Violation (double mc_i)
 Given the residual of the constraint computed as the linear map mc_i = [Cq]*q + b_i + cfm*l_i , returns the violation of the constraint, considering inequalities, etc. More...
 
virtual void Build_Cq (ChSparseMatrix &storage, int insrow)=0
 Puts the jacobian portions into the 'insrow' row of a sparse matrix, where each portion of jacobian is shifted in order to match the offset of the corresponding ChVariable.
 
virtual void Build_CqT (ChSparseMatrix &storage, int inscol)=0
 Same as Build_Cq, but puts the transposed jacobian row as a column.
 
void SetOffset (int moff)
 Set offset in global q vector (set automatically by ChSystemDescriptor)
 
int GetOffset () const
 Get offset in global q vector.
 
virtual void ArchiveOUT (ChArchiveOut &marchive)
 Method to allow serialization of transient data to archives.
 
virtual void ArchiveIN (ChArchiveIn &marchive)
 Method to allow de-serialization of transient data from archives.
 

Protected Attributes

double c_i
 The 'c_i' residual of the constraint (if satisfied, c must be 0)
 
double l_i
 The 'l_i' lagrangian multiplier (reaction)
 
double b_i
 The 'b_i' right term in [Cq_i]*q+b_i=0 , note: c_i= [Cq_i]*q + b_i.
 
double cfm_i
 The constraint force mixing, if needed (usually is zero) to add some numerical 'compliance' in the constraint, that is the equation becomes: c_i= [Cq_i]*q + b_i + cfm*l_i =0; Example, it could be cfm = [k * h^2](^-1) where k is stiffness.
 
eChConstraintMode mode
 mode of the constraint: free / lock / complementar
 
double g_i
 'g_i' product [Cq_i]*[invM_i]*[Cq_i]' (+cfm)
 
int offset
 offset in global "l" state vector (needed by some solvers)
 

Member Function Documentation

◆ Compute_c_i()

virtual double chrono::ChConstraint::Compute_c_i ( )
inlinevirtual

Compute the residual of the constraint using the LINEAR expression.

c_i= [Cq_i]*q + cfm_i*l_i + b_i

For a satisfied bilateral constraint, this residual must be near zero.

◆ Compute_Cq_q()

virtual double chrono::ChConstraint::Compute_Cq_q ( )
pure virtual

This function must computes the product between the row-jacobian of this constraint '[Cq_i]' and the vector of variables, 'q', that is, Cq_q=[Cq_i]*q.

This is used for some iterative solvers. *** This function MUST BE OVERRIDDEN by specialized inherited classes! (since it will be called frequently, when iterative solvers are used, the implementation of the [Cq_i]*q product must be AS FAST AS POSSIBLE!). It returns the result of the computation.

Implemented in chrono::ChConstraintThreeGeneric, chrono::ChConstraintThreeBBShaft, chrono::ChConstraintTwoGeneric, chrono::ChConstraintTwoBodies, chrono::ChConstraintTwoTuples< Ta, Tb >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZROTnodes >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZnodes >, chrono::ChConstraintTwoTuples< typecarr_a, typecarr_b >, and chrono::ChConstraintNgeneric.

◆ Increment_q()

virtual void chrono::ChConstraint::Increment_q ( const double  deltal)
pure virtual

◆ IsActive()

virtual bool chrono::ChConstraint::IsActive ( ) const
inlinevirtual

Tells if the constraint is currently active, in general, that is tells if it must be included into the system solver or not.

This method cumulates the effect of all flags (so a constraint may be not active either because 'disabled', or 'broken', o 'redundant', or not 'valid'.)

◆ MultiplyAndAdd()

virtual void chrono::ChConstraint::MultiplyAndAdd ( double &  result,
const ChVectorDynamic< double > &  vect 
) const
pure virtual

Computes the product of the corresponding block in the system matrix by 'vect', and add to 'result'.

NOTE: the 'vect' vector must already have the size of the total variables&constraints in the system; the procedure will use the ChVariable offsets (that must be already updated) to know the indexes in result and vect;

Implemented in chrono::ChConstraintThreeGeneric, chrono::ChConstraintThreeBBShaft, chrono::ChConstraintTwoGeneric, chrono::ChConstraintTwoTuples< Ta, Tb >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZROTnodes >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZnodes >, chrono::ChConstraintTwoTuples< typecarr_a, typecarr_b >, chrono::ChConstraintTwoBodies, and chrono::ChConstraintNgeneric.

◆ MultiplyTandAdd()

virtual void chrono::ChConstraint::MultiplyTandAdd ( ChVectorDynamic< double > &  result,
double  l 
)
pure virtual

Computes the product of the corresponding transposed block in the system matrix (ie.

the TRANSPOSED jacobian matrix C_q') by 'l', and add to 'result'. NOTE: the 'result' vectors must already have the size of the total variables&constraints in the system; the procedure will use the ChVariable offsets (that must be already updated) to know the indexes in result and vect;

Implemented in chrono::ChConstraintThreeGeneric, chrono::ChConstraintTwoTuples< Ta, Tb >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZROTnodes >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZnodes >, chrono::ChConstraintTwoTuples< typecarr_a, typecarr_b >, chrono::ChConstraintThreeBBShaft, chrono::ChConstraintTwoGeneric, chrono::ChConstraintTwoBodies, and chrono::ChConstraintNgeneric.

◆ Project()

void chrono::ChConstraint::Project ( )
virtual

For iterative solvers: project the value of a possible 'l_i' value of constraint reaction onto admissible orthant/set.

Default behavior: if constraint is unilateral and l_i<0, reset l_i=0 *** This function MAY BE OVERRIDDEN by specialized inherited classes! For example, a bilateral constraint can do nothing, a monolateral: l_i= ChMax(0., l_i); a 'boxed constraint': l_i= ChMin(ChMax(min., l_i), max); etc. etc.

Reimplemented in chrono::ChConstraintTwoTuplesRollingN< Ta, Tb >, chrono::ChConstraintTwoTuplesRollingN< typecarr_a, typecarr_b >, chrono::ChConstraintTwoTuplesContactN< Ta, Tb >, chrono::ChConstraintTwoTuplesContactN< typecarr_a, typecarr_b >, and chrono::ChConstraintTwoGenericBoxed.

◆ Set_cfm_i()

void chrono::ChConstraint::Set_cfm_i ( const double  mcfm)
inline

Sets the constraint force mixing term (default=0).

Adds artificial 'elasticity' to the constraint, as c_i= [Cq_i]*q + b_i + cfm*l_i = 0

◆ Update_auxiliary()

virtual void chrono::ChConstraint::Update_auxiliary ( )
inlinevirtual

This function must update jacobians and auxiliary data such as the 'g_i' product.

This function is often called by solvers at the beginning of the solution process. *** This function MUST BE OVERRIDDEN by specialized inherited classes, which have some jacobians!

Reimplemented in chrono::ChConstraintThreeGeneric, chrono::ChConstraintThreeBBShaft, chrono::ChConstraintTwoGeneric, chrono::ChConstraintTwoBodies, chrono::ChConstraintNgeneric, chrono::ChConstraintTwoTuples< Ta, Tb >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZROTnodes >, chrono::ChConstraintTwoTuples< chrono::fea::ChNodeFEAxyz, chrono::fea::ChTriangleOfXYZnodes >, and chrono::ChConstraintTwoTuples< typecarr_a, typecarr_b >.

◆ Violation()

double chrono::ChConstraint::Violation ( double  mc_i)
virtual

Given the residual of the constraint computed as the linear map mc_i = [Cq]*q + b_i + cfm*l_i , returns the violation of the constraint, considering inequalities, etc.

For bilateral constraint, violation = mc_i. For unilateral constraint, violation = min(mc_i, 0), For boxed constraints or such, inherited class MAY OVERRIDE THIS!

Reimplemented in chrono::ChConstraintTwoGenericBoxed, chrono::ChConstraintTwoTuplesFrictionT< Ta, Tb >, chrono::ChConstraintTwoTuplesFrictionT< typecarr_a, typecarr_b >, chrono::ChConstraintTwoTuplesRollingT< Ta, Tb >, and chrono::ChConstraintTwoTuplesRollingT< typecarr_a, typecarr_b >.


The documentation for this class was generated from the following files:
  • /builds/uwsbel/chrono/src/chrono/solver/ChConstraint.h
  • /builds/uwsbel/chrono/src/chrono/solver/ChConstraint.cpp