1 #ifndef SimTK_SimTKCOMMON_SYSTEM_H_
2 #define SimTK_SimTKCOMMON_SYSTEM_H_
37 class DecorativeGeometry;
38 class DefaultSystemSubsystem;
39 class ScheduledEventHandler;
40 class ScheduledEventReporter;
41 class TriggeredEventHandler;
42 class TriggeredEventReporter;
619 bool includeCurrentTime)
const;
627 bool includeCurrentTime)
const;
814 inline operator const Subsystem&()
const;
927 const Guts& getGuts()
const;
940 inline System::operator
const Subsystem&()
const {
return getDefaultSubsystem();}
941 inline System::operator
Subsystem&() {
return updDefaultSubsystem();}
993 { optionSet=0; setAccuracyDefaults();
return *
this; }
1000 requiredAccuracy = accuracy > 0 ? accuracy
1008 assert(0 < overshoot && overshoot <= 1);
1009 desiredOvershoot = overshoot;
1017 projectionLimit = limit;
1024 { optionSet &= ~(unsigned)opt;
return *
this; }
1027 { optionSet |= (unsigned)opt;
return *
this; }
1044 { optionSet |= opts.optionSet;
return *
this; }
1046 { optionSet &= opts.optionSet;
return *
this; }
1048 { optionSet &= ~opts.optionSet;
return *
this; }
1054 Real requiredAccuracy;
1055 Real desiredOvershoot;
1056 Real projectionLimit;
1059 void setAccuracyDefaults() {
1091 m_anyChangeMade = m_projectionLimitExceeded =
false;
1092 m_numIterations = 0;
1094 m_normOnEntrance = m_normOnExit =
NaN;
1105 { assert(
isValid());
return m_worstError; }
1107 { assert(
isValid());
return m_projectionLimitExceeded; }
1110 { m_exitStatus=status;
return *
this; }
1112 { m_anyChangeMade=changeMade;
return *
this; }
1114 { m_projectionLimitExceeded=limitExceeded;
return *
this; }
1116 { m_numIterations=numIterations;
return *
this; }
1118 { m_normOnEntrance=
norm; m_worstError=worstError;
return *
this; }
1120 { m_normOnExit=
norm;
return *
this; }
1123 bool m_anyChangeMade;
1124 bool m_projectionLimitExceeded;
1125 int m_numIterations;
1127 Real m_normOnEntrance;
1138 unsigned int optionSet;
1154 operator bool()
const {
return optionSet != 0;}
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
This is the header which should be included in user programs that would like to make use of all the S...
Declares the user-visible part of a SimTK::State, the implementation is done in a separate internal c...
Includes internal headers providing declarations for the basic SimTK Core classes.
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:1520
A CoordinateDirection is a CoordinateAxis plus a direction indicating the positive or negative direct...
Definition: CoordinateAxis.h:244
This is a concrete Subsystem that is part of every System. It provides a variety of services for the ...
Definition: System.h:910
EventId createEventId(SubsystemIndex subsys, const State &state) const
void addEventReporter(ScheduledEventReporter *handler) const
DefaultSystemSubsystem(System &sys)
void addEventHandler(TriggeredEventHandler *handler)
void addEventReporter(TriggeredEventReporter *handler) const
void addEventHandler(ScheduledEventHandler *handler)
void findSubsystemEventIds(SubsystemIndex subsys, const State &state, const Array_< EventId > &allEvents, Array_< EventId > &eventsForSubsystem) const
This is a class to represent unique IDs for events in a type-safe way.
These are all the possible causes for events.
Definition: Event.h:126
Options for the handleEvent() method.
Definition: Event.h:269
Results returned by the handleEvent() method.
Definition: Event.h:345
Options for the advanced project() methods.
Definition: System.h:950
ProjectOptions & operator&=(const ProjectOptions &opts)
Definition: System.h:1045
ProjectOptions(Option opt)
This constructor creates default options except one setting one non-default Option.
Definition: System.h:986
static Real getDefaultOvershootFactor()
Definition: System.h:1040
bool isOptionSet(Option opt) const
Definition: System.h:1037
ProjectOptions & operator|=(const ProjectOptions &opts)
Definition: System.h:1043
Real getRequiredAccuracy() const
Return the current value for the required accuracy option.
Definition: System.h:1030
ProjectOptions & operator-=(Option opt)
Definition: System.h:1051
ProjectOptions & clear()
Restore this object to its default-constructed state (no options selected, default accuracy and overs...
Definition: System.h:992
ProjectOptions & clearOption(Option opt)
Remove a given option from the set.
Definition: System.h:1023
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
Option
Definition: System.h:952
@ UseInfinityNorm
Use the stricter infinity (max absolute value) norm rather than the default RMS norm to determine whe...
Definition: System.h:966
@ LocalOnly
This option says we expect the state to be close to a solution already and restricts projection to mo...
Definition: System.h:959
@ ForceFullNewton
A project() method is free to use an out-of-date Jacobian when solving the nonlinear system.
Definition: System.h:974
@ ForceProjection
Normally a project() method will return immediately after evaluating the norm if it is already at or ...
Definition: System.h:970
@ None
Take all defaults.
Definition: System.h:954
@ DontThrow
Normally failure to meet the accuracy requirements throws an exception.
Definition: System.h:963
Real getProjectionLimit() const
Return the maximum norm we're allowed to attempt to correct.
Definition: System.h:1035
ProjectOptions(Real accuracy)
This constructor allows the default accuracy to be overridden while leaving all other options at thei...
Definition: System.h:982
Real getOvershootFactor() const
Return the factor by which a project() method should try to do better than the required accuracy.
Definition: System.h:1033
ProjectOptions & setOvershootFactor(Real overshoot)
Project will attempt to reach accuracy*overshoot but settle for just accuracy.
Definition: System.h:1007
static Real getDefaultRequiredAccuracy()
Definition: System.h:1039
ProjectOptions & operator|=(Option opt)
Definition: System.h:1050
ProjectOptions & setProjectionLimit(Real limit)
Project will fail immediately if the initial norm is greater than the projection limit,...
Definition: System.h:1015
ProjectOptions()
Default constructor sets options to their default values.
Definition: System.h:978
ProjectOptions & operator-=(const ProjectOptions &opts)
Definition: System.h:1047
ProjectOptions & setOption(Option opt)
Set a particular option.
Definition: System.h:1026
Results for advanced users of project() methods.
Definition: System.h:1067
ProjectResults()
Definition: System.h:1069
bool isValid() const
Definition: System.h:1097
Real getNormOnExit() const
Definition: System.h:1103
ProjectResults & setNumIterations(int numIterations)
Definition: System.h:1115
ProjectResults & setNormOnExit(Real norm)
Definition: System.h:1119
int getWorstErrorOnEntrance() const
Definition: System.h:1104
bool getAnyChangeMade() const
Definition: System.h:1100
ProjectResults & setNormOnEntrance(Real norm, int worstError)
Definition: System.h:1117
ProjectResults & setExitStatus(Status status)
Definition: System.h:1109
int getNumIterations() const
Definition: System.h:1101
ProjectResults & setProjectionLimitExceeded(bool limitExceeded)
Definition: System.h:1113
bool getProjectionLimitExceeded() const
Definition: System.h:1106
Real getNormOnEntrance() const
Definition: System.h:1102
Status
Definition: System.h:1071
@ FailedToAchieveAccuracy
Projection converged but was unable to achieve the required accuracy.
Definition: System.h:1079
@ FailedToConverge
The Newton iterations were diverging.
Definition: System.h:1084
@ Succeeded
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
@ Invalid
This object has not been filled in yet and holds no results.
Definition: System.h:1073
ProjectResults & setAnyChangeMade(bool changeMade)
Definition: System.h:1111
ProjectResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid.
Definition: System.h:1089
Status getExitStatus() const
Definition: System.h:1098
(NOT USED YET) Options for the advanced realize() methods.
Definition: System.h:1137
bool isOptionSet(Option opt) const
Definition: System.h:1157
void clear()
Definition: System.h:1158
RealizeOptions()
Definition: System.h:1148
RealizeOptions & operator&=(RealizeOptions opts)
Definition: System.h:1164
RealizeOptions & operator|=(Option opt)
Definition: System.h:1166
void setOption(Option opt)
Definition: System.h:1160
RealizeOptions(Option opt)
Definition: System.h:1151
RealizeOptions & operator-=(Option opt)
Definition: System.h:1167
bool isEmpty() const
Definition: System.h:1155
RealizeOptions & operator|=(RealizeOptions opts)
Definition: System.h:1163
Option
Definition: System.h:1142
@ DontThrow
Definition: System.h:1144
@ None
Definition: System.h:1143
void clearOption(Option opt)
Definition: System.h:1159
(NOT USED YET) Results for advanced users of realize() methods.
Definition: System.h:1171
ScheduledEventHandler is a subclass of EventHandler for events that occur at a particular time that i...
Definition: EventHandler.h:84
ScheduledEventReporter is a subclass of EventReporter for events that occur at a particular time that...
Definition: EventReporter.h:72
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
@ Time
A new time has been realized.
Definition: Stage.h:73
@ HighestRuntime
Definition: Stage.h:84
@ Position
Spatial configuration available.
Definition: Stage.h:74
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
Provide a unique integer type for identifying Subsystems.
The abstract parent of all Subsystem implementation classes.
Definition: SubsystemGuts.h:47
A Subsystem is expected to be part of a larger System and to have interdependencies with other subsys...
Definition: Subsystem.h:55
This is the declaration for the System::Guts class, the abstract object to which a System handle poin...
Definition: SystemGuts.h:71
This is the base class that serves as the parent of all SimTK System objects; most commonly Simbody's...
Definition: System.h:97
int getNumHandlerCallsThatChangedStage(Stage) const
handleEvents() reports the lowest Stage it modified and we bump the counter for that Stage.
int getNumQErrorEstimateProjections() const
How many of the projectQ() calls that did a constraint projection also projected an error estimate?
System(const System &)
Copy constructor (untested).
int getNumQProjections() const
How many of the successful projectQ() calls actually did a constraint projection, rather than returni...
System & setDefaultTimeScale(Real tc)
(Advanced) This is a hint used for some default behaviors, such as determining an initial step size f...
int getNumHandleEventCalls() const
This is the total number of calls to handleEvents() regardless of the outcome.
System(System::Guts *g)
Constructor for internal use only.
Definition: System.h:884
const State & realizeTopology() const
The following call must be made after any topological change has been made to this System,...
DefaultSystemSubsystem & updDefaultSubsystem()
Get writable access to the default subsystem which is present in every system.
int getNumFailedProjectQCalls() const
Return the total number of calls to projectQ() that failed.
void multiplyByNPInvTranspose(const State &state, const Vector &fu, Vector &fq) const
Calculate fq=~pinv(N)*fu in O(n) time (very fast).
int getNumRealizationsOfThisStage(Stage) const
Whenever the system was realized from Stage-1 to the indicated Stage, this counter is bumped.
SubsystemIndex adoptSubsystem(Subsystem &child)
Take over ownership of the supplied subsystem and install it into the next free subsystem slot.
void calcTimeOfNextScheduledEvent(const State &state, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
This routine should be called to determine if and when there is an event scheduled to occur at a part...
int getNumPrescribeQCalls() const
Return the total number of calls to the System's prescribeQ() method.
bool systemTopologyHasBeenRealized() const
(Advanced) You can check whether realizeTopology() has been called since the last topological change ...
void multiplyByN(const State &state, const Vector &u, Vector &dq) const
Calculate dq=N*u in O(n) time (very fast).
bool getUseUniformBackground() const
Get the current setting of the "use uniform background" visualization hint.
~System()
Destructor here will invoke the virtual destructor in the System::Guts class and thus clean up all un...
bool hasGuts() const
Return true if this System handle is not empty.
Definition: System.h:886
void projectQ(State &state, Vector &qErrEst, const ProjectOptions &options, ProjectResults &results) const
(Advanced) Project free q's so that position constraints are satisfied and remove the corresponding e...
int getNumUProjections() const
How many of the successful projectU() calls actually did a constraint projection, rather than returni...
System & setUpDirection(const CoordinateDirection &up)
This is a hint to other software as to which way this System's designer considers to be "up".
void calcDecorativeGeometryAndAppend(const State &, Stage, Array_< DecorativeGeometry > &) const
(Advanced) Generate all decorative geometry computable at a specific stage; this is useful for visual...
bool isEmptyHandle() const
Internal use only.
bool prescribeU(State &state) const
This solver sets prescribed u's to their known values u=u(t,q) as a function of time and position var...
System()
Default constructor creates an empty handle.
Definition: System.h:780
void getFreeUIndex(const State &state, Array_< SystemUIndex > &freeUs) const
Return the indices of the u's in the given state that are free; that is, they are not affected by pre...
void projectU(State &state, Real accuracy=-1) const
Set prescribed velocities u=u(t,q) and attempt to satisfy velocity constraints by modifying the remai...
void realizeModel(State &state) const
Realize the model to be used for subsequent computations with the given state.
int getNumUErrorEstimateProjections() const
How many of the projectU() calls that did a constraint projection also projected an error estimate?
void addEventReporter(ScheduledEventReporter *handler) const
Add a ScheduledEventReporter to this System, which takes over ownership of the event reporter object.
Definition: System.h:935
System & setDefaultLengthScale(Real lc)
(Advanced) This is a hint that can be used to get a sense of what a "unit length" looks like for thi...
void projectU(State &state, Vector &uErrEst, const ProjectOptions &options, ProjectResults &results) const
(Advanced) Project free u's so that velocity constraints are satisfied and remove the corresponding e...
void reportEvents(const State &state, Event::Cause cause, const Array_< EventId > &eventIds) const
This method is similar to handleEvents(), but does not allow the State to be modified.
bool isSameSystem(const System &otherSystem) const
There can be multiple handles referring to the same System::Guts object; they are considered to be th...
int getNumFailedProjectUCalls() const
Return the total number of calls to projectU() that failed.
void multiplyByNPInv(const State &state, const Vector &dq, Vector &u) const
Calculate u=pinv(N)*dq in O(n) time (very fast).
void prescribe(State &state) const
Set values for prescribed positions q and velocities u.
Definition: System.h:488
const Guts & getSystemGuts() const
Obtain a const reference to the System::Guts object to which this handle refers.
Definition: System.h:872
void adoptSystemGuts(System::Guts *g)
Put new unowned Guts into this empty handle and take over ownership.
Guts & updSystemGuts()
Obtain a writable reference to the System::Guts object to which this handle refers.
Definition: System.h:876
void multiplyByNTranspose(const State &state, const Vector &fq, Vector &fu) const
Calculate fu=~N*fq in O(n) time (very fast).
StageVersion getSystemTopologyCacheVersion() const
(Advanced) Return the current version number of this system's Topology cache information.
int getNumReportEventCalls() const
This is the total number of calls to reportEvents() regardless of the outcome.
void relax(State &state, Stage stage, Real accuracy=-1) const
This optional method should modify fast variables at the given stage until they satisfy some relaxati...
void calcEventTriggerInfo(const State &state, Array_< EventTriggerInfo > &triggerInfo) const
This routine provides the Integrator with information it needs about the individual event trigger fun...
System & setUseUniformBackground(bool useUniformBackground)
This is a hint to visualization software that this System is best viewed against a uniform background...
Real getDefaultTimeScale() const
Get the currently-set value for the default time scale, 0.1 time units if it has never been set.
int getNumProjectQCalls() const
Return the total number of calls to projectQ(), regardless of whether the call did anything.
void resetAllCountersToZero()
Zero out the statistics for this System.
const String & getVersion() const
Return the version string assigned to this System (arbitrary).
const State & getDefaultState() const
This is available after realizeTopology(), and will throw an exception if realizeTopology() has not b...
int getNumRealizeCalls() const
Return the total number of calls to realizeTopology(), realizeModel(), or realize(),...
void projectQ(State &state, Real accuracy=-1) const
Set prescribed positions q=q(t) and attempt to satisfy position constraints by modifying the remainin...
bool isOwnerHandle() const
Internal use only.
void handleEvents(State &state, Event::Cause cause, const Array_< EventId > &eventIds, const HandleEventsOptions &options, HandleEventsResults &results) const
This solver handles a set of events which a TimeStepper has denoted as having occurred at the given t...
bool hasTimeAdvancedEvents() const
Return the current value of the flag indicating whether this System wants an event generated whenever...
Real getDefaultLengthScale() const
Get the currently-set value for the default length scale, 1 length unit if it has never been set.
CoordinateDirection getUpDirection() const
Get the current setting of the "up" direction hint.
Subsystem & updSubsystem(SubsystemIndex)
Obtain writable access to a particular subsystem by its index.
State & updDefaultState()
Don't use this; make a copy of the default state instead and modify your copy.
void invalidateSystemTopologyCache() const
(Advanced) Mark the Topology stage of this system and all its subsystems "not realized....
void setHasTimeAdvancedEvents(bool)
This determines whether this System wants to be notified whenever time advances irreversibly.
void getFreeQIndex(const State &state, Array_< SystemQIndex > &freeQs) const
Return the indices of the q's in the given state that are free; that is, they are not affected by pre...
int getNumPrescribeUCalls() const
Return the total number of calls to the System's prescribeU() method.
void realize(const State &state, Stage stage=Stage::HighestRuntime) const
Realize the given state to the indicated stage.
int getNumSubsystems() const
How may Subsystems are in here?
System & operator=(const System &)
Copy assignment (untested).
const String & getName() const
Return the name assigned to this System (arbitrary).
const DefaultSystemSubsystem & getDefaultSubsystem() const
Get read-only access to the default subsystem which is present in every system.
bool prescribeQ(State &state) const
This solver sets prescribed q's to their known values q=q(t) as a function of time (and possibly earl...
void calcTimeOfNextScheduledReport(const State &state, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
This routine is similar to calcTimeOfNextScheduledEvent(), but is used for "reporting events" which d...
void setSystemTopologyCacheVersion(StageVersion topoVersion) const
(Really advanced) Set the current version number of this system's Topology cache information.
const Subsystem & getSubsystem(SubsystemIndex) const
Obtain read-only access to a particular subsystem by its index.
int getNumProjectUCalls() const
Return the total number of calls to projectU(), regardless of whether the call did anything.
void addEventHandler(ScheduledEventHandler *handler)
Add a ScheduledEventHandler to this System, which takes over ownership of the event handler object.
Definition: System.h:931
void project(State &state, Real accuracy=-1) const
Apply prescribed motion and attempt to satisfy all position and velocity constraints by projecting th...
TriggeredEventHandler is a subclass of EventHandler for events that occur when some condition is sati...
Definition: EventHandler.h:109
TriggeredEventReporter is a subclass of EventReporter for events that occur when some condition is sa...
Definition: EventReporter.h:96
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
const Real NaN
This is the IEEE "not a number" constant for this implementation of the default-precision Real type; ...
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
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
float norm(const conjugate< float > &c)
Definition: conjugate.h:486
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