Simbody  3.7
SimTK::SemiExplicitEulerTimeStepper Class Reference

A low-accuracy, high performance, velocity-level time stepper for models containing unilateral rigid contacts or other conditional constraints. More...

Public Types

enum  RestitutionModel {
  Poisson =0,
  Newton =1,
  NoRestitution =2
}
 If an impact occurs at a contact where the coefficient of restitution (COR) is non zero, this option determines how we process the restitution impulse. More...
 
enum  InducedImpactModel {
  Simultaneous =0,
  Sequential =1,
  Mixed =2
}
 
enum  PositionProjectionMethod {
  Bilateral =0,
  Unilateral =1,
  NoPositionProjection =2
}
 
enum  ImpulseSolverType {
  PLUS =0,
  PGS =1
}
 

Public Member Functions

 SemiExplicitEulerTimeStepper (const MultibodySystem &mbs)
 
 ~SemiExplicitEulerTimeStepper ()
 The contained ImpulseSolver will be destructed here; don't reference it afterwards! More...
 
void initialize (const State &initState)
 Initialize the TimeStepper's internally maintained state to a copy of the given state; allocate and initialize the ImpulseSolver if there isn't one already. More...
 
const StategetState () const
 Get access to the TimeStepper's internally maintained State. More...
 
StateupdState ()
 Get writable access to the TimeStepper's internally maintained State. More...
 
Real getTime () const
 Shortcut to getting the current time from the TimeStepper's internally maintained State. More...
 
const StategetAdvancedState () const
 synonym for getState. More...
 
StateupdAdvancedState ()
 synonym for updState. More...
 
Real getAdvancedTime () const
 synonym for getTime. More...
 
Integrator::SuccessfulStepStatus stepTo (Real time)
 Advance to the indicated time in one or more steps, using repeated induced impacts. More...
 
void setAccuracy (Real accuracy)
 Set integration accuracy; requires variable length steps. More...
 
void setConstraintTolerance (Real consTol)
 Set the tolerance to which constraints must be satisfied. More...
 
void setRestitutionModel (RestitutionModel restModel)
 
RestitutionModel getRestitutionModel () const
 
void setInducedImpactModel (InducedImpactModel indModel)
 
InducedImpactModel getInducedImpactModel () const
 
void setMaxInducedImpactsPerStep (int maxInduced)
 Limit the number of induced impact rounds per time step. More...
 
int getMaxInducedImpactsPerStep () const
 
void setPositionProjectionMethod (PositionProjectionMethod projMethod)
 
PositionProjectionMethod getPositionProjectionMethod () const
 
void setImpulseSolverType (ImpulseSolverType solverType)
 
ImpulseSolverType getImpulseSolverType () const
 
void setDefaultImpactCaptureVelocity (Real vCapture)
 Set the impact capture velocity to be used by default when a contact does not provide its own. More...
 
void setDefaultImpactMinCORVelocity (Real vMinCOR)
 Set the minimum coefficient of restitution (COR) velocity to be used by default when a unilateral contact does not provide its own. More...
 
void setDefaultFrictionTransitionVelocity (Real vTransition)
 Set the friction sliding-to-rolling transition velocity to be used by default when a frictional contact does not provide its own. More...
 
void setMinSignificantForce (Real minSignificantForce)
 Set the threshold below which we can ignore forces. More...
 
Real getMinSignificantForce () const
 
Real getAccuracyInUse () const
 Return the integration accuracy setting. More...
 
Real getConstraintToleranceInUse () const
 Return the tolerance to which we require constraints to be satisfied. More...
 
Real getDefaultImpactCaptureVelocity () const
 Return the value set for this parameter, but the actual value used during execution will be no smaller than the velocity constraint tolerance. More...
 
Real getDefaultImpactMinCORVelocity () const
 Return the value set for this parameter, but the actual value used during execution will be no smaller than the impact cature velocity. More...
 
Real getDefaultFrictionTransitionVelocity () const
 Return the value set for this parameter, but the actual value used during execution will be no smaller than the velocity constraint tolerance. More...
 
Real getDefaultImpactCaptureVelocityInUse () const
 Return the value actually being used as the default impact capture velocity. More...
 
Real getDefaultImpactMinCORVelocityInUse () const
 Return the value actually being used as the default impact minimum coefficient of restitution velocity. More...
 
Real getDefaultFrictionTransitionVelocityInUse () const
 Return the value actually being used as the default sliding-to-rolling friction transition velocity. More...
 
const MultibodySystemgetMultibodySystem () const
 Get access to the MultibodySystem for which this TimeStepper was constructed. More...
 
const ImpulseSolvergetImpulseSolver () const
 (Advanced) Get direct access to the ImpulseSolver. More...
 
void setImpulseSolver (ImpulseSolver *impulseSolver)
 (Advanced) Set your own ImpulseSolver; the TimeStepper takes over ownership so don't delete afterwards! More...
 
void clearImpulseSolver ()
 (Advanced) Delete the existing ImpulseSolver if any. More...
 

Static Public Member Functions

static const char * getRestitutionModelName (RestitutionModel rm)
 Get human-readable string representing the given enum value. More...
 
static const char * getInducedImpactModelName (InducedImpactModel iim)
 Get human-readable string representing the given enum value. More...
 
static const char * getPositionProjectionMethodName (PositionProjectionMethod ppm)
 Get human-readable string representing the given enum value. More...
 
static const char * getImpulseSolverTypeName (ImpulseSolverType ist)
 Get human-readable string representing the given enum value. More...
 

Detailed Description

A low-accuracy, high performance, velocity-level time stepper for models containing unilateral rigid contacts or other conditional constraints.

At each step, this TimeStepper determines which subset of the multibody system's conditional constraints may affect behavior; those are called "proximal" constraints. It then formulates the resulting equations and invokes an ImpulseSolver to find constraint-space impulses that solve the constraint equations and satisfy all the constraint inequalities. Generally there are multiple solutions possible, and different ImpulseSolver objects use different criteria.

A variety of options are available for different methods of handling impacts, to facilitate comparison of methods. For production, we recommend using the default options.

Member Enumeration Documentation

◆ RestitutionModel

If an impact occurs at a contact where the coefficient of restitution (COR) is non zero, this option determines how we process the restitution impulse.

The default Poisson uses Poisson's hypothesis, which treates the COR as a ratio of impulses, providing good physical behavior. The alternative Newton uses Newton's hypothesis which treats the COR as a ratio of velocities; this is more commonly used in other packages and can be somewhat faster, but may exhibit blatantly nonphysical behavior such as energy gain during an impact. Poisson and Newton are equivalent in most simple impact circumstances but can differ substantially in a multibody impact involving multiple coupled simultaneous collisions. The final alternative is NoRestitution, meaning that all CORs are treated as zero so impacts are always maximally dissipative.

Enumerator
Poisson 
Newton 
NoRestitution 

◆ InducedImpactModel

Enumerator
Simultaneous 
Sequential 
Mixed 

◆ PositionProjectionMethod

Enumerator
Bilateral 
Unilateral 
NoPositionProjection 

◆ ImpulseSolverType

Constructor & Destructor Documentation

◆ SemiExplicitEulerTimeStepper()

SimTK::SemiExplicitEulerTimeStepper::SemiExplicitEulerTimeStepper ( const MultibodySystem mbs)
explicit

◆ ~SemiExplicitEulerTimeStepper()

SimTK::SemiExplicitEulerTimeStepper::~SemiExplicitEulerTimeStepper ( )
inline

The contained ImpulseSolver will be destructed here; don't reference it afterwards!

Member Function Documentation

◆ initialize()

void SimTK::SemiExplicitEulerTimeStepper::initialize ( const State initState)

Initialize the TimeStepper's internally maintained state to a copy of the given state; allocate and initialize the ImpulseSolver if there isn't one already.

◆ getState()

const State& SimTK::SemiExplicitEulerTimeStepper::getState ( ) const
inline

Get access to the TimeStepper's internally maintained State.

◆ updState()

State& SimTK::SemiExplicitEulerTimeStepper::updState ( )
inline

Get writable access to the TimeStepper's internally maintained State.

Modifying this will change the course of the simulation.

◆ getTime()

Real SimTK::SemiExplicitEulerTimeStepper::getTime ( ) const
inline

Shortcut to getting the current time from the TimeStepper's internally maintained State.

◆ getAdvancedState()

const State& SimTK::SemiExplicitEulerTimeStepper::getAdvancedState ( ) const
inline

synonym for getState.

◆ updAdvancedState()

State& SimTK::SemiExplicitEulerTimeStepper::updAdvancedState ( )
inline

synonym for updState.

◆ getAdvancedTime()

Real SimTK::SemiExplicitEulerTimeStepper::getAdvancedTime ( ) const
inline

synonym for getTime.

◆ stepTo()

Integrator::SuccessfulStepStatus SimTK::SemiExplicitEulerTimeStepper::stepTo ( Real  time)

Advance to the indicated time in one or more steps, using repeated induced impacts.

◆ setAccuracy()

void SimTK::SemiExplicitEulerTimeStepper::setAccuracy ( Real  accuracy)
inline

Set integration accuracy; requires variable length steps.

◆ setConstraintTolerance()

void SimTK::SemiExplicitEulerTimeStepper::setConstraintTolerance ( Real  consTol)
inline

Set the tolerance to which constraints must be satisfied.

◆ setRestitutionModel()

void SimTK::SemiExplicitEulerTimeStepper::setRestitutionModel ( RestitutionModel  restModel)
inline

◆ getRestitutionModel()

RestitutionModel SimTK::SemiExplicitEulerTimeStepper::getRestitutionModel ( ) const
inline

◆ setInducedImpactModel()

void SimTK::SemiExplicitEulerTimeStepper::setInducedImpactModel ( InducedImpactModel  indModel)
inline

◆ getInducedImpactModel()

InducedImpactModel SimTK::SemiExplicitEulerTimeStepper::getInducedImpactModel ( ) const
inline

◆ setMaxInducedImpactsPerStep()

void SimTK::SemiExplicitEulerTimeStepper::setMaxInducedImpactsPerStep ( int  maxInduced)
inline

Limit the number of induced impact rounds per time step.

The effect depends on the InducedImpactModel. If Simultaneous, this setting is ignored since there is always just a single round that fully resolves the impact. If Sequential, after this many rounds the remainder of the impact is left unresolved to be dealt with at the next time step (meaning penetration will be permitted). If Mixed, this many sequential impact rounds are executed, followed by a final round which resolves any remaining penetration as for Simultaneous, meaning that all remaining induced impacts are treated as though they have zero coefficient of restitution.

◆ getMaxInducedImpactsPerStep()

int SimTK::SemiExplicitEulerTimeStepper::getMaxInducedImpactsPerStep ( ) const
inline

◆ setPositionProjectionMethod()

void SimTK::SemiExplicitEulerTimeStepper::setPositionProjectionMethod ( PositionProjectionMethod  projMethod)
inline

◆ getPositionProjectionMethod()

PositionProjectionMethod SimTK::SemiExplicitEulerTimeStepper::getPositionProjectionMethod ( ) const
inline

◆ setImpulseSolverType()

void SimTK::SemiExplicitEulerTimeStepper::setImpulseSolverType ( ImpulseSolverType  solverType)
inline

◆ getImpulseSolverType()

ImpulseSolverType SimTK::SemiExplicitEulerTimeStepper::getImpulseSolverType ( ) const
inline

◆ setDefaultImpactCaptureVelocity()

void SimTK::SemiExplicitEulerTimeStepper::setDefaultImpactCaptureVelocity ( Real  vCapture)
inline

Set the impact capture velocity to be used by default when a contact does not provide its own.

This is the impact velocity below which the coefficient of restitution is to be treated as zero. This avoids a Zeno's paradox of ever-tinier time-wasting impacts. A capture velocity should be significantly greater than the velocity constraint tolerance since speeds below that are indistinguishable from zero anyway. In practice we will use as the capture velocity the larger of this value and twice the velocity constraint tolerance currently in effect.

◆ setDefaultImpactMinCORVelocity()

void SimTK::SemiExplicitEulerTimeStepper::setDefaultImpactMinCORVelocity ( Real  vMinCOR)
inline

Set the minimum coefficient of restitution (COR) velocity to be used by default when a unilateral contact does not provide its own.

This is the velocity at which the COR reaches its specified value; below this velocity the COR increases until the capture velocity is reached, at which point the COR is set to zero. This velocity cannot be less than the capture velocity, but we don't check here. Instead we'll check at run time and use the larger of the minimum COR velocity and the capture velocity.

◆ setDefaultFrictionTransitionVelocity()

void SimTK::SemiExplicitEulerTimeStepper::setDefaultFrictionTransitionVelocity ( Real  vTransition)
inline

Set the friction sliding-to-rolling transition velocity to be used by default when a frictional contact does not provide its own.

This is the slip velocity below which we are permitted to consider that the contact may be rolling, that is, in stiction. The transition velocity should be significantly greater than the velocity constraint tolerance since speeds below that are indistinguishable from zero anyway. In practice we will use as the transition velocity the larger of this value and twice the velocity constraint tolerance currently in effect.

◆ setMinSignificantForce()

void SimTK::SemiExplicitEulerTimeStepper::setMinSignificantForce ( Real  minSignificantForce)
inline

Set the threshold below which we can ignore forces.

This gives the TimeStepper to consider any force with smaller magnitude to be zero. The default value for this is SimTK::SignificantReal, about 1e-14 in double precision.

◆ getMinSignificantForce()

Real SimTK::SemiExplicitEulerTimeStepper::getMinSignificantForce ( ) const
inline

◆ getAccuracyInUse()

Real SimTK::SemiExplicitEulerTimeStepper::getAccuracyInUse ( ) const
inline

Return the integration accuracy setting.

This has no effect unless you are running in variable time step mode.

◆ getConstraintToleranceInUse()

Real SimTK::SemiExplicitEulerTimeStepper::getConstraintToleranceInUse ( ) const
inline

Return the tolerance to which we require constraints to be satisfied.

This applies even if we are not controlling overall integration accuracy. It is also used as a "minimum meaningful velocity" value that overrides other velocity thresholds if they have been set to smaller values.

◆ getDefaultImpactCaptureVelocity()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultImpactCaptureVelocity ( ) const
inline

Return the value set for this parameter, but the actual value used during execution will be no smaller than the velocity constraint tolerance.

See also
getDefaultImpactCaptureVelocityInUse()

◆ getDefaultImpactMinCORVelocity()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultImpactMinCORVelocity ( ) const
inline

Return the value set for this parameter, but the actual value used during execution will be no smaller than the impact cature velocity.

See also
getDefaultImpactMinCORVelocityInUse()

◆ getDefaultFrictionTransitionVelocity()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultFrictionTransitionVelocity ( ) const
inline

Return the value set for this parameter, but the actual value used during execution will be no smaller than the velocity constraint tolerance.

See also
getDefaultFrictionTransitionVelocityInUse()

◆ getDefaultImpactCaptureVelocityInUse()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultImpactCaptureVelocityInUse ( ) const
inline

Return the value actually being used as the default impact capture velocity.

◆ getDefaultImpactMinCORVelocityInUse()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultImpactMinCORVelocityInUse ( ) const
inline

Return the value actually being used as the default impact minimum coefficient of restitution velocity.

◆ getDefaultFrictionTransitionVelocityInUse()

Real SimTK::SemiExplicitEulerTimeStepper::getDefaultFrictionTransitionVelocityInUse ( ) const
inline

Return the value actually being used as the default sliding-to-rolling friction transition velocity.

◆ getMultibodySystem()

const MultibodySystem& SimTK::SemiExplicitEulerTimeStepper::getMultibodySystem ( ) const
inline

Get access to the MultibodySystem for which this TimeStepper was constructed.

◆ getImpulseSolver()

const ImpulseSolver& SimTK::SemiExplicitEulerTimeStepper::getImpulseSolver ( ) const
inline

(Advanced) Get direct access to the ImpulseSolver.

◆ setImpulseSolver()

void SimTK::SemiExplicitEulerTimeStepper::setImpulseSolver ( ImpulseSolver impulseSolver)
inline

(Advanced) Set your own ImpulseSolver; the TimeStepper takes over ownership so don't delete afterwards!

◆ clearImpulseSolver()

void SimTK::SemiExplicitEulerTimeStepper::clearImpulseSolver ( )
inline

(Advanced) Delete the existing ImpulseSolver if any.

◆ getRestitutionModelName()

static const char* SimTK::SemiExplicitEulerTimeStepper::getRestitutionModelName ( RestitutionModel  rm)
static

Get human-readable string representing the given enum value.

◆ getInducedImpactModelName()

static const char* SimTK::SemiExplicitEulerTimeStepper::getInducedImpactModelName ( InducedImpactModel  iim)
static

Get human-readable string representing the given enum value.

◆ getPositionProjectionMethodName()

static const char* SimTK::SemiExplicitEulerTimeStepper::getPositionProjectionMethodName ( PositionProjectionMethod  ppm)
static

Get human-readable string representing the given enum value.

◆ getImpulseSolverTypeName()

static const char* SimTK::SemiExplicitEulerTimeStepper::getImpulseSolverTypeName ( ImpulseSolverType  ist)
static

Get human-readable string representing the given enum value.


The documentation for this class was generated from the following file: