Description
Base class for collecting objects inherited from ChConstraint, ChVariables and optionally ChKRMBlock.
These objects can be used to define a sparse representation of the system. This collector is important because it contains all the required information that is sent to a solver (usually a VI/CCP solver, or as a subcase, a linear solver).
The problem is described by a variational inequality VI(Z*xd,K):
The matrix \(Z\) that represents the problem has this form:
 H Cq'*q  f= 0  Cq E  l b c
with \(Y \ni \mathbb{l} \perp \mathbb{c} \in N_y\)
where \(N_y\) is the normal cone to \(Y\)
By flipping the sign of \(l_i\), the matrix \(Z\) can be symmetric (but in general non positive definite)
 H Cq'* q f=0  Cq E  l b c
 Linear Problem: \( \forall i \,Y_i = \mathbb{R}, N_{y_{i}} = 0\) (e.g. all bilateral)
 Linear Complementarity Problem (LCP): \( 0\le c \perp l\ge0 \) (i.e. \(Y_i = \mathbb{R}^+\))
 Cone Complementarity Problem (CCP): \(Y \ni \mathbb{l} \perp \mathbb{c} \in N_y\) ( \(Y_i\) are friction cones)
Notes
 most often you call BuildSystemMatrix() right after a dynamic simulation step, in order to get the system matrices updated to the last timestep;
 when using Anitescu default stepper, the 'f' vector contains forces*timestep = F*dt
 when using Anitescu default stepper, 'q' represents the 'delta speed',
 when using Anitescu default stepper, 'b' represents the dt/phi stabilization term.
 usually, H = M, the mass matrix, but in some cases, ex. when using implicit integrators, objects inherited from ChKRMBlock can be added too, hence H could be H=a*M+b*K+c*R (but not all solvers handle ChKRMBlock!)
All solvers require that the description of the system is passed by means of a ChSystemDescriptor object that holds a list of all the constraints, variables, masses, known terms (ex.forces) under the form of ChVariables, ChConstraints and ChKRMBlock.
In this default implementation, the ChSystemDescriptor simply holds a vector of pointers to ChVariables or to ChConstraints, but more advanced implementations (ex. for supporting parallel GPU solvers) could store constraints and variables structures with other, more efficient data schemes.
#include <ChSystemDescriptor.h>
Public Member Functions  
std::vector< ChConstraint * > &  GetConstraints () 
Access the vector of constraints.  
std::vector< ChVariables * > &  GetVariables () 
Access the vector of variables.  
std::vector< ChKRMBlock * > &  GetKRMBlocks () 
Access the vector of KRM matrix blocks.  
virtual void  BeginInsertion () 
Begin insertion of items.  
virtual void  InsertConstraint (ChConstraint *mc) 
Insert reference to a ChConstraint object.  
virtual void  InsertVariables (ChVariables *mv) 
Insert reference to a ChVariables object.  
virtual void  InsertKRMBlock (ChKRMBlock *mk) 
Insert reference to a ChKRMBlock object (a piece of matrix).  
virtual void  EndInsertion () 
End insertion of items. More...  
virtual unsigned int  CountActiveVariables () const 
Count & returns the scalar variables in the system. More...  
virtual unsigned int  CountActiveConstraints () const 
Count & returns the scalar constraints in the system This excludes ChConstraint object that are set as inactive. More...  
virtual void  UpdateCountsAndOffsets () 
Update counts of scalar variables and scalar constraints.  
virtual void  SetMassFactor (const double mc_a) 
Set the c_a coefficient (default=1) used for scaling the M masses of the m_variables. More...  
virtual double  GetMassFactor () 
Get the c_a coefficient (default=1) used for scaling the M masses of the m_variables.  
virtual unsigned int  BuildFbVector (ChVectorDynamic<> &Fvector, unsigned int start_row=0) const 
Get a vector with all the 'fb' known terms associated to all variables, ordered into a column vector. More...  
virtual unsigned int  BuildBiVector (ChVectorDynamic<> &Bvector, unsigned int start_row=0) const 
Get a vector with all the 'bi' known terms ('constraint residuals') associated to all constraints, ordered into a column vector. More...  
virtual unsigned int  BuildDiVector (ChVectorDynamic<> &Dvector) const 
Get the d vector = {f; b} with all the 'fb' and 'bi' known terms, as in Z*yd (it is the concatenation of BuildFbVector and BuildBiVector) The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary. More...  
virtual unsigned int  BuildDiagonalVector (ChVectorDynamic<> &Diagonal_vect) const 
Get the D diagonal of the Z system matrix, as a single column vector (it includes all the diagonal masses of M, and all the diagonal E (cfm) terms). More...  
virtual unsigned int  FromVariablesToVector (ChVectorDynamic<> &mvector, bool resize_vector=true) const 
Using this function, one may get a vector with all the variables 'q' ordered into a column vector. More...  
virtual unsigned int  FromVectorToVariables (const ChVectorDynamic<> &mvector) 
Using this function, one may go in the opposite direction of the FromVariablesToVector() function, i.e. More...  
virtual unsigned int  FromConstraintsToVector (ChVectorDynamic<> &mvector, bool resize_vector=true) const 
Using this function, one may get a vector with all the constraint reactions 'l_i' ordered into a column vector. More...  
virtual unsigned int  FromVectorToConstraints (const ChVectorDynamic<> &mvector) 
Using this function, one may go in the opposite direction of the FromConstraintsToVector() function, i.e. More...  
virtual unsigned int  FromUnknownsToVector (ChVectorDynamic<> &mvector, bool resize_vector=true) const 
Using this function, one may get a vector with all the unknowns x={q,l} i.e. More...  
virtual unsigned int  FromVectorToUnknowns (const ChVectorDynamic<> &mvector) 
Using this function, one may go in the opposite direction of the FromUnknownsToVector() function, i.e. More...  
virtual void  SchurComplementProduct (ChVectorDynamic<> &result, const ChVectorDynamic<> &lvector, std::vector< bool > *enabled=nullptr) 
Performs the product of N, the Schur complement of the KKT matrix, by an 'l' vector. More...  
virtual void  SystemProduct (ChVectorDynamic<> &result, const ChVectorDynamic<> &x) 
Performs the product of the entire system matrix (KKT matrix), by a vector x ={q,l}. More...  
virtual void  ConstraintsProject (ChVectorDynamic<> &multipliers) 
Performs projection of constraint multipliers onto allowed set (in case of bilateral constraints it does not affect multipliers, but for frictional constraints, for example, it projects multipliers onto the friction cones) Note! the 'l_i' data in the ChConstraints of the system descriptor are changed by this operation (they get the value of 'multipliers' after the projection), so it may happen that you need to backup them via FromConstraintToVector(). More...  
virtual void  UnknownsProject (ChVectorDynamic<> &mx) 
As ConstraintsProject(), but instead of passing the l vector, the entire vector of unknowns x={q,l} is passed. More...  
virtual void  ComputeFeasabilityViolation (double &resulting_maxviolation, double &resulting_feasability) 
The following (obsolete) function may be called after a solver's 'Solve()' operation has been performed. More...  
void  PasteMassKRMMatrixInto (ChSparseMatrix &Z, unsigned int start_row=0, unsigned int start_col=0) const 
Paste the stiffness, damping or mass matrix of the system into a sparse matrix. More...  
unsigned int  PasteConstraintsJacobianMatrixInto (ChSparseMatrix &Z, unsigned int start_row=0, unsigned int start_col=0, bool only_bilateral=false) const 
Paste the constraints jacobian of the system into a sparse matrix at a given position. More...  
unsigned int  PasteConstraintsJacobianMatrixTransposedInto (ChSparseMatrix &Z, unsigned int start_row=0, unsigned int start_col=0, bool only_bilateral=false) const 
Paste the transposed constraints jacobian of the system into a sparse matrix at a given position. More...  
void  PasteComplianceMatrixInto (ChSparseMatrix &Z, unsigned int start_row=0, unsigned int start_col=0, bool only_bilateral=false) const 
Paste the compliance matrix of the system into a sparse matrix at a given position. More...  
virtual void  BuildSystemMatrix (ChSparseMatrix *Z, ChVectorDynamic<> *rhs) const 
Create and return the assembled system matrix and RHS vector at a given position. More...  
virtual void  WriteMatrixBlocks (const std::string &path, const std::string &prefix, bool one_indexed=true) 
Write the current system matrix blocks and righthand side components. More...  
virtual void  WriteMatrix (const std::string &path, const std::string &prefix, bool one_indexed=true) 
Write the current assembled system matrix and righthand side vector. More...  
virtual void  WriteMatrixSpmv (const std::string &path, const std::string &prefix, bool one_indexed=true) 
Write the current assembled system matrix and righthand side vector. More...  
virtual void  ArchiveOut (ChArchiveOut &archive_out) 
Method to allow serialization of transient data to archives.  
virtual void  ArchiveIn (ChArchiveIn &archive_in) 
Method to allow deserialization of transient data from archives.  
Protected Attributes  
std::vector< ChConstraint * >  m_constraints 
list of all constraints in the current Chrono system  
std::vector< ChVariables * >  m_variables 
list of all variables in the current Chrono system  
std::vector< ChKRMBlock * >  m_KRMblocks 
list of all KRM blocks in the current Chrono system  
double  c_a 
coefficient form M mass matrices in m_variables  
Member Function Documentation
◆ BuildBiVector()

virtual 
Get a vector with all the 'bi' known terms ('constraint residuals') associated to all constraints, ordered into a column vector.
The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary.
 Parameters

Bvector systemlevel vector 'b' start_row offset in global 'b' vector
◆ BuildDiagonalVector()

virtual 
Get the D diagonal of the Z system matrix, as a single column vector (it includes all the diagonal masses of M, and all the diagonal E (cfm) terms).
The Diagonal_vect must already have the size of n. of unknowns, otherwise it will be resized if necessary).
 Parameters

Diagonal_vect systemlevel vector of terms on M and E diagonal
◆ BuildDiVector()

virtual 
Get the d vector = {f; b} with all the 'fb' and 'bi' known terms, as in Z*yd (it is the concatenation of BuildFbVector and BuildBiVector) The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary.
 Parameters

Dvector systemlevel vector {f;b}
◆ BuildFbVector()

virtual 
Get a vector with all the 'fb' known terms associated to all variables, ordered into a column vector.
The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary.
 Parameters

Fvector systemlevel vector 'f' start_row offset in global 'f' vector
◆ BuildSystemMatrix()

virtual 
Create and return the assembled system matrix and RHS vector at a given position.
 Parameters

[out] Z assembled system matrix [out] rhs assembled RHS vector
◆ ComputeFeasabilityViolation()

virtual 
The following (obsolete) function may be called after a solver's 'Solve()' operation has been performed.
This gives an estimate of 'how good' the solver had been in finding the proper solution. Resulting estimates are passed as references in member arguments.
 Parameters

resulting_maxviolation gets the max constraint violation (either bi and unilateral.) resulting_feasability gets the max feasability as max l*c , for unilateral only
◆ ConstraintsProject()

virtual 
Performs projection of constraint multipliers onto allowed set (in case of bilateral constraints it does not affect multipliers, but for frictional constraints, for example, it projects multipliers onto the friction cones) Note! the 'l_i' data in the ChConstraints of the system descriptor are changed by this operation (they get the value of 'multipliers' after the projection), so it may happen that you need to backup them via FromConstraintToVector().
 Parameters

multipliers systemlevel vector of 'l_i' multipliers to be projected
◆ CountActiveConstraints()

virtual 
Count & returns the scalar constraints in the system This excludes ChConstraint object that are set as inactive.
Notes:
 also updates the offsets of all constraints in 'l' global vector (see GetOffset() in ChConstraint).
◆ CountActiveVariables()

virtual 
Count & returns the scalar variables in the system.
This excludes ChVariable object that are set as inactive. Notes:
 the number of scalar variables is not necessarily the number of inserted ChVariable objects, some could be inactive.
 also updates the offsets of all variables in 'q' global vector (see GetOffset() in ChVariables).
◆ EndInsertion()

inlinevirtual 
End insertion of items.
A derived class should always call UpdateCountsAndOffsets.
◆ FromConstraintsToVector()

virtual 
Using this function, one may get a vector with all the constraint reactions 'l_i' ordered into a column vector.
The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary (but uf you are sure that the vector has already the proper size, you can optimize the performance a bit by setting resize_vector as false). Optionally, you can pass an 'enabled' vector of bools, that must have the same length of the l_i reactions vector; constraints with enabled=false are not handled.
 Returns
 the number of scalar constr.multipliers (i.e. the rows of the column vector).
 Parameters

mvector systemlevel vector 'l_i' resize_vector if true, resize vector as necessary
◆ FromUnknownsToVector()

virtual 
Using this function, one may get a vector with all the unknowns x={q,l} i.e.
q variables & l_i constr. ordered into a column vector. The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary (but if you are sure that the vector has already the proper size, you can optimize the performance a bit by setting resize_vector as false).
 Returns
 the number of scalar unknowns
 Parameters

mvector systemlevel vector x={q,l} resize_vector if true, resize vector as necessary
◆ FromVariablesToVector()

virtual 
Using this function, one may get a vector with all the variables 'q' ordered into a column vector.
The column vector must be passed as a ChMatrix<> object, which will be automatically reset and resized to the proper length if necessary (but if you are sure that the vector has already the proper size, you can optimize the performance a bit by setting resize_vector as false).
 Returns
 the number of scalar variables (i.e. the rows of the column vector).
 Parameters

mvector systemlevel vector 'q' resize_vector if true, resize vector as necessary
◆ FromVectorToConstraints()

virtual 
Using this function, one may go in the opposite direction of the FromConstraintsToVector() function, i.e.
one gives a vector with all the constr.reactions 'l_i' ordered into a column vector, and the constraint objects are updated according to these values. Optionally, you can pass an 'enabled' vector of bools, that must have the same length of the l_i reactions vector; constraints with enabled=false are not handled. NOTE!!! differently from FromConstraintsToVector(), which always works, this function will fail if mvector does not match the amount and ordering of the variable objects!!! (it is up to the user to check this!) btw: most often, this is called after FromConstraintsToVector() to do a kind of 'undo', for example.
 Returns
 the number of scalar constraint multipliers (i.e. the rows of the column vector).
 Parameters

mvector systemlevel vector 'l_i'
◆ FromVectorToUnknowns()

virtual 
Using this function, one may go in the opposite direction of the FromUnknownsToVector() function, i.e.
one gives a vector with all the unknowns x={q,l} ordered into a column vector, and the variables q and constr.multipliers l objects are updated according to these values. NOTE!!! differently from FromUnknownsToVector(), which always works, this function will fail if mvector does not match the amount and ordering of the variable and constraint objects!!! (it is up to the user to check this!)
 Parameters

mvector systemlevel vector x={q,l}
◆ FromVectorToVariables()

virtual 
Using this function, one may go in the opposite direction of the FromVariablesToVector() function, i.e.
one gives a vector with all the variables 'q' ordered into a column vector, and the variables objects are updated according to these values. NOTE!!! differently from FromVariablesToVector(), which always works, this function will fail if mvector does not match the amount and ordering of the variable objects!!! (it is up to the user to check this!) btw: most often, this is called after FromVariablesToVector() to do a kind of 'undo', for example.
 Returns
 the number of scalar variables (i.e. the rows of the column vector).
 Parameters

mvector systemlevel vector 'q'
◆ PasteComplianceMatrixInto()
void chrono::ChSystemDescriptor::PasteComplianceMatrixInto  (  ChSparseMatrix &  Z, 
unsigned int  start_row = 0 , 

unsigned int  start_col = 0 , 

bool  only_bilateral = false 

)  const 
Paste the compliance matrix of the system into a sparse matrix at a given position.
Before calling this function the user needs to:
 resize Z (and potentially call SetZeroValues if the case)
 call LoadKRMMatrices with the desired factors
 call SetMassFactor() with the appropriate value
◆ PasteConstraintsJacobianMatrixInto()
unsigned int chrono::ChSystemDescriptor::PasteConstraintsJacobianMatrixInto  (  ChSparseMatrix &  Z, 
unsigned int  start_row = 0 , 

unsigned int  start_col = 0 , 

bool  only_bilateral = false 

)  const 
Paste the constraints jacobian of the system into a sparse matrix at a given position.
Before calling this function the user needs to:
 resize Z (and potentially call SetZeroValues if the case)
 call LoadConstraintJacobians Returns the number of pasted constraints.
◆ PasteConstraintsJacobianMatrixTransposedInto()
unsigned int chrono::ChSystemDescriptor::PasteConstraintsJacobianMatrixTransposedInto  (  ChSparseMatrix &  Z, 
unsigned int  start_row = 0 , 

unsigned int  start_col = 0 , 

bool  only_bilateral = false 

)  const 
Paste the transposed constraints jacobian of the system into a sparse matrix at a given position.
Before calling this function the user needs to:
 resize Z (and potentially call SetZeroValues if the case)
 call LoadConstraintJacobians Returns the number of pasted constraints.
◆ PasteMassKRMMatrixInto()
void chrono::ChSystemDescriptor::PasteMassKRMMatrixInto  (  ChSparseMatrix &  Z, 
unsigned int  start_row = 0 , 

unsigned int  start_col = 0 

)  const 
Paste the stiffness, damping or mass matrix of the system into a sparse matrix.
Before calling this function the user needs to:
 resize Z (and potentially call SetZeroValues if the case)
 call LoadKRMMatrices with the desired factors
 call SetMassFactor() with the appropriate value
◆ SchurComplementProduct()

virtual 
Performs the product of N, the Schur complement of the KKT matrix, by an 'l' vector.
result = [N]*l = [ [Cq][M^(1)][Cq']  [E] ] * l
where [Cq] are the jacobians, [M] is the mass matrix, [E] is the matrix of the optional cfm 'constraint force mixing' terms for compliant constraints. The N matrix is not built explicitly, to exploit sparsity, it is described by the inserted constraints and inserted variables. Optionally, you can pass an 'enabled' vector of bools, that must have the same length of the l_i reactions vector; constraints with enabled=false are not handled. NOTE! the 'q' data in the ChVariables of the system descriptor is changed by this operation, so it may happen that you need to backup them via FromVariablesToVector() NOTE! currently this function does NOT support the cases that use also ChKRMBlock objects, because it would need to invert the global M+K, that is not diagonal, for doing = [N]*l = [ [Cq][(M+K)^(1)][Cq']  [E] ] * l
 Parameters

result result of N * l_i lvector vector to be multiplied enabled optional: vector of "enabled" flags, one per scalar constraint.
◆ SetMassFactor()

inlinevirtual 
Set the c_a coefficient (default=1) used for scaling the M masses of the m_variables.
Used when performing SchurComplementProduct(), SystemProduct(), BuildSystemMatrix().
◆ SystemProduct()

virtual 
Performs the product of the entire system matrix (KKT matrix), by a vector x ={q,l}.
Note that the 'q' data in the ChVariables of the system descriptor is changed by this operation, so thay may need to be backed up via FromVariablesToVector()
 Parameters

result result vector (multiplication of system matrix by x) x vector to be multiplied
◆ UnknownsProject()

virtual 
As ConstraintsProject(), but instead of passing the l vector, the entire vector of unknowns x={q,l} is passed.
Note! the 'l_i' data in the ChConstraints of the system descriptor are changed by this operation (they get the value of 'multipliers' after the projection), so it may happen that you need to backup them via FromConstraintToVector().
 Parameters

mx systemlevel vector of unknowns x={q,l} (only the l part is projected)
◆ WriteMatrix()

virtual 
Write the current assembled system matrix and righthand side vector.
The system matrix is formed by calling BuildSystemMatrix() as used with direct linear solvers. The following files are written in the directory specified by [path]:
 [prefix]_Z.dat the assembled optimization matrix (COO sparse format)
 [prefix]_rhs.dat the assmbled RHS By default, uses 1based indices (as in Matlab).
◆ WriteMatrixBlocks()

virtual 
Write the current system matrix blocks and righthand side components.
The system matrix is formed by calling BuildSystemMatrix() as used with direct linear solvers. The following files are written in the directory specified by [path]:
 [prefix]_H.dat masses and/or stiffness (Matlab sparse format)
 [prefix]_Cq.dat Jacobians (Matlab sparse format)
 [prefix]_E.dat constraint compliance (Matlab sparse format)
 [prefix]_f.dat applied loads
 [prefix]_b.dat constraint rhs By default, uses 1based indices (as in Matlab).
◆ WriteMatrixSpmv()

virtual 
Write the current assembled system matrix and righthand side vector.
The system matrix is formed by multiple calls to SystemProduct() as used with iterative linear solvers. The following files are written in the directory specified by [path]:
 [prefix]_Z.dat the assembled optimization matrix (Matlab sparse format)
 [prefix]_rhs.dat the assmbled RHS By default, uses 1based indices (as in Matlab).
The documentation for this class was generated from the following files:
 /builds/uwsbel/chrono/src/chrono/solver/ChSystemDescriptor.h
 /builds/uwsbel/chrono/src/chrono/solver/ChSystemDescriptor.cpp