chrono::ChIntegrable Class Referenceabstract

Description

Interface class for all objects that support time integration.

Derived concrete classes can use time integrators for the ChTimestepper hierarchy.

#include <ChIntegrable.h>

Inheritance diagram for chrono::ChIntegrable:

Public Member Functions

virtual int GetNcoords_y ()=0
 Return the number of coordinates in the state Y.
 
virtual int GetNcoords_dy ()
 Return the number of coordinates in the state increment. More...
 
virtual int GetNconstr ()
 Return the number of lagrangian multipliers (constraints). More...
 
virtual void StateSetup (ChState &y, ChStateDelta &dy)
 Set up the system state.
 
virtual void StateGather (ChState &y, double &T)
 Gather system state in specified array. More...
 
virtual void StateScatter (const ChState &y, const double T)
 Scatter the states from the provided array to the system. More...
 
virtual void StateGatherDerivative (ChStateDelta &Dydt)
 Gather from the system the state derivatives in specified array. More...
 
virtual void StateScatterDerivative (const ChStateDelta &Dydt)
 Scatter the state derivatives from the provided array to the system. More...
 
virtual void StateGatherReactions (ChVectorDynamic<> &L)
 Gather from the system the Lagrange multipliers in specified array. More...
 
virtual void StateScatterReactions (const ChVectorDynamic<> &L)
 Scatter the Lagrange multipliers from the provided array to the system. More...
 
virtual bool StateSolve (ChStateDelta &Dydt, ChVectorDynamic<> &L, const ChState &y, const double T, const double dt, bool force_state_scatter=true)=0
 Solve for state derivatives: dy/dt = f(y,t). More...
 
virtual void StateIncrement (ChState &y_new, const ChState &y, const ChStateDelta &Dy)
 Increment state array: y_new = y + Dy. More...
 
virtual bool StateSolveCorrection (ChStateDelta &Dy, ChVectorDynamic<> &L, const ChVectorDynamic<> &R, const ChVectorDynamic<> &Qc, const double a, const double b, const ChState &y, const double T, const double dt, bool force_state_scatter=true, bool force_setup=true)
 Assuming an explicit ODE H*dy/dt = F(y,t) or an explicit DAE H*dy/dt = F(y,t) + Cq*L C(y,t) = 0 this function must compute the state increment as required for a Newton iteration within an implicit integration scheme. More...
 
virtual void LoadResidual_Hv (ChVectorDynamic<> &R, const ChVectorDynamic<> &v, const double c)
 Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with a term that has H multiplied a given vector w: R += c*H*w. More...
 
virtual void LoadResidual_F (ChVectorDynamic<> &R, const double c)
 Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with the term c*F: R += c*F. More...
 
virtual void LoadResidual_CqL (ChVectorDynamic<> &R, const ChVectorDynamic<> &L, const double c)
 Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with the term Cq'*L: R += c*Cq'*L. More...
 
virtual void LoadConstraint_C (ChVectorDynamic<> &Qc, const double c, const bool do_clamp=false, const double mclam=1e30)
 Increment a vector Qc (usually the residual in a Newton Raphson iteration for solving an implicit integration step, constraint part) with the term C: Qc += c*C. More...
 
virtual void LoadConstraint_Ct (ChVectorDynamic<> &Qc, const double c)
 Increment a vector Qc (usually the residual in a Newton Raphson iteration for solving an implicit integration step, constraint part) with the term Ct = partial derivative dC/dt: Qc += c*Ct. More...
 

Member Function Documentation

virtual int chrono::ChIntegrable::GetNconstr ( )
virtual

Return the number of lagrangian multipliers (constraints).

By default returns 0.

Reimplemented in chrono::ChSystem.

virtual int chrono::ChIntegrable::GetNcoords_dy ( )
virtual

Return the number of coordinates in the state increment.

This is a base implementation that works in many cases where dim(Y) = dim(dy), but it can be overridden in the case that y contains quaternions for rotations rather than simple y+dy

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::LoadConstraint_C ( ChVectorDynamic<> &  Qc,
const double  c,
const bool  do_clamp = false,
const double  mclam = 1e30 
)
virtual

Increment a vector Qc (usually the residual in a Newton Raphson iteration for solving an implicit integration step, constraint part) with the term C: Qc += c*C.

Parameters
Qcresult: the Qc residual, Qc += c*C
ca scaling factor
do_clampenable optional clamping of Qc
mclamclamping value

Reimplemented in chrono::ChSystem, and chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::LoadConstraint_Ct ( ChVectorDynamic<> &  Qc,
const double  c 
)
virtual

Increment a vector Qc (usually the residual in a Newton Raphson iteration for solving an implicit integration step, constraint part) with the term Ct = partial derivative dC/dt: Qc += c*Ct.

Parameters
Qcresult: the Qc residual, Qc += c*Ct
ca scaling factor

Reimplemented in chrono::ChSystem, and chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::LoadResidual_CqL ( ChVectorDynamic<> &  R,
const ChVectorDynamic<> &  L,
const double  c 
)
virtual

Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with the term Cq'*L: R += c*Cq'*L.

Parameters
Rresult: the R residual, R += c*Cq'*L
Lthe L vector
ca scaling factor

Reimplemented in chrono::ChSystem, and chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::LoadResidual_F ( ChVectorDynamic<> &  R,
const double  c 
)
virtual

Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with the term c*F: R += c*F.

Parameters
Rresult: the R residual, R += c*F
ca scaling factor

Reimplemented in chrono::ChSystem, and chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::LoadResidual_Hv ( ChVectorDynamic<> &  R,
const ChVectorDynamic<> &  v,
const double  c 
)
virtual

Increment a vector R (usually the residual in a Newton Raphson iteration for solving an implicit integration step) with a term that has H multiplied a given vector w: R += c*H*w.

Parameters
Rresult: the R residual, R += c*M*v
vthe v vector
ca scaling factor
virtual void chrono::ChIntegrable::StateGather ( ChState y,
double &  T 
)
virtual

Gather system state in specified array.

Optionally, they will copy system private state, if any, to Y.

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::StateGatherDerivative ( ChStateDelta Dydt)
virtual

Gather from the system the state derivatives in specified array.

Optional: the integrable object might contain last computed state derivative, some integrators might reuse it.

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::StateGatherReactions ( ChVectorDynamic<> &  L)
virtual

Gather from the system the Lagrange multipliers in specified array.

Optional: the integrable object might contain Lagrange multipliers (reaction in constraints)

Reimplemented in chrono::ChSystem.

void chrono::ChIntegrable::StateIncrement ( ChState y_new,
const ChState y,
const ChStateDelta Dy 
)
virtual

Increment state array: y_new = y + Dy.

This is a base implementation that works in many cases, but it can be overridden in the case that y contains quaternions for rotations, in which case rot. exponential is needed instead of simply doing y+Dy. NOTE: the system is not updated automatically after the state increment, so one might need to call StateScatter().

Parameters
y_newresulting y_new = y + Dy
yinitial state y
Dystate increment Dy

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::StateScatter ( const ChState y,
const double  T 
)
virtual

Scatter the states from the provided array to the system.

This function is called by time integrators every time they modify the Y state. In some cases, the ChIntegrable object might contain dependent data structures that might need an update at each change of Y. If so, this function must be overridden.

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::StateScatterDerivative ( const ChStateDelta Dydt)
virtual

Scatter the state derivatives from the provided array to the system.

Optional: the integrable object might need to store last computed state derivative, ex. for plotting etc.

Reimplemented in chrono::ChIntegrableIIorder.

virtual void chrono::ChIntegrable::StateScatterReactions ( const ChVectorDynamic<> &  L)
virtual

Scatter the Lagrange multipliers from the provided array to the system.

Optional: the integrable object might contain Lagrange multipliers (reaction in constraints)

Reimplemented in chrono::ChSystem.

virtual bool chrono::ChIntegrable::StateSolve ( ChStateDelta Dydt,
ChVectorDynamic<> &  L,
const ChState y,
const double  T,
const double  dt,
bool  force_state_scatter = true 
)
pure virtual

Solve for state derivatives: dy/dt = f(y,t).

Given current state y , computes the state derivative dy/dt and Lagrange multipliers L (if any). NOTE: some solvers (ex in DVI) cannot compute a classical derivative dy/dt when v is a function of bounded variation, and f or L are distributions (e.g., when there are impulses and discontinuities), so they compute a finite Dy through a finite dt. This is the reason why this function has an optional parameter dt. In a DVI setting, one computes Dy, and returns Dy*(1/dt) here in Dydt parameter; if the original Dy has to be known, just multiply Dydt*dt. The same for impulses: a DVI would compute impulses I, and return L=I*(1/dt). NOTES:

  • derived classes must take care of calling StateScatter(y,T) before computing Dy, only if force_state_scatter = true (otherwise it is assumed state is already in sync)
  • derived classes must take care of resizing Dy and L if needed.

This function must return true if successful and false otherwise.

Parameters
Dydtresult: computed Dydt
Lresult: computed lagrangian multipliers, if any
ycurrent state y
Tcurrent time T
dttimestep (if needed, ex. in DVI)
force_state_scatterif false, y and T are not scattered to the system

Implemented in chrono::ChIntegrableIIorder.

virtual bool chrono::ChIntegrable::StateSolveCorrection ( ChStateDelta Dy,
ChVectorDynamic<> &  L,
const ChVectorDynamic<> &  R,
const ChVectorDynamic<> &  Qc,
const double  a,
const double  b,
const ChState y,
const double  T,
const double  dt,
bool  force_state_scatter = true,
bool  force_setup = true 
)
virtual

Assuming an explicit ODE H*dy/dt = F(y,t) or an explicit DAE H*dy/dt = F(y,t) + Cq*L C(y,t) = 0 this function must compute the state increment as required for a Newton iteration within an implicit integration scheme.

For an ODE: Dy = [ c_a*H + c_b*dF/dy ]^-1 * R Dy = [ G ]^-1 * R For a DAE with constraints: |Dy| = [ G Cq' ]^-1 * | R | |DL| [ Cq 0 ] | Qc| where R is a given residual and dF/dy is the Jacobian of F.

This function must return true if successful and false otherwise.

Parameters
Dyresult: computed Dy
Lresult: computed lagrangian multipliers, if any
Rthe R residual
Qcthe Qc residual
athe factor in c_a*H
bthe factor in c_b*dF/dy
ycurrent state y
Tcurrent time T
dttimestep (if needed)
force_state_scatterif false, y and T are not scattered to the system
force_setupif true, call the solver's Setup() function

Reimplemented in chrono::ChIntegrableIIorder.