Simbody  3.5
SimTK::SemiExplicitEuler2Integrator Class Reference

This is an implementation of a variable-step, first-order semi-explicit Euler method, also known as semi-implicit Euler or symplectic Euler. More...

+ Inheritance diagram for SimTK::SemiExplicitEuler2Integrator:

Public Member Functions

 SemiExplicitEuler2Integrator (const System &sys)
 Create a SemiExplicitEuler2Integrator for integrating a System with variable size steps. More...
 
- Public Member Functions inherited from SimTK::Integrator
 Integrator ()
 
 ~Integrator ()
 
const char * getMethodName () const
 Get the name of this integration method. More...
 
int getMethodMinOrder () const
 Get the minimum order this Integrator may use. More...
 
int getMethodMaxOrder () const
 Get the maximum order this Integrator may use. More...
 
bool methodHasErrorControl () const
 Get whether this Integrator provides error control. More...
 
void initialize (const State &state)
 Supply the integrator with a starting state. More...
 
void reinitialize (Stage stage, bool shouldTerminate)
 After an event handler has made a discontinuous change to the Integrator's "advanced state", this method must be called to reinitialize the Integrator. More...
 
const StategetState () const
 Return a State corresponding to the "current" time at the end of the last call to stepTo() or stepBy(). More...
 
Real getTime () const
 Get the time of the current State. This is equivalent to calling getState().getTime(). More...
 
bool isStateInterpolated () const
 Get whether getState() will return an interpolated state or just the same thing as getAdvancedState() does. More...
 
const StategetAdvancedState () const
 Return the state representing the trajectory point to which the integrator has irreversibly advanced. More...
 
Real getAdvancedTime () const
 Get the time of the advanced State. This is equivalent to calling getAdvancedState().getTime(). More...
 
StateupdAdvancedState ()
 Get a non-const reference to the advanced state. More...
 
Real getAccuracyInUse () const
 Get the accuracy which is being used for error control. More...
 
Real getConstraintToleranceInUse () const
 Get the constraint tolerance which is being used for error control. More...
 
SuccessfulStepStatus stepTo (Real reportTime, Real scheduledEventTime=Infinity)
 Integrate the System until something happens which requires outside processing, and return a status code describing what happened. More...
 
SuccessfulStepStatus stepBy (Real interval, Real scheduledEventTime=Infinity)
 Integrate the System until something happens which requires outside processing, and return a status code describing what happened. More...
 
Vec2 getEventWindow () const
 Get the window (tLow, tHigh] within which one or more events have been localized. More...
 
const Array_< EventId > & getTriggeredEvents () const
 Get the IDs of all events which have been localized within the event window. More...
 
const Array_< Real > & getEstimatedEventTimes () const
 Get the estimated times of all events which have been localized within the event window. More...
 
const Array_< Event::Trigger > & getEventTransitionsSeen () const
 Get EventTriggers describing the events which have been localized within the event window. More...
 
bool isSimulationOver () const
 Get whether the simulation has terminated. More...
 
TerminationReason getTerminationReason () const
 Get the reason the simulation terminated. More...
 
void resetAllStatistics ()
 Reset all statistics to zero. More...
 
Real getActualInitialStepSizeTaken () const
 Get the size of the first successful step after the last initialize() call. More...
 
Real getPreviousStepSizeTaken () const
 Get the size of the most recent successful step. More...
 
Real getPredictedNextStepSize () const
 Get the step size that will be attempted first on the next call to stepTo() or stepBy(). More...
 
int getNumStepsAttempted () const
 Get the total number of steps that have been attempted (successfully or unsuccessfully) since the last call to resetAllStatistics(). More...
 
int getNumStepsTaken () const
 Get the total number of steps that have been successfully taken since the last call to resetAllStatistics(). More...
 
int getNumRealizations () const
 Get the total number of state realizations that have been performed since the last call to resetAllStatistics(). More...
 
int getNumQProjections () const
 Get the total number of times a state positions Q have been projected since the last call to resetAllStatistics(). More...
 
int getNumUProjections () const
 Get the total number of times a state velocities U have been projected since the last call to resetAllStatistics(). More...
 
int getNumProjections () const
 Get the total number of times a state has been projected (counting both Q and U projections) since the last call to resetAllStatistics(). More...
 
int getNumErrorTestFailures () const
 Get the number of attempted steps that have failed due to the error being unacceptably high since the last call to resetAllStatistics(). More...
 
int getNumConvergenceTestFailures () const
 Get the number of attempted steps that failed due to non-convergence of internal step iterations. More...
 
int getNumRealizationFailures () const
 Get the number of attempted steps that have failed due to an error when realizing the state since the last call to resetAllStatistics(). More...
 
int getNumQProjectionFailures () const
 Get the number of attempted steps that have failed due to an error when projecting the state positions (Q) since the last call to resetAllStatistics(). More...
 
int getNumUProjectionFailures () const
 Get the number of attempted steps that have failed due to an error when projecting the state velocities (U) since the last call to resetAllStatistics(). More...
 
int getNumProjectionFailures () const
 Get the number of attempted steps that have failed due to an error when projecting the state (either a Q- or U-projection) since the last call to resetAllStatistics(). More...
 
int getNumConvergentIterations () const
 For iterative methods, get the number of internal step iterations in steps that led to convergence (not necessarily successful steps). More...
 
int getNumDivergentIterations () const
 For iterative methods, get the number of internal step iterations in steps that did not lead to convergence. More...
 
int getNumIterations () const
 For iterative methods, this is the total number of internal step iterations taken regardless of whether those iterations led to convergence or to successful steps. More...
 
void setFinalTime (Real tFinal)
 Set the time at which the simulation should end. More...
 
void setInitialStepSize (Real hinit)
 Set the initial step size that should be attempted. More...
 
void setMinimumStepSize (Real hmin)
 Set the minimum step size that should ever be used. More...
 
void setMaximumStepSize (Real hmax)
 Set the maximum step size that should ever be used. More...
 
void setFixedStepSize (Real stepSize)
 Set the integrator to use a single fixed step size for all steps. More...
 
void setAccuracy (Real accuracy)
 Set the overall accuracy that should be used for integration. More...
 
void setConstraintTolerance (Real consTol)
 Set the tolerance within which constraints must be satisfied. More...
 
void setUseInfinityNorm (bool useInfinityNorm)
 (Advanced) Use infinity norm (maximum absolute value) instead of default RMS norm to evaluate whether accuracy has been achieved for states and for constraint tolerance. More...
 
bool isInfinityNormInUse () const
 (Advanced) Are we currently using the infinity norm? More...
 
void setInternalStepLimit (int nSteps)
 Set the maximum number of steps that may be taken within a single call to stepTo() or stepBy(). More...
 
void setReturnEveryInternalStep (bool shouldReturn)
 Set whether the Integrator should return from stepTo() or stepBy() after every internal step, even if no event has occurred and the report time has not been reached. More...
 
void setProjectEveryStep (bool forceProject)
 Set whether the system should be projected back to the constraint manifold after every step. More...
 
void setAllowInterpolation (bool shouldInterpolate)
 Set whether the Integrator is permitted to return interpolated states for reporting purposes which may be less accurate than the "real" states that form the trajectory. More...
 
void setProjectInterpolatedStates (bool shouldProject)
 Set whether interpolated states should be projected back to the constraint manifold after interpolation is performed. More...
 
void setForceFullNewton (bool forceFullNewton)
 (Advanced) Constraint projection may use an out-of-date iteration matrix for efficiency. More...
 

Additional Inherited Members

- Public Types inherited from SimTK::Integrator
enum  SuccessfulStepStatus {
  ReachedReportTime =1,
  ReachedEventTrigger =2,
  ReachedScheduledEvent =3,
  TimeHasAdvanced =4,
  ReachedStepLimit =5,
  EndOfSimulation =6,
  StartOfContinuousInterval =7,
  InvalidSuccessfulStepStatus = -1
}
 When a step is successful, it will return an indication of what caused it to stop where it did. More...
 
enum  TerminationReason {
  ReachedFinalTime = 1,
  AnUnrecoverableErrorOccurred = 2,
  EventHandlerRequestedTermination = 3,
  InvalidTerminationReason = -1
}
 Once the simulation has ended, getTerminationReason() may be called to find out what caused it to end. More...
 
- Static Public Member Functions inherited from SimTK::Integrator
static String getSuccessfulStepStatusString (SuccessfulStepStatus)
 Get a human readable description of the reason a step returned. More...
 
static String getTerminationReasonString (TerminationReason)
 Get a human readable description of the termination reason. More...
 
static String successfulStepStatusString (SuccessfulStepStatus stat)
 OBSOLETE: use getSuccessfulStepStatusString(). More...
 
- Protected Member Functions inherited from SimTK::Integrator
const IntegratorRepgetRep () const
 
IntegratorRepupdRep ()
 
- Protected Attributes inherited from SimTK::Integrator
IntegratorReprep
 

Detailed Description

This is an implementation of a variable-step, first-order semi-explicit Euler method, also known as semi-implicit Euler or symplectic Euler.

The fixed-step, first-order semi-explicit Euler method is very popular for game engines such as ODE, and Simbody offers that method as SemiExplicitEulerIntegrator. See the documentation there for a discussion and theory. This integrator is an attempt to extend that method to give some error control. For equivalent performance to the fixed-step method, this one needs to run at twice the step size (because it takes two substeps). Be sure to set its maximum allowable step large enough, and use a very loose accuracy setting.

Theory

See SemiExplicitEulerIntegrator for the theory behind the underlying first order method. Here we use Richardson Extrapolation (step doubling) to get an error estimate. See Solving Ordinary Differential Equations I: Nonstiff Problems, 2nd rev. ed., Hairer, Norsett, & Wanner, section II.4, pp 164-165. Note that we are not using the local extrapolation trick to get a higher-order result; see below for why.

The idea is to take two steps of length h, and a single big step of length 2h, and combine the results. Starting at t=t0 we can get to t2=t0+2h two different ways:

    u1 = u0 + h udot(q0,u0)              ub = u0 + 2h udot(q0,u0)
    q1 = q0 + h N(q0)u1         and      qb = q0 + 2h N(q0)ub
    u2 = u1 + h udot(q1,u1)                  (b = big step)
    q2 = q1 + h N(q1)u2

Note that we can use udot(q0,u0) in both methods so it doesn't cost much to calculate both solutions y2(t2)=(q2,u2) and yb(t2)=(qb,ub).

Now assume the true solution at t2 is y(t2)=(q,u). Then

    y = y2 + 2C h^2  + O(h^3)
    y = yb + C(2h)^2 + O(h^3)

where C is some unknown constant of the underlying method. Ignoring the 3rd order terms, subtract these two equations to get:

    y2-yb = 2Ch^2

which is the 2nd order error term for y2. We can use that for error control.

Hairer suggests using that error term to improve on y2 to get a better estimate for y (this is called "local extrapolation") :

    y2' = y2 + (y2-yb) = 2 y2 - yb
    y   = y2' + O(h^3)                  <-- we don't actually do this

y2' is a 2nd order accurate estimate for y(t2). But ... we don't have an error estimate for the revised value and we don't actually know that it is more accurate. In fact, although this sounds lovely in theory, in practice we will often be running at close to a stability boundary and using the "big step" value to update the result causes stability problems. So we'll skip the local extrapolation and stick with the first order result from the two half-steps.

Author
Michael Sherman

Constructor & Destructor Documentation

SimTK::SemiExplicitEuler2Integrator::SemiExplicitEuler2Integrator ( const System sys)

Create a SemiExplicitEuler2Integrator for integrating a System with variable size steps.


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