Simbody  3.8
Integrator.h
Go to the documentation of this file.
1 #ifndef SimTK_SIMMATH_INTEGRATOR_H_
2 #define SimTK_SIMMATH_INTEGRATOR_H_
3 
4 /* -------------------------------------------------------------------------- *
5  * Simbody(tm): SimTKmath *
6  * -------------------------------------------------------------------------- *
7  * This is part of the SimTK biosimulation toolkit originating from *
8  * Simbios, the NIH National Center for Physics-Based Simulation of *
9  * Biological Structures at Stanford, funded under the NIH Roadmap for *
10  * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody. *
11  * *
12  * Portions copyright (c) 2006-12 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: *
15  * *
16  * Licensed under the Apache License, Version 2.0 (the "License"); you may *
17  * not use this file except in compliance with the License. You may obtain a *
18  * copy of the License at http://www.apache.org/licenses/LICENSE-2.0. *
19  * *
20  * Unless required by applicable law or agreed to in writing, software *
21  * distributed under the License is distributed on an "AS IS" BASIS, *
22  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
23  * See the License for the specific language governing permissions and *
24  * limitations under the License. *
25  * -------------------------------------------------------------------------- */
26 
32 #include "SimTKcommon.h"
34 
35 namespace SimTK {
36 
37 
38 class IntegratorRep;
39 
117 public:
118  Integrator() : rep(0) { }
120 
121  // These are the exceptions that can be thrown by this class.
122 
123  class InitializationFailed;
124  class StepSizeTooSmall;
125  class StepFailed;
126  class TriedToAdvancePastFinalTime;
127  class CantAskForEventInfoWhenNoEventTriggered;
128 
130  const char* getMethodName() const;
132  int getMethodMinOrder() const;
134  int getMethodMaxOrder() const;
138  bool methodHasErrorControl() const;
139 
143  void initialize(const State& state);
144 
156  void reinitialize(Stage stage, bool shouldTerminate);
157 
160  const State& getState() const;
162  Real getTime() const {return getState().getTime();}
163 
166  bool isStateInterpolated() const;
167 
171  const State& getAdvancedState() const;
173  Real getAdvancedTime() const {return getAdvancedState().getTime();}
174 
177 
184 
204  ReachedReportTime =1,
206  ReachedEventTrigger =2,
208  ReachedScheduledEvent=3,
210  TimeHasAdvanced =4,
212  ReachedStepLimit =5,
214  EndOfSimulation =6,
217  StartOfContinuousInterval=7,
218  InvalidSuccessfulStepStatus = -1
219  };
222 
226  SuccessfulStepStatus stepTo(Real reportTime, Real scheduledEventTime=Infinity);
230  SuccessfulStepStatus stepBy(Real interval, Real scheduledEventTime=Infinity);
231 
232 
245 
246 
247  // TERMINATION //
248 
252  ReachedFinalTime = 1,
254  AnUnrecoverableErrorOccurred = 2,
256  EventHandlerRequestedTermination = 3,
258  InvalidTerminationReason = -1
259  };
260 
263  bool isSimulationOver() const;
264 
268 
271 
274 
277 
280 
283 
286  int getNumStepsAttempted() const;
288  int getNumStepsTaken() const;
290  int getNumRealizations() const;
293  int getNumQProjections() const;
296  int getNumUProjections() const;
299  int getNumProjections() const;
332  int getNumIterations() const;
333 
336  void setFinalTime(Real tFinal);
346 
352  void setFixedStepSize(Real stepSize);
353 
357  void setAccuracy(Real accuracy);
364  void setUseInfinityNorm(bool useInfinityNorm);
366  bool isInfinityNormInUse() const;
367 
368 
373  void setInternalStepLimit(int nSteps);
374 
378  void setReturnEveryInternalStep(bool shouldReturn);
379 
383  void setProjectEveryStep(bool forceProject);
394  void setAllowInterpolation(bool shouldInterpolate);
398  void setProjectInterpolatedStates(bool shouldProject);
402  void setForceFullNewton(bool forceFullNewton);
403 
406  { return getSuccessfulStepStatusString(stat); }
407 
408 protected:
409  const IntegratorRep& getRep() const {assert(rep); return *rep;}
410  IntegratorRep& updRep() {assert(rep); return *rep;}
411 
412  // opaque implementation for binary compatibility
413  IntegratorRep* rep;
414  friend class IntegratorRep;
415 };
416 
417 } // namespace SimTK
418 
419 #endif // SimTK_SIMMATH_INTEGRATOR_H_
Includes internal headers providing declarations for the basic SimTK Core classes,...
This is the header file that every Simmath compilation unit should include first.
#define SimTK_SIMMATH_EXPORT
Definition: SimTKmath/include/simmath/internal/common.h:64
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:1520
An Integrator is an object that can advance the State of a System through time.
Definition: Integrator.h:116
Real getPreviousStepSizeTaken() const
Get the size of the most recent successful step.
int getMethodMinOrder() const
Get the minimum order this Integrator may use.
int getNumStepsAttempted() const
Get the total number of steps that have been attempted (successfully or unsuccessfully) since the las...
Real getTime() const
Get the time of the current State. This is equivalent to calling getState().getTime().
Definition: Integrator.h:162
const State & getState() const
Return a State corresponding to the "current" time at the end of the last call to stepTo() or stepBy(...
const Array_< Real > & getEstimatedEventTimes() const
Get the estimated times of all events which have been localized within the event window.
const Array_< Event::Trigger > & getEventTransitionsSeen() const
Get EventTriggers describing the events which have been localized within the event window.
TerminationReason
Once the simulation has ended, getTerminationReason() may be called to find out what caused it to end...
Definition: Integrator.h:250
bool isSimulationOver() const
Get whether the simulation has terminated.
int getNumRealizationFailures() const
Get the number of attempted steps that have failed due to an error when realizing the state since the...
int getNumQProjections() const
Get the total number of times a state positions Q have been projected since the last call to resetAll...
Real getAccuracyInUse() const
Get the accuracy which is being used for error control.
void setForceFullNewton(bool forceFullNewton)
(Advanced) Constraint projection may use an out-of-date iteration matrix for efficiency.
void setFixedStepSize(Real stepSize)
Set the integrator to use a single fixed step size for all steps.
const State & getAdvancedState() const
Return the state representing the trajectory point to which the integrator has irreversibly advanced.
int getNumUProjectionFailures() const
Get the number of attempted steps that have failed due to an error when projecting the state velociti...
void setMinimumStepSize(Real hmin)
Set the minimum step size that should ever be used.
IntegratorRep & updRep()
Definition: Integrator.h:410
const IntegratorRep & getRep() const
Definition: Integrator.h:409
void setReturnEveryInternalStep(bool shouldReturn)
Set whether the Integrator should return from stepTo() or stepBy() after every internal step,...
void setInitialStepSize(Real hinit)
Set the initial step size that should be attempted.
bool isStateInterpolated() const
Get whether getState() will return an interpolated state or just the same thing as getAdvancedState()...
SuccessfulStepStatus
When a step is successful, it will return an indication of what caused it to stop where it did.
Definition: Integrator.h:202
bool methodHasErrorControl() const
Get whether this Integrator provides error control.
void initialize(const State &state)
Supply the integrator with a starting state.
static String successfulStepStatusString(SuccessfulStepStatus stat)
OBSOLETE: use getSuccessfulStepStatusString().
Definition: Integrator.h:405
Vec2 getEventWindow() const
Get the window (tLow, tHigh] within which one or more events have been localized.
void setAccuracy(Real accuracy)
Set the overall accuracy that should be used for integration.
int getNumStepsTaken() const
Get the total number of steps that have been successfully taken since the last call to resetAllStatis...
void setInternalStepLimit(int nSteps)
Set the maximum number of steps that may be taken within a single call to stepTo() or stepBy().
int getMethodMaxOrder() const
Get the maximum order this Integrator may use.
const char * getMethodName() const
Get the name of this integration method.
bool isInfinityNormInUse() const
(Advanced) Are we currently using the infinity norm?
void resetAllStatistics()
Reset all statistics to zero.
int getNumConvergentIterations() const
For iterative methods, get the number of internal step iterations in steps that led to convergence (n...
int getNumDivergentIterations() const
For iterative methods, get the number of internal step iterations in steps that did not lead to conve...
SuccessfulStepStatus stepBy(Real interval, Real scheduledEventTime=Infinity)
Integrate the System until something happens which requires outside processing, and return a status c...
TerminationReason getTerminationReason() const
Get the reason the simulation terminated.
int getNumProjectionFailures() const
Get the number of attempted steps that have failed due to an error when projecting the state (either ...
int getNumConvergenceTestFailures() const
Get the number of attempted steps that failed due to non-convergence of internal step iterations.
static String getTerminationReasonString(TerminationReason)
Get a human readable description of the termination reason.
void setProjectEveryStep(bool forceProject)
Set whether the system should be projected back to the constraint manifold after every step.
int getNumProjections() const
Get the total number of times a state has been projected (counting both Q and U projections) since th...
void reinitialize(Stage stage, bool shouldTerminate)
After an event handler has made a discontinuous change to the Integrator's "advanced state",...
void setUseInfinityNorm(bool useInfinityNorm)
(Advanced) Use infinity norm (maximum absolute value) instead of default RMS norm to evaluate whether...
int getNumRealizations() const
Get the total number of state realizations that have been performed since the last call to resetAllSt...
Integrator()
Definition: Integrator.h:118
void setFinalTime(Real tFinal)
Set the time at which the simulation should end.
Real getPredictedNextStepSize() const
Get the step size that will be attempted first on the next call to stepTo() or stepBy().
int getNumErrorTestFailures() const
Get the number of attempted steps that have failed due to the error being unacceptably high since the...
void setProjectInterpolatedStates(bool shouldProject)
Set whether interpolated states should be projected back to the constraint manifold after interpolati...
void setConstraintTolerance(Real consTol)
Set the tolerance within which constraints must be satisfied.
State & updAdvancedState()
Get a non-const reference to the advanced state.
int getNumUProjections() const
Get the total number of times a state velocities U have been projected since the last call to resetAl...
int getNumQProjectionFailures() const
Get the number of attempted steps that have failed due to an error when projecting the state position...
Real getConstraintToleranceInUse() const
Get the constraint tolerance which is being used for error control.
int getNumIterations() const
For iterative methods, this is the total number of internal step iterations taken regardless of wheth...
SuccessfulStepStatus stepTo(Real reportTime, Real scheduledEventTime=Infinity)
Integrate the System until something happens which requires outside processing, and return a status c...
void setAllowInterpolation(bool shouldInterpolate)
Set whether the Integrator is permitted to return interpolated states for reporting purposes which ma...
Real getAdvancedTime() const
Get the time of the advanced State. This is equivalent to calling getAdvancedState()....
Definition: Integrator.h:173
const Array_< EventId > & getTriggeredEvents() const
Get the IDs of all events which have been localized within the event window.
void setMaximumStepSize(Real hmax)
Set the maximum step size that should ever be used.
static String getSuccessfulStepStatusString(SuccessfulStepStatus)
Get a human readable description of the reason a step returned.
IntegratorRep * rep
Definition: Integrator.h:413
Real getActualInitialStepSizeTaken() const
Get the size of the first successful step after the last initialize() call.
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:280
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:65
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
SimTK_Real Real
This is the default compiled-in floating point type for SimTK, either float or double.
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:607