1#ifndef SimTK_SimTKCOMMON_SYSTEM_H_
2#define SimTK_SimTKCOMMON_SYSTEM_H_
37class DecorativeGeometry;
38class DefaultSystemSubsystem;
39class ScheduledEventHandler;
40class ScheduledEventReporter;
41class TriggeredEventHandler;
42class TriggeredEventReporter;
489 realize(state, Stage::Time);
491 realize(state, Stage::Position);
619 bool includeCurrentTime)
const;
627 bool includeCurrentTime)
const;
927 const Guts& getGuts()
const;
940inline System::operator
const Subsystem&()
const {
return getDefaultSubsystem();}
941inline 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(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 & clear()
Restore this object to its default-constructed state (no options selected, default accuracy and overs...
Definition System.h:992
Real getRequiredAccuracy() const
Return the current value for the required accuracy option.
Definition System.h:1030
ProjectOptions & setProjectionLimit(Real limit)
Project will fail immediately if the initial norm is greater than the projection limit,...
Definition System.h:1015
ProjectOptions & operator|=(Option opt)
Definition System.h:1050
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
ProjectOptions & operator-=(const ProjectOptions &opts)
Definition System.h:1047
ProjectOptions & setOption(Option opt)
Set a particular option.
Definition System.h:1026
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 & operator-=(Option opt)
Definition System.h:1051
static Real getDefaultRequiredAccuracy()
Definition System.h:1039
ProjectOptions()
Default constructor sets options to their default values.
Definition System.h:978
ProjectOptions & operator&=(const ProjectOptions &opts)
Definition System.h:1045
ProjectOptions & clearOption(Option opt)
Remove a given option from the set.
Definition System.h:1023
ProjectOptions & setOvershootFactor(Real overshoot)
Project will attempt to reach accuracy*overshoot but settle for just accuracy.
Definition System.h:1007
ProjectOptions & operator|=(const ProjectOptions &opts)
Definition System.h:1043
Results for advanced users of project() methods.
Definition System.h:1067
ProjectResults()
Definition System.h:1069
ProjectResults & setNumIterations(int numIterations)
Definition System.h:1115
bool isValid() const
Definition System.h:1097
Real getNormOnExit() const
Definition System.h:1103
ProjectResults & setAnyChangeMade(bool changeMade)
Definition System.h:1111
int getWorstErrorOnEntrance() const
Definition System.h:1104
bool getAnyChangeMade() const
Definition System.h:1100
ProjectResults & setNormOnExit(Real norm)
Definition System.h:1119
int getNumIterations() const
Definition System.h:1101
bool getProjectionLimitExceeded() const
Definition System.h:1106
ProjectResults & setNormOnEntrance(Real norm, int worstError)
Definition System.h:1117
ProjectResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid.
Definition System.h:1089
Real getNormOnEntrance() const
Definition System.h:1102
ProjectResults & setProjectionLimitExceeded(bool limitExceeded)
Definition System.h:1113
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 & setExitStatus(Status status)
Definition System.h:1109
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-=(Option opt)
Definition System.h:1167
void setOption(Option opt)
Definition System.h:1160
RealizeOptions & operator|=(RealizeOptions opts)
Definition System.h:1163
RealizeOptions(Option opt)
Definition System.h:1151
RealizeOptions & operator|=(Option opt)
Definition System.h:1166
RealizeOptions & operator&=(RealizeOptions opts)
Definition System.h:1164
bool isEmpty() const
Definition System.h:1155
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
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:62
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?
const State & getDefaultState() const
This is available after realizeTopology(), and will throw an exception if realizeTopology() has not b...
System(const System &)
Copy constructor (untested).
int getNumQProjections() const
How many of the successful projectQ() calls actually did a constraint projection, rather than returni...
const String & getName() const
Return the name assigned to this System (arbitrary).
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
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...
const String & getVersion() const
Return the version string assigned to this System (arbitrary).
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...
const DefaultSystemSubsystem & getDefaultSubsystem() const
Get read-only access to the default subsystem which is present in every system.
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
DefaultSystemSubsystem & updDefaultSubsystem()
Get writable access to the default subsystem which is present in every system.
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...
const Guts & getSystemGuts() const
Obtain a const reference to the System::Guts object to which this handle refers.
Definition System.h:872
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
void adoptSystemGuts(System::Guts *g)
Put new unowned Guts into this empty handle and take over ownership.
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 multiplyByNTranspose(const State &state, const Vector &fq, Vector &fu) const
Calculate fu=~N*fq in O(n) time (very fast).
State & updDefaultState()
Don't use this; make a copy of the default state instead and modify your copy.
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.
Subsystem & updSubsystem(SubsystemIndex)
Obtain writable access to a particular subsystem by its index.
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...
const Subsystem & getSubsystem(SubsystemIndex) const
Obtain read-only access to a particular subsystem by its index.
void calcEventTriggerInfo(const State &state, Array_< EventTriggerInfo > &triggerInfo) const
This routine provides the Integrator with information it needs about the individual event trigger fun...
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.
System & operator=(const System &)
Copy assignment (untested).
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...
const State & realizeTopology() const
The following call must be made after any topological change has been made to this System,...
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.
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.
System & setUseUniformBackground(bool useUniformBackground)
This is a hint to visualization software that this System is best viewed against a uniform background...
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...
System & setDefaultTimeScale(Real tc)
(Advanced) This is a hint used for some default behaviors, such as determining an initial step size f...
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?
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.
Guts & updSystemGuts()
Obtain a writable reference to the System::Guts object to which this handle refers.
Definition System.h:876
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:606