Simbody  3.5
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) { }
119  ~Integrator();
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 
176  State& updAdvancedState();
177 
180  Real getAccuracyInUse() const;
183  Real getConstraintToleranceInUse() const;
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  };
221  static String getSuccessfulStepStatusString(SuccessfulStepStatus);
222 
226  SuccessfulStepStatus stepTo(Real reportTime, Real scheduledEventTime=Infinity);
230  SuccessfulStepStatus stepBy(Real interval, Real scheduledEventTime=Infinity);
231 
232 
235  Vec2 getEventWindow() const;
238  const Array_<EventId>& getTriggeredEvents() const;
241  const Array_<Real>& getEstimatedEventTimes() const;
244  const Array_<Event::Trigger>& getEventTransitionsSeen() const;
245 
246 
247  // TERMINATION //
248 
252  ReachedFinalTime = 1,
254  AnUnrecoverableErrorOccurred = 2,
256  EventHandlerRequestedTermination = 3,
258  InvalidTerminationReason = -1
259  };
260 
263  bool isSimulationOver() const;
264 
267  TerminationReason getTerminationReason() const;
268 
270  static String getTerminationReasonString(TerminationReason);
271 
273  void resetAllStatistics();
274 
276  Real getActualInitialStepSizeTaken() const;
277 
279  Real getPreviousStepSizeTaken() const;
280 
282  Real getPredictedNextStepSize() const;
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;
302  int getNumErrorTestFailures() const;
307  int getNumConvergenceTestFailures() const;
310  int getNumRealizationFailures() const;
314  int getNumQProjectionFailures() const;
318  int getNumUProjectionFailures() const;
322  int getNumProjectionFailures() const;
325  int getNumConvergentIterations() const;
328  int getNumDivergentIterations() const;
332  int getNumIterations() const;
333 
336  void setFinalTime(Real tFinal);
339  void setInitialStepSize(Real hinit);
342  void setMinimumStepSize(Real hmin);
345  void setMaximumStepSize(Real hmax);
346 
352  void setFixedStepSize(Real stepSize);
353 
357  void setAccuracy(Real accuracy);
359  void setConstraintTolerance(Real consTol);
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_
const IntegratorRep & getRep() const
Definition: Integrator.h:409
IntegratorRep * rep
Definition: Integrator.h:413
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
An Integrator is an object that can advance the State of a System through time.
Definition: Integrator.h:116
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:50
Real getTime() const
Get the time of the current State. This is equivalent to calling getState().getTime().
Definition: Integrator.h:162
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:593
Integrator()
Definition: Integrator.h:118
static String successfulStepStatusString(SuccessfulStepStatus stat)
OBSOLETE: use getSuccessfulStepStatusString().
Definition: Integrator.h:405
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:276
Includes internal headers providing declarations for the basic SimTK Core classes, including Simmatrix.
The SimTK::Array_<T> container class is a plug-compatible replacement for the C++ standard template l...
Definition: Array.h:50
TerminationReason
Once the simulation has ended, getTerminationReason() may be called to find out what caused it to end...
Definition: Integrator.h:250
IntegratorRep & updRep()
Definition: Integrator.h:410
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
This is the header file that every Simmath compilation unit should include first. ...
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
SuccessfulStepStatus
When a step is successful, it will return an indication of what caused it to stop where it did...
Definition: Integrator.h:202
const Real & getTime() const
You can call these as long as *system* stage >= Model.
Real getAdvancedTime() const
Get the time of the advanced State. This is equivalent to calling getAdvancedState().getTime().
Definition: Integrator.h:173
#define SimTK_SIMMATH_EXPORT
Definition: SimTKmath/include/simmath/internal/common.h:64