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 State &	getState () const
	Get access to the TimeStepper's internally maintained State. More...

State &	updState ()
	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 State &	getAdvancedState () const
	synonym for getState. More...

State &	updAdvancedState ()
	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 MultibodySystem &	getMultibodySystem () const
	Get access to the MultibodySystem for which this TimeStepper was constructed. More...

const ImpulseSolver &	getImpulseSolver () 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

enum SimTK::SemiExplicitEulerTimeStepper::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

enum SimTK::SemiExplicitEulerTimeStepper::InducedImpactModel

Enumerator
Simultaneous
Sequential
Mixed

◆ PositionProjectionMethod

enum SimTK::SemiExplicitEulerTimeStepper::PositionProjectionMethod

Enumerator
Bilateral
Unilateral
NoPositionProjection

◆ ImpulseSolverType

enum SimTK::SemiExplicitEulerTimeStepper::ImpulseSolverType

Enumerator
PLUS
PGS

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:

SemiExplicitEulerTimeStepper.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ RestitutionModel

◆ InducedImpactModel

◆ PositionProjectionMethod

◆ ImpulseSolverType

Constructor & Destructor Documentation

◆ SemiExplicitEulerTimeStepper()

◆ ~SemiExplicitEulerTimeStepper()

Member Function Documentation

◆ initialize()

◆ getState()

◆ updState()

◆ getTime()

◆ getAdvancedState()

◆ updAdvancedState()

◆ getAdvancedTime()

◆ stepTo()

◆ setAccuracy()

◆ setConstraintTolerance()

◆ setRestitutionModel()

◆ getRestitutionModel()

◆ setInducedImpactModel()

◆ getInducedImpactModel()

◆ setMaxInducedImpactsPerStep()

◆ getMaxInducedImpactsPerStep()

◆ setPositionProjectionMethod()

◆ getPositionProjectionMethod()

◆ setImpulseSolverType()

◆ getImpulseSolverType()

◆ setDefaultImpactCaptureVelocity()

◆ setDefaultImpactMinCORVelocity()

◆ setDefaultFrictionTransitionVelocity()

◆ setMinSignificantForce()

◆ getMinSignificantForce()

◆ getAccuracyInUse()

◆ getConstraintToleranceInUse()

◆ getDefaultImpactCaptureVelocity()

◆ getDefaultImpactMinCORVelocity()

◆ getDefaultFrictionTransitionVelocity()

◆ getDefaultImpactCaptureVelocityInUse()

◆ getDefaultImpactMinCORVelocityInUse()

◆ getDefaultFrictionTransitionVelocityInUse()

◆ getMultibodySystem()

◆ getImpulseSolver()

◆ setImpulseSolver()

◆ clearImpulseSolver()

◆ getRestitutionModelName()

◆ getInducedImpactModelName()

◆ getPositionProjectionMethodName()

◆ getImpulseSolverTypeName()