Simbody  3.7
System.h
Go to the documentation of this file.
1 #ifndef SimTK_SimTKCOMMON_SYSTEM_H_
2 #define SimTK_SimTKCOMMON_SYSTEM_H_
3 
4 /* -------------------------------------------------------------------------- *
5  * Simbody(tm): SimTKcommon *
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-13 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: Peter Eastman *
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 
27 #include "SimTKcommon/basics.h"
28 #include "SimTKcommon/Simmatrix.h"
32 
33 #include <cassert>
34 
35 namespace SimTK {
36 
37 class DecorativeGeometry;
38 class DefaultSystemSubsystem;
39 class ScheduledEventHandler;
40 class ScheduledEventReporter;
41 class TriggeredEventHandler;
42 class TriggeredEventReporter;
43 class RealizeOptions;
44 class RealizeResults;
45 class ProjectOptions;
46 class ProjectResults;
47 
48 //==============================================================================
49 // SYSTEM
50 //==============================================================================
98 public:
99 class Guts; // local; name is System::Guts
100 
101 
102 //------------------------------------------------------------------------------
125 System& setUpDirection(const CoordinateDirection& up);
126 
134 System& setUseUniformBackground(bool useUniformBackground);
135 
149 System& setDefaultTimeScale(Real tc);
150 
158 System& setDefaultLengthScale(Real lc);
159 
165 void setHasTimeAdvancedEvents(bool); // default=false
166 
168 CoordinateDirection getUpDirection() const;
171 bool getUseUniformBackground() const;
174 Real getDefaultTimeScale() const;
177 Real getDefaultLengthScale() const;
180 bool hasTimeAdvancedEvents() const;
184 //------------------------------------------------------------------------------
193 inline void addEventHandler(ScheduledEventHandler* handler);
196 inline void addEventHandler(TriggeredEventHandler* handler);
199 inline void addEventReporter(ScheduledEventReporter* handler) const;
202 inline void addEventReporter(TriggeredEventReporter* handler) const;
206 //------------------------------------------------------------------------------
235 const State& realizeTopology() const;
236 
251 const State& getDefaultState() const;
254 State& updDefaultState();
255 
274 void realizeModel(State& state) const;
275 
283 void realize(const State& state, Stage stage = Stage::HighestRuntime) const;
287 //------------------------------------------------------------------------------
368 void project(State& state, Real accuracy=-1) const;
369 
385 void projectQ(State& state, Real accuracy=-1) const;
386 
404 void projectU(State& state, Real accuracy=-1) const;
405 
441 void projectQ(State& state, Vector& qErrEst,
442  const ProjectOptions& options, ProjectResults& results) const;
443 
467 void projectU(State& state, Vector& uErrEst,
468  const ProjectOptions& options, ProjectResults& results) const;
469 
470 
488 void prescribe(State& state) const {
489  realize(state, Stage::Time);
490  prescribeQ(state);
491  realize(state, Stage::Position);
492  prescribeU(state);
493 }
494 
513 bool prescribeQ(State& state) const;
514 
530 bool prescribeU(State& state) const;
531 
537 void getFreeQIndex(const State& state, Array_<SystemQIndex>& freeQs) const;
538 
544 void getFreeUIndex(const State& state, Array_<SystemUIndex>& freeUs) const;
548 //------------------------------------------------------------------------------
587 void handleEvents(State& state,
588  Event::Cause cause,
589  const Array_<EventId>& eventIds,
590  const HandleEventsOptions& options,
591  HandleEventsResults& results) const;
592 
596 void reportEvents(const State& state,
597  Event::Cause cause,
598  const Array_<EventId>& eventIds) const;
599 
608 void calcEventTriggerInfo(const State& state,
609  Array_<EventTriggerInfo>& triggerInfo) const;
610 
616 void calcTimeOfNextScheduledEvent(const State& state,
617  Real& tNextEvent,
618  Array_<EventId>& eventIds,
619  bool includeCurrentTime) const;
620 
624 void calcTimeOfNextScheduledReport(const State& state,
625  Real& tNextEvent,
626  Array_<EventId>& eventIds,
627  bool includeCurrentTime) const;
631 //------------------------------------------------------------------------------
660 void relax(State& state, Stage stage, Real accuracy=-1) const;
664 //------------------------------------------------------------------------------
685 void multiplyByN(const State& state, const Vector& u,
686  Vector& dq) const;
688 void multiplyByNTranspose(const State& state, const Vector& fq,
689  Vector& fu) const;
691 void multiplyByNPInv(const State& state, const Vector& dq,
692  Vector& u) const;
694 void multiplyByNPInvTranspose(const State& state, const Vector& fu,
695  Vector& fq) const;
699 //------------------------------------------------------------------------------
709 void resetAllCountersToZero();
710 
711  // Realization
712 
716 int getNumRealizationsOfThisStage(Stage) const;
717 
721 int getNumRealizeCalls() const;
722 
723  // Prescribed motion
724 
726 int getNumPrescribeQCalls() const;
728 int getNumPrescribeUCalls() const;
729 
730  // Projection
731 
734 int getNumProjectQCalls() const;
736 int getNumFailedProjectQCalls() const;
739 int getNumQProjections() const;
742 int getNumQErrorEstimateProjections() const;
743 
746 int getNumProjectUCalls() const;
748 int getNumFailedProjectUCalls() const;
751 int getNumUProjections() const;
754 int getNumUErrorEstimateProjections() const;
755 
756  // Event handling and reporting
757 
761 int getNumHandlerCallsThatChangedStage(Stage) const;
762 
765 int getNumHandleEventCalls() const;
766 
769 int getNumReportEventCalls() const;
773 //------------------------------------------------------------------------------
780 System() : guts(0) { }
782 System(const System&);
784 System& operator=(const System&);
787 ~System();
788 
790 const String& getName() const;
792 const String& getVersion() const;
793 
796 SubsystemIndex adoptSubsystem(Subsystem& child);
797 
799 int getNumSubsystems() const;
801 const Subsystem& getSubsystem(SubsystemIndex) const;
803 Subsystem& updSubsystem(SubsystemIndex);
806 const DefaultSystemSubsystem& getDefaultSubsystem() const;
809 DefaultSystemSubsystem& updDefaultSubsystem();
810 
814 inline operator const Subsystem&() const; // implemented below
818 inline operator Subsystem&();
819 
824 bool systemTopologyHasBeenRealized() const;
825 
833 StageVersion getSystemTopologyCacheVersion() const;
834 
840 void setSystemTopologyCacheVersion(StageVersion topoVersion) const;
841 
851 void invalidateSystemTopologyCache() const;
852 
860 void calcDecorativeGeometryAndAppend(const State&, Stage,
862 
863 
866 bool isSameSystem(const System& otherSystem) const;
867 
868 
872 const Guts& getSystemGuts() const {assert(guts); return *guts;}
876 Guts& updSystemGuts() {assert(guts); return *guts;}
877 
881 void adoptSystemGuts(System::Guts* g);
882 
884 explicit System(System::Guts* g) : guts(g) { }
886 bool hasGuts() const {return guts!=0;}
887 
889 bool isOwnerHandle() const;
891 bool isEmptyHandle() const;
894 private:
895 friend class Guts;
896 // This is the only data member in this class. Also, any class derived from
897 // System must have *NO* data members at all (data goes in the Guts class).
898 Guts* guts;
899 };
900 
901 
911 public:
912  explicit DefaultSystemSubsystem(System& sys);
913  void addEventHandler(ScheduledEventHandler* handler);
914  void addEventHandler(TriggeredEventHandler* handler);
915  void addEventReporter(ScheduledEventReporter* handler) const;
916  void addEventReporter(TriggeredEventReporter* handler) const;
917  EventId createEventId(SubsystemIndex subsys, const State& state) const;
918  void findSubsystemEventIds
919  (SubsystemIndex subsys, const State& state,
920  const Array_<EventId>& allEvents,
921  Array_<EventId>& eventsForSubsystem) const;
922  // don't let doxygen see this private class
924  class Guts;
926 private:
927  const Guts& getGuts() const;
928  Guts& updGuts();
929 };
930 
932 { updDefaultSubsystem().addEventHandler(handler); }
934 { updDefaultSubsystem().addEventHandler(handler); }
939 
940 inline System::operator const Subsystem&() const {return getDefaultSubsystem();}
941 inline System::operator Subsystem&() {return updDefaultSubsystem();}
942 
943 
944 //==============================================================================
945 // PROJECT OPTIONS and PROJECT RESULTS
946 //==============================================================================
951 public:
952  enum Option {
954  None = 0x0000,
959  LocalOnly = 0x0001,
963  DontThrow = 0x0002,
966  UseInfinityNorm = 0x0004,
970  ForceProjection = 0x0008,
975  };
976 
982  explicit ProjectOptions(Real accuracy)
983  { clear(); setRequiredAccuracy(accuracy); }
986  explicit ProjectOptions(Option opt)
987  { clear(); setOption(opt); }
988 
993  { optionSet=0; setAccuracyDefaults(); return *this; }
994 
1000  requiredAccuracy = accuracy > 0 ? accuracy
1002  return *this;
1003  }
1004 
1008  assert(0 < overshoot && overshoot <= 1);
1009  desiredOvershoot = overshoot;
1010  return *this;
1011  }
1012 
1016  assert(limit > 0);
1017  projectionLimit = limit;
1018  return *this;
1019  }
1020 
1024  { optionSet &= ~(unsigned)opt; return *this; }
1027  { optionSet |= (unsigned)opt; return *this; }
1028 
1030  Real getRequiredAccuracy() const {return requiredAccuracy;}
1033  Real getOvershootFactor() const {return desiredOvershoot;}
1035  Real getProjectionLimit() const {return projectionLimit;}
1036 
1037  bool isOptionSet(Option opt) const {return (optionSet&(unsigned)opt) != 0;}
1038 
1039  static Real getDefaultRequiredAccuracy() {return Real(1e-4);}
1040  static Real getDefaultOvershootFactor() {return Real(0.1);} //i.e., 1e-5
1041 
1042  // Set operators: not, or, and, set difference
1044  { optionSet |= opts.optionSet; return *this; }
1046  { optionSet &= opts.optionSet; return *this; }
1048  { optionSet &= ~opts.optionSet; return *this; }
1049 
1050  ProjectOptions& operator|=(Option opt) {setOption(opt); return *this;}
1051  ProjectOptions& operator-=(Option opt) {clearOption(opt); return *this;}
1052 
1053 private:
1054  Real requiredAccuracy;
1055  Real desiredOvershoot; // try for accuracy*overshoot
1056  Real projectionLimit; // abort if initial norm is worse than this
1057  unsigned optionSet;
1058 
1059  void setAccuracyDefaults() {
1060  requiredAccuracy = getDefaultRequiredAccuracy();
1061  desiredOvershoot = getDefaultOvershootFactor();
1062  projectionLimit = Infinity; // we'll try from however far away
1063  }
1064 };
1065 
1068 public:
1070 
1071  enum Status {
1073  Invalid = -1,
1085  };
1086 
1090  m_exitStatus = Invalid;
1091  m_anyChangeMade = m_projectionLimitExceeded = false;
1092  m_numIterations = 0;
1093  m_worstError = -1;
1094  m_normOnEntrance = m_normOnExit = NaN;
1095  return *this;
1096  }
1097  bool isValid() const {return m_exitStatus != Invalid;}
1098  Status getExitStatus() const {return m_exitStatus;}
1099 
1100  bool getAnyChangeMade() const {assert(isValid());return m_anyChangeMade;}
1101  int getNumIterations() const {assert(isValid());return m_numIterations;}
1102  Real getNormOnEntrance() const {assert(isValid());return m_normOnEntrance;}
1103  Real getNormOnExit() const {assert(isValid());return m_normOnExit;}
1105  { assert(isValid());return m_worstError; }
1107  { assert(isValid());return m_projectionLimitExceeded; }
1108 
1110  { m_exitStatus=status; return *this; }
1112  { m_anyChangeMade=changeMade; return *this; }
1114  { m_projectionLimitExceeded=limitExceeded; return *this; }
1115  ProjectResults& setNumIterations(int numIterations)
1116  { m_numIterations=numIterations; return *this; }
1118  { m_normOnEntrance=norm; m_worstError=worstError; return *this; }
1120  { m_normOnExit=norm; return *this; }
1121 private:
1122  Status m_exitStatus;
1123  bool m_anyChangeMade;
1124  bool m_projectionLimitExceeded;
1125  int m_numIterations;
1126  int m_worstError; // index of worst error on entrance
1127  Real m_normOnEntrance; // in selected rms or infinity norm
1128  Real m_normOnExit;
1129 };
1130 
1131 
1132 
1133 //==============================================================================
1134 // REALIZE OPTIONS and REALIZE RESULTS
1135 //==============================================================================
1138  unsigned int optionSet;
1139  explicit RealizeOptions(unsigned o) : optionSet(o) { }
1140 public:
1141 
1142  enum Option {
1143  None = 0x00,
1144  DontThrow = 0x01
1145  };
1146 
1147 
1148  RealizeOptions() : optionSet(0) { }
1149 
1150  // This is an implicit conversion
1151  RealizeOptions(Option opt) : optionSet((unsigned)opt) { }
1152 
1153  // Implicit conversion to bool when needed
1154  operator bool() const {return optionSet != 0;}
1155  bool isEmpty() const {return optionSet==0;}
1156 
1157  bool isOptionSet(Option opt) const {return (optionSet&(unsigned)opt) != 0;}
1158  void clear() {optionSet=0;}
1159  void clearOption(Option opt) {optionSet &= ~(unsigned)opt;}
1160  void setOption (Option opt) {optionSet |= (unsigned)opt;}
1161 
1162  // Set operators: or, and
1163  RealizeOptions& operator|=(RealizeOptions opts) {optionSet |= opts.optionSet; return *this;}
1164  RealizeOptions& operator&=(RealizeOptions opts) {optionSet &= opts.optionSet; return *this;}
1165 
1166  RealizeOptions& operator|=(Option opt) {setOption(opt); return *this;}
1167  RealizeOptions& operator-=(Option opt) {clearOption(opt); return *this;}
1168 };
1169 
1172 };
1173 
1174 
1175 
1176 
1177 } // namespace SimTK
1178 
1179 #endif // SimTK_SimTKCOMMON_SYSTEM_H_
DefaultSystemSubsystem & updDefaultSubsystem()
Get writable access to the default subsystem which is present in every system.
ScheduledEventReporter is a subclass of EventReporter for events that occur at a particular time that...
Definition: EventReporter.h:72
System(System::Guts *g)
Constructor for internal use only.
Definition: System.h:884
ScheduledEventHandler is a subclass of EventHandler for events that occur at a particular time that i...
Definition: EventHandler.h:84
Definition: System.h:1144
A Subsystem is expected to be part of a larger System and to have interdependencies with other subsys...
Definition: Subsystem.h:55
ProjectResults()
Definition: System.h:1069
void addEventReporter(ScheduledEventReporter *handler) const
Add a ScheduledEventReporter to this System, which takes over ownership of the event reporter object...
Definition: System.h:935
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
Normally a project() method will return immediately after evaluating the norm if it is already at or ...
Definition: System.h:970
A project() method is free to use an out-of-date Jacobian when solving the nonlinear system...
Definition: System.h:974
ProjectResults & setNumIterations(int numIterations)
Definition: System.h:1115
ProjectOptions & operator|=(const ProjectOptions &opts)
Definition: System.h:1043
const Guts & getSystemGuts() const
Obtain a const reference to the System::Guts object to which this handle refers.
Definition: System.h:872
ProjectOptions & operator-=(const ProjectOptions &opts)
Definition: System.h:1047
RealizeOptions & operator|=(RealizeOptions opts)
Definition: System.h:1163
(NOT USED YET) Results for advanced users of realize() methods.
Definition: System.h:1171
ProjectOptions(Real accuracy)
This constructor allows the default accuracy to be overridden while leaving all other options at thei...
Definition: System.h:982
const DefaultSystemSubsystem & getDefaultSubsystem() const
Get read-only access to the default subsystem which is present in every system.
bool hasGuts() const
Return true if this System handle is not empty.
Definition: System.h:886
Definition: Stage.h:84
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
void addEventHandler(ScheduledEventHandler *handler)
Definition: System.h:1143
A CoordinateDirection is a CoordinateAxis plus a direction indicating the positive or negative direct...
Definition: CoordinateAxis.h:244
ProjectOptions(Option opt)
This constructor creates default options except one setting one non-default Option.
Definition: System.h:986
Status getExitStatus() const
Definition: System.h:1098
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
bool isOptionSet(Option opt) const
Definition: System.h:1157
ProjectOptions & setProjectionLimit(Real limit)
Project will fail immediately if the initial norm is greater than the projection limit, with status FailureToConverge.
Definition: System.h:1015
int getWorstErrorOnEntrance() const
Definition: System.h:1104
ProjectResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid...
Definition: System.h:1089
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:606
long long StageVersion
This is the type to use for Stage version numbers that get incremented whenever a state variable chan...
Definition: Stage.h:44
ProjectOptions & clear()
Restore this object to its default-constructed state (no options selected, default accuracy and overs...
Definition: System.h:992
static Real getDefaultOvershootFactor()
Definition: System.h:1040
System()
Default constructor creates an empty handle.
Definition: System.h:780
ProjectResults & setNormOnExit(Real norm)
Definition: System.h:1119
Guts & updSystemGuts()
Obtain a writable reference to the System::Guts object to which this handle refers.
Definition: System.h:876
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:280
const Real NaN
This is the IEEE "not a number" constant for this implementation of the default-precision Real type; ...
ProjectOptions & operator &=(const ProjectOptions &opts)
Definition: System.h:1045
Results for advanced users of project() methods.
Definition: System.h:1067
These are all the possible causes for events.
Definition: Event.h:126
static Real getDefaultRequiredAccuracy()
Definition: System.h:1039
bool getProjectionLimitExceeded() const
Definition: System.h:1106
Options for the advanced project() methods.
Definition: System.h:950
This object has not been filled in yet and holds no results.
Definition: System.h:1073
Real getProjectionLimit() const
Return the maximum norm we&#39;re allowed to attempt to correct.
Definition: System.h:1035
Option
Definition: System.h:1142
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
ProjectResults & setProjectionLimitExceeded(bool limitExceeded)
Definition: System.h:1113
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:53
Real getOvershootFactor() const
Return the factor by which a project() method should try to do better than the required accuracy...
Definition: System.h:1033
Option
Definition: System.h:952
(NOT USED YET) Options for the advanced realize() methods.
Definition: System.h:1137
Real getNormOnExit() const
Definition: System.h:1103
Normally failure to meet the accuracy requirements throws an exception.
Definition: System.h:963
bool isOptionSet(Option opt) const
Definition: System.h:1037
RealizeOptions()
Definition: System.h:1148
ProjectOptions & operator-=(Option opt)
Definition: System.h:1051
Spatial configuration available.
Definition: Stage.h:74
int getNumIterations() const
Definition: System.h:1101
ProjectOptions & setRequiredAccuracy(Real accuracy)
The norm of the constraint errors must be driven to below this value for a project() to be considered...
Definition: System.h:999
void prescribe(State &state) const
Set values for prescribed positions q and velocities u.
Definition: System.h:488
The abstract parent of all Subsystem implementation classes.
Definition: SubsystemGuts.h:47
float norm(const conjugate< float > &c)
Definition: conjugate.h:486
The Newton iterations were diverging.
Definition: System.h:1084
This option says we expect the state to be close to a solution already and restricts projection to mo...
Definition: System.h:959
RealizeOptions & operator-=(Option opt)
Definition: System.h:1167
void addEventHandler(ScheduledEventHandler *handler)
Add a ScheduledEventHandler to this System, which takes over ownership of the event handler object...
Definition: System.h:931
ProjectResults & setAnyChangeMade(bool changeMade)
Definition: System.h:1111
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
ProjectResults & setExitStatus(Status status)
Definition: System.h:1109
Use the stricter infinity (max absolute value) norm rather than the default RMS norm to determine whe...
Definition: System.h:966
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
Declares the user-visible part of a SimTK::State, the implementation is done in a separate internal c...
This is the declaration for the System::Guts class, the abstract object to which a System handle poin...
Definition: SystemGuts.h:71
Real getNormOnEntrance() const
Definition: System.h:1102
Status
Definition: System.h:1071
TriggeredEventHandler is a subclass of EventHandler for events that occur when some condition is sati...
Definition: EventHandler.h:109
RealizeOptions & operator &=(RealizeOptions opts)
Definition: System.h:1164
bool isValid() const
Definition: System.h:1097
ProjectOptions & setOption(Option opt)
Set a particular option.
Definition: System.h:1026
This is the base class that serves as the parent of all SimTK System objects; most commonly Simbody&#39;s...
Definition: System.h:97
void clear()
Definition: System.h:1158
void clearOption(Option opt)
Definition: System.h:1159
bool getAnyChangeMade() const
Definition: System.h:1100
ProjectOptions()
Default constructor sets options to their default values.
Definition: System.h:978
bool isEmpty() const
Definition: System.h:1155
Provide a unique integer type for identifying Subsystems.
This is a concrete Subsystem that is part of every System. It provides a variety of services for the ...
Definition: System.h:910
Real getRequiredAccuracy() const
Return the current value for the required accuracy option.
Definition: System.h:1030
Results returned by the handleEvent() method.
Definition: Event.h:345
A new time has been realized.
Definition: Stage.h:73
This is the header which should be included in user programs that would like to make use of all the S...
Take all defaults.
Definition: System.h:954
void addEventReporter(ScheduledEventReporter *handler) const
TriggeredEventReporter is a subclass of EventReporter for events that occur when some condition is sa...
Definition: EventReporter.h:96
Includes internal headers providing declarations for the basic SimTK Core classes.
ProjectOptions & setOvershootFactor(Real overshoot)
Project will attempt to reach accuracy*overshoot but settle for just accuracy.
Definition: System.h:1007
ProjectOptions & clearOption(Option opt)
Remove a given option from the set.
Definition: System.h:1023
RealizeOptions(Option opt)
Definition: System.h:1151
RealizeOptions & operator|=(Option opt)
Definition: System.h:1166
ProjectOptions & operator|=(Option opt)
Definition: System.h:1050
ProjectResults & setNormOnEntrance(Real norm, int worstError)
Definition: System.h:1117
void setOption(Option opt)
Definition: System.h:1160
Options for the handleEvent() method.
Definition: Event.h:269
Projection converged but was unable to achieve the required accuracy.
Definition: System.h:1079
This is a class to represent unique IDs for events in a type-safe way.