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
F Î IÁ A7 Î Î ¶ µ e2 Ì ½6 ÃJ ÿÿÿÿ °Ûþ ¿Ê …8 q2 L F ô F ¸ ½6 F ½6 p IÁ IÁ Î IÁ IÁ IÁ IÁ IÁ C7 C7 Î IÁ IÁ IÁ IÁ IÁ IÁ IÁ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ ÿÿÿÿ F IÁ IÁ IÁ IÁ IÁ IÁ IÁ IÁ IÁ â Michael Peter Eastman Permission is hereby free of to any person obtaining a copy of this to deal in the Document without including without limitation the rights to and or sell copies of the and to permit persons to whom the Document is furnished to do subject to the following WITHOUT WARRANTY OF ANY EXPRESS OR INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DAMAGES OR OTHER WHETHER IN AN ACTION OF TORT OR ARISING OUT OF OR IN CONNECTION WITH THE DOCUMENT OR THE USE OR OTHER DEALINGS IN THE DOCUMENT Acknowledgment SimTK software and all related activities are funded by the HYPERLINK vectors and matrices PAGEREF _Toc251069768 h HYPERLINK l _Toc251069769 Linear algebra PAGEREF _Toc251069769 h HYPERLINK l _Toc251069770 Solving Linear Systems(SimTK::FactorLU)PAGEREF _Toc251069770\h5HYPERLINK\l"_Toc251069771"3.2 Linear Least Squares(SimTK otherwise the best guess is that tevent is in the middle of the window Finite width localization windows create a likelihood that multiple events will occur within the same window We cannot say with certainty in what order these events so for precise treatment they must be considered simultaneous If an approximate ordering is acceptable then the integrator’s tevent guesses can be used to order the events within the but even those may be identical for some and in any case the integrator cannot guarantee that the events actually occurred in the order they appear when sorted by estimated time of occurrence If more precise information is then the localization window must be made at the cost of increased computation time Once an event has been localized to an acceptable the integrator’s stepTo() method will return control to the time stepper at time tlow
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. ...
that it contains events that have triggered but have not been processed Thus it is not a legitimate point along the system’s trajectory and should never be returned to the caller For discussion we label this “improper” state EMBED Equation DSMT4 The event handler will correct the state creating a modified state with time still at thigh but not triggering any events We label the modified state EMBED Equation DSMT4 Once the system’s handler the state EMBED Equation DSMT4 can be output as part of the trajectory and used as the initial condition for the next continuous interval Thus the time stepper generates the sequence of legitimate trajectory points just prior to event immediately followed by EMBED Equation DSMT4 which is the time at which the but after the event handler has modified the state to deal with those events Consecutive intervals I and I will consist of trajectory points EMBED Equation DSMT4 with round brackets indicating that EMBED Equation DSMT4 is not part of the trajectory Event handlers Event handlers are solvers which are able to take a state in an resolve the set up appropriate event triggers for the next interval
Definition: SimmathUserGuide.doc:219
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