Simbody  3.7
SimTK::State Class Reference

This object is intended to contain all state information for a SimTK::System, except topological information which is stored in the System itself. More...

Public Member Functions

 State ()
 Create an empty State; this allocates an implementation object on the heap. More...
 
 State (const State &)
 The copy constructor has deep copy semantics; that is, this creates a new copy of the source object, not a reference to the original object. More...
 
 State (State &&source)
 The move constructor is very fast. The source object is left empty. More...
 
Stateoperator= (const State &)
 Copy assignment has deep copy semantics; that is, this State will contain a copy of the source, not a reference into it. More...
 
Stateoperator= (State &&source)
 Move assignment is very fast. More...
 
 ~State ()
 Destruct this State object and free up the heap space it is using. More...
 
void clear ()
 Restore State to default-constructed condition. More...
 
bool isConsistent (const SimTK::State &otherState) const
 Checks if a given state has the same number of state variables, constraints, etc as this state. More...
 
void setNumSubsystems (int i)
 Set the number of subsystems in this state. More...
 
void initializeSubsystem (SubsystemIndex, const String &name, const String &version)
 Set the name and version for a given subsystem, which must already have a slot allocated. More...
 
SubsystemIndex addSubsystem (const String &name, const String &version)
 Register a new subsystem as a client of this State. More...
 
int getNumSubsystems () const
 Return the number of Subsystems known to this State. More...
 
const StringgetSubsystemName (SubsystemIndex) const
 
const StringgetSubsystemVersion (SubsystemIndex) const
 
const StagegetSubsystemStage (SubsystemIndex) const
 
const StagegetSystemStage () const
 This returns the global stage for this State. More...
 
void invalidateAll (Stage)
 If any subsystem or the system stage is currently at or higher than the passed-in one, back up to the stage just prior; otherwise do nothing. More...
 
void invalidateAllCacheAtOrAbove (Stage) const
 If any subsystem or the system stage is currently at or higher than the passed-in one, back up to the stage just prior; otherwise do nothing. More...
 
void advanceSubsystemToStage (SubsystemIndex, Stage) const
 Advance a particular Subsystem's current stage by one to the indicated stage. More...
 
void advanceSystemToStage (Stage) const
 Advance the System-level current stage by one to the indicated stage. More...
 
StageVersion getSystemTopologyStageVersion () const
 The Topology stage version number (an integer) stored in this State must match the topology cache version number stored in the System for which it is allegedly a state. More...
 
const VectorgetEventTriggers () const
 
const VectorgetEventTriggersByStage (Stage) const
 
const VectorgetEventTriggersByStage (SubsystemIndex, Stage) const
 
VectorupdEventTriggers () const
 
VectorupdEventTriggersByStage (Stage) const
 
VectorupdEventTriggersByStage (SubsystemIndex, Stage) const
 
const VectorgetQ (SubsystemIndex) const
 Per-subsystem access to the global shared variables. More...
 
const VectorgetU (SubsystemIndex) const
 
const VectorgetZ (SubsystemIndex) const
 
const VectorgetUWeights (SubsystemIndex) const
 
const VectorgetZWeights (SubsystemIndex) const
 
VectorupdQ (SubsystemIndex)
 
VectorupdU (SubsystemIndex)
 
VectorupdZ (SubsystemIndex)
 
VectorupdUWeights (SubsystemIndex)
 
VectorupdZWeights (SubsystemIndex)
 
const VectorgetQDot (SubsystemIndex) const
 Per-subsystem access to the shared cache entries. More...
 
const VectorgetUDot (SubsystemIndex) const
 
const VectorgetZDot (SubsystemIndex) const
 
const VectorgetQDotDot (SubsystemIndex) const
 
VectorupdQDot (SubsystemIndex) const
 
VectorupdUDot (SubsystemIndex) const
 
VectorupdZDot (SubsystemIndex) const
 
VectorupdQDotDot (SubsystemIndex) const
 
const VectorgetQErr (SubsystemIndex) const
 
const VectorgetUErr (SubsystemIndex) const
 
const VectorgetUDotErr (SubsystemIndex) const
 
const VectorgetMultipliers (SubsystemIndex) const
 
const VectorgetQErrWeights (SubsystemIndex) const
 
const VectorgetUErrWeights (SubsystemIndex) const
 
VectorupdQErr (SubsystemIndex) const
 
VectorupdUErr (SubsystemIndex) const
 
VectorupdUDotErr (SubsystemIndex) const
 
VectorupdMultipliers (SubsystemIndex) const
 
VectorupdQErrWeights (SubsystemIndex)
 
VectorupdUErrWeights (SubsystemIndex)
 
const RealgetTime () const
 You can call these as long as system stage >= Model. More...
 
const VectorgetY () const
 
const VectorgetQ () const
 These are just views into Y. More...
 
const VectorgetU () const
 
const VectorgetZ () const
 
const VectorgetUWeights () const
 Get a unit weighting (1/unit change) for each u that can be used to weight a vector du so that the disparate elements are comparable in physical effect. More...
 
const VectorgetZWeights () const
 Get a unit weighting (1/unit change) for each z that can be used to weight a vector dz so that the disparate elements are comparable in physical effect. More...
 
VectorupdUWeights ()
 Set u weights (and q weights indirectly). More...
 
VectorupdZWeights ()
 Set z weights. More...
 
RealupdTime ()
 You can call these as long as System stage >= Model, but the stage will be backed up if necessary to the indicated stage. More...
 
VectorupdY ()
 
void setTime (Real t)
 An alternate syntax equivalent to updTime() and updY(). More...
 
void setY (const Vector &y)
 
VectorupdQ ()
 These are just views into Y. More...
 
VectorupdU ()
 
VectorupdZ ()
 
void setQ (const Vector &q)
 Alternate interface. More...
 
void setU (const Vector &u)
 
void setZ (const Vector &z)
 
const VectorgetYDot () const
 
const VectorgetQDot () const
 These are just views into YDot. More...
 
const VectorgetZDot () const
 
const VectorgetUDot () const
 
const VectorgetQDotDot () const
 This has its own space, not a view. More...
 
VectorupdYDot () const
 These are mutable. More...
 
VectorupdQDot () const
 
VectorupdZDot () const
 
VectorupdUDot () const
 
VectorupdQDotDot () const
 This is a separate shared cache entry, not part of YDot. More...
 
const VectorgetYErr () const
 Return the current constraint errors for all constraints. More...
 
const VectorgetQErr () const
 These are just views into YErr. More...
 
const VectorgetUErr () const
 
const VectorgetUDotErr () const
 These have their own space, they are not views. More...
 
const VectorgetMultipliers () const
 
const VectorgetQErrWeights () const
 Get the unit weighting (1/unit error) for each of the mp+mquat position inline constraints equations. More...
 
const VectorgetUErrWeights () const
 Get the unit weighting (1/unit error) for each of the mp+mv velocity-level inline constraint equations, meaning mp time derivatives of position (holonomic) inline constraint equations followed by mv velocity (nonholonomic) constraints. More...
 
VectorupdQErrWeights ()
 Set the unit weighting (1/unit error) for each of the mp+mquat position inline constraint equations. More...
 
VectorupdUErrWeights ()
 Set the unit weighting (1/unit error) for each of the mp+mv velocity-level inline constraints. More...
 
VectorupdYErr () const
 These are mutable. More...
 
VectorupdQErr () const
 
VectorupdUErr () const
 
VectorupdUDotErr () const
 
VectorupdMultipliers () const
 
Continuous state variables

These continuous state variables are shared among all the subsystems and are not allocated until the system is advanced to Stage::Model.

The returned index is local to each subsystem. After the system is modeled, we guarantee that all the q's for a subsystem will be contiguous, and similarly for u's and z's. However, q,u,z will not be contiguous with each other. The global y={q,u,z} is contiguous, and global q,u,z are contiguous within y, in that order. Corresponding cache entries for the derivatives of these variables are allocated at Model stage also.

QIndex allocateQ (SubsystemIndex, const Vector &qInit)
 Allocate generalized coordinates q, which are second order continuous state variables. More...
 
UIndex allocateU (SubsystemIndex, const Vector &uInit)
 Allocate generalized speeds u, which are first order continuous state variables related to the derivatives of the second order q's by qdot=N(q)*u, for a System-defined coupling matrix N. More...
 
ZIndex allocateZ (SubsystemIndex, const Vector &zInit)
 Allocate auxiliary first order continuous state variables z. More...
 
Constraint errors and multipliers

These constraint error cache entries are shared among all the subsystems and are not allocated until the system is advanced to Stage::Instance.

The returned index is local to each subsystem. Q errors and U errors will each be contiguous for a given subsystem, but not with each other. However, the System-level yerr={qerr,uerr} is a single contiguous vector. UDotErr is a separate quantity, not part of yerr. Again the UDotErr's for each subsystem will be contiguous within the larger UDotErr Vector. Allocating a UDotErr has the side effect of allocating another Vector of the same size in the cache for the corresponding Lagrange multipliers, and these are partitioned identically to UDotErrs.

QErrIndex allocateQErr (SubsystemIndex, int nqerr) const
 Allocate nqerr cache slots to hold the current error for position-level (holonomic) constraint equations. More...
 
UErrIndex allocateUErr (SubsystemIndex, int nuerr) const
 Allocate nuerr cache slots to hold the current error for velocity-level (nonholonomic and holonomic first derivative) constraint equations. More...
 
UDotErrIndex allocateUDotErr (SubsystemIndex, int nudoterr) const
 Allocate nudoterr cache slots to hold the current error for acceleration-level (acceleration-only, nonholonomic first derivative, and holonomic second derivative) constraint equations. More...
 
Event witness functions

Some Events require a slot in the State cache to hold the current value of the event trigger function (a.k.a.

event "witness" function). The Stage here is the stage at which the trigger function's value should be examined by a TimeStepper. The returned index is local to the Subsystem and also to the stage. These can be allocated in a State that has not yet been realized to Instance stage, and will be forgotten appropriately if the State is later backed up to an earlier stage. When this State is realized to Instance stage, global event trigger slots will be allocated, collecting all same-stage event triggers together consecutively for the convenience of the TimeStepper. Within a stage, a given subsystem's event trigger slots for that stage are consecutive.

EventTriggerByStageIndex allocateEventTrigger (SubsystemIndex, Stage stage, int nevent) const
 Allocate room for nevent witness function values that will be available at the indicated stage. More...
 
Discrete Variables

You can allocate a new DiscreteVariable in any State whose stage has not yet been advanced to Model stage.

The stage at allocation (Empty or Topology) is remembered so that the appropriate discrete variables can be forgotten if the State's stage is reduced back to that stage later after advancing past it. DiscreteVariables are private to each Subsystem and allocated immediately. The returned index is unique within the Subsystem and there is no corresponding global index.

DiscreteVariableIndex allocateDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *)
 The Stage supplied here in the call is the earliest subsystem stage which is invalidated by a change made to this discrete variable. More...
 
DiscreteVariableIndex allocateAutoUpdateDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *, Stage updateDependsOn)
 This method allocates a DiscreteVariable whose value should be updated automatically after each time step. More...
 
CacheEntryIndex getDiscreteVarUpdateIndex (SubsystemIndex, DiscreteVariableIndex) const
 For an auto-updating discrete variable, return the CacheEntryIndex for its associated update cache entry, otherwise return an invalid index. More...
 
Stage getDiscreteVarAllocationStage (SubsystemIndex, DiscreteVariableIndex) const
 At what stage was this State when this discrete variable was allocated? The answer must be Stage::Empty or Stage::Topology. More...
 
Stage getDiscreteVarInvalidatesStage (SubsystemIndex, DiscreteVariableIndex) const
 What is the earliest stage that is invalidated when this discrete variable is modified? All later stages are also invalidated. More...
 
const AbstractValuegetDiscreteVariable (SubsystemIndex, DiscreteVariableIndex) const
 Get the current value of the indicated discrete variable. More...
 
Real getDiscreteVarLastUpdateTime (SubsystemIndex, DiscreteVariableIndex) const
 Return the time of last update for this discrete variable. More...
 
const AbstractValuegetDiscreteVarUpdateValue (SubsystemIndex, DiscreteVariableIndex) const
 For an auto-updating discrete variable, return the current value of its associated update cache entry; this is the value the discrete variable will have the next time it is updated. More...
 
AbstractValueupdDiscreteVarUpdateValue (SubsystemIndex, DiscreteVariableIndex) const
 For an auto-updating discrete variable, return a writable reference to the value of its associated update cache entry. More...
 
bool isDiscreteVarUpdateValueRealized (SubsystemIndex, DiscreteVariableIndex) const
 Check whether the update value for this auto-update discrete variable has already been computed since the last change to state variables it depends on. More...
 
void markDiscreteVarUpdateValueRealized (SubsystemIndex, DiscreteVariableIndex) const
 Mark the update value for this auto-update discrete variable as up-to-date with respect to the state variables it depends on. More...
 
AbstractValueupdDiscreteVariable (SubsystemIndex, DiscreteVariableIndex)
 Get a writable reference to the value stored in the indicated discrete state variable dv, and invalidate stage dv.invalidates and all higher stages. More...
 
void setDiscreteVariable (SubsystemIndex, DiscreteVariableIndex, const AbstractValue &)
 Alternate interface to updDiscreteVariable. More...
 
Cache Entries

You can allocate a new CacheEntry in any State whose stage has not yet been advanced to Instance stage.

The stage at allocation (Empty, Topology, or Model) is remembered so that the appropriate cache entries can be forgotten if the State's stage is reduced back to that stage later after advancing past it. CacheEntries are private to each Subsystem and allocated immediately. The returned index is unique within the Subsystem and there is no corresponding global index.

CacheEntryIndex allocateCacheEntry (SubsystemIndex, Stage earliest, Stage latest, AbstractValue *value) const
 There are two Stages supplied explicitly as arguments to this method: earliest and latest. More...
 
CacheEntryIndex allocateCacheEntry (SubsystemIndex sx, Stage stage, AbstractValue *value) const
 This is an abbreviation for allocation of a cache entry whose earliest and latest Stages are the same. More...
 
CacheEntryIndex allocateLazyCacheEntry (SubsystemIndex sx, Stage earliest, AbstractValue *value) const
 This is an abbreviation for allocation of a lazy cache entry. More...
 
CacheEntryIndex allocateCacheEntryWithPrerequisites (SubsystemIndex, Stage earliest, Stage latest, bool q, bool u, bool z, const Array_< DiscreteVarKey > &discreteVars, const Array_< CacheEntryKey > &cacheEntries, AbstractValue *value)
 (Advanced) Allocate a cache entry with prerequisites other than just reaching a particular computation stage. More...
 
Stage getCacheEntryAllocationStage (SubsystemIndex, CacheEntryIndex) const
 At what stage was this State when this cache entry was allocated? The answer must be Stage::Empty, Stage::Topology, or Stage::Model. More...
 
const AbstractValuegetCacheEntry (SubsystemIndex, CacheEntryIndex) const
 Retrieve a const reference to the value contained in a particular cache entry. More...
 
AbstractValueupdCacheEntry (SubsystemIndex, CacheEntryIndex) const
 Retrieve a writable reference to the value contained in a particular cache entry. More...
 
bool isCacheValueRealized (SubsystemIndex, CacheEntryIndex) const
 Check whether the value in a particular cache entry has been recalculated since the last change to the state variables it depends on. More...
 
void markCacheValueRealized (SubsystemIndex, CacheEntryIndex) const
 Mark the value of a particular cache entry as up to date after it has been recalculated. More...
 
void markCacheValueNotRealized (SubsystemIndex, CacheEntryIndex) const
 (Advanced) Normally cache entries are invalidated automatically, however this method allows manual invalidation of the value of a particular cache entry. More...
 
Global Resource Dimensions

These are the dimensions of the global shared state and cache resources, as well as the dimensions of the per-Subsystem partioning of those resources.

State resource dimensions (including cache resources directly related to state variables) are known after the System has been realized to Model stage. Other cache resource dimensions are known after the System has been realized to Instance stage. Access to the actual data arrays may have stricter requirements (for example, you can't ask to look at UErr arrays until Velocity stage). Hence it is better to use these explicit dimension-providing methods than to get a reference to a Vector and ask for its size().

See also
Per-Subsystem Dimensions group
Global-to-Subsystem Maps group
int getNY () const
 Get the total number ny=nq+nu+nz of shared continuous state variables. More...
 
int getNQ () const
 Get total number of shared q's (generalized coordinates; second order state variables). More...
 
SystemYIndex getQStart () const
 Returns the y index at which the q's begin. Callable at Model stage. More...
 
int getNU () const
 Get total number of shared u's (generalized speeds; mobilities). More...
 
SystemYIndex getUStart () const
 Returns the y index at which the u's begin. Callable at Model stage. More...
 
int getNZ () const
 Get total number of shared z's (auxiliary state variables). More...
 
SystemYIndex getZStart () const
 Returns the y index at which the z's begin. Callable at Model stage. More...
 
int getNYErr () const
 Get the total number nyerr=nqerr+nuerr of shared cache entries for position-level and velocity-level constraint errors. More...
 
int getNQErr () const
 Return the total number nqerr=mp+nQuaternions of cache entries for position-level constraint errors. More...
 
SystemYErrIndex getQErrStart () const
 Returns the yErr index at which the qErr's begin. Callable at Instance stage. More...
 
int getNUErr () const
 Return the total number nuerr=mp+mv of cache entries for velocity-level constraint errors (including also errors in the time derivatives of position-level constraints). More...
 
SystemYErrIndex getUErrStart () const
 Returns the yErr index at which the uErr's begin. Callable at Instance stage. More...
 
int getNUDotErr () const
 Return the total number nudotErr=mp+mv+ma of cache entries for acceleration-level constraint errors (including also errors in the second time derivatives of position-level constraints and the first time derivatives of velocity-level constraints). More...
 
int getNMultipliers () const
 Return the total number of constraint multipliers; necessarily the same as the number of acceleration-level constraint errors nUDotErr. More...
 
int getNEventTriggers () const
 Return the total number of event trigger function slots in the cache. More...
 
int getNEventTriggersByStage (Stage) const
 Return the size of the partition of event trigger functions which are evaluated at a given Stage. More...
 
SystemEventTriggerIndex getEventTriggerStartByStage (Stage) const
 Return the index within the global event trigger array at which the first of the event triggers associated with a particular Stage are stored; the rest follow contiguously. More...
 
std::mutex & getStateLock () const
 Returns a mutex that should be used to lock the state whenever multiple threads are asynchronously writing/updating a common state cache. More...
 
Per-Subsystem Dimensions

These are the dimensions and locations within the global resource arrays of state and cache resources allocated to a particular Subsystem.

Note that a Subsystem has contiguous q's, contiguous u's, and contiguous z's but that the q-, u-, and z-partitions are not contiguous. Hence there is no Subsystem equivalent of the global y vector.

These serve as a mapping from Subsystem-local indices for the various shared resources to their global resource indices.

See also
Global Resource Dimensions
SystemQIndex getQStart (SubsystemIndex) const
 
int getNQ (SubsystemIndex) const
 
SystemUIndex getUStart (SubsystemIndex) const
 
int getNU (SubsystemIndex) const
 
SystemZIndex getZStart (SubsystemIndex) const
 
int getNZ (SubsystemIndex) const
 
SystemQErrIndex getQErrStart (SubsystemIndex) const
 
int getNQErr (SubsystemIndex) const
 
SystemUErrIndex getUErrStart (SubsystemIndex) const
 
int getNUErr (SubsystemIndex) const
 
SystemUDotErrIndex getUDotErrStart (SubsystemIndex) const
 
int getNUDotErr (SubsystemIndex) const
 
SystemMultiplierIndex getMultipliersStart (SubsystemIndex) const
 
int getNMultipliers (SubsystemIndex) const
 
SystemEventTriggerByStageIndex getEventTriggerStartByStage (SubsystemIndex, Stage) const
 
int getNEventTriggersByStage (SubsystemIndex, Stage) const
 
Advanced/Obscure/Debugging

Don't call these methods unless you know what you're doing.

void getSystemStageVersions (Array_< StageVersion > &versions) const
 (Advanced) Record the current version numbers of each valid System-level stage. More...
 
Stage getLowestSystemStageDifference (const Array_< StageVersion > &prevVersions) const
 (Advanced) Given a list of per-stage version numbers extracted by an earlier call to getSystemStageVersions(), note the lowest system stage in the current State whose version number differs from the corresponding previous version number. More...
 
void setSystemTopologyStageVersion (StageVersion topoVersion)
 (Advanced) This explicitly modifies the Topology stage version; don't use this method unless you know what you're doing! This can be used to force compatibility with a System that has had Topology changes since this State was created. More...
 
ValueVersion getQValueVersion () const
 (Advanced) Return a ValueVersion for q, meaning an integer that is incremented whenever any q is changed (or more precisely whenever q or y is returned with writable access). More...
 
ValueVersion getUValueVersion () const
 (Advanced) Return a ValueVersion for u, meaning an integer that is incremented whenever any u is changed (or more precisely whenever u or y is returned with writable access). More...
 
ValueVersion getZValueVersion () const
 (Advanced) Return a ValueVersion for z, meaning an integer that is incremented whenever any z is changed (or more precisely whenever z or y is returned with writable access). More...
 
const ListOfDependents & getQDependents () const
 (Advanced) Return the list of cache entries for which q was specified as an explicit prerequisite. More...
 
const ListOfDependents & getUDependents () const
 (Advanced) Return the list of cache entries for which u was specified as an explicit prerequisite. More...
 
const ListOfDependents & getZDependents () const
 (Advanced) Return the list of cache entries for which z was specified as an explicit prerequisite. More...
 
bool hasCacheEntry (const CacheEntryKey &cacheEntry) const
 (Advanced) Check whether this State has a particular cache entry. More...
 
const CacheEntryInfo & getCacheEntryInfo (const CacheEntryKey &cacheEntry) const
 (Advanced) Return a const reference to the cache entry information for a particular cache entry. More...
 
CacheEntryInfo & updCacheEntryInfo (const CacheEntryKey &cacheEntry)
 (Advanced) Return a writable reference to the cache entry information for a particular cache entry. More...
 
bool hasDiscreteVar (const DiscreteVarKey &discreteVar) const
 (Advanced) Check whether this State has a particular discrete state variable. More...
 
const DiscreteVarInfo & getDiscreteVarInfo (const DiscreteVarKey &discreteVar) const
 (Advanced) Return a reference to the discrete variable information for a particular discrete variable. More...
 
const PerSubsystemInfo & getPerSubsystemInfo (SubsystemIndex) const
 (Advanced) Return a reference to the per-subsystem information in the state. More...
 
void autoUpdateDiscreteVariables ()
 (Advanced) This is called at the beginning of every integration step to set the values of auto-update discrete variables from the values stored in their associated cache entries. More...
 
String toString () const
 (Debugging) Not suitable for serialization. More...
 
String cacheToString () const
 (Debugging) Not suitable for serialization. More...
 

Detailed Description

This object is intended to contain all state information for a SimTK::System, except topological information which is stored in the System itself.

A SimTK::System is "const" after its topology has been constructed and realized. Anything changeable is instead stored in a State. Systems contain a set of Subsystem objects, and State supports that concept by allowing per-subsystem partitioning of the total system state. This allows subsystems to have their own private state variables, while permitting the system to allow shared access to state among the subsystems when necessary.

The State provides services reflecting the structure of the equations it expects to find in the System. Three different views of the same state information are supported to accommodate three different users:

  • the system as a whole
  • Subsystems contained in the system
  • numerical methods operating on the state

Typically numerical methods have a much less nuanced view of the state than do the system or subsystems.

The system is expected to be a "hybrid DAE", that is, a mixture of continuous and discrete dynamic equations, and algebraic constraints. There is an independent variable t, continuous state variables y, and discrete state variables d.

The continuous part is an ODE-on-a-manifold system suitable for solution via coordinate projection, structured like this for the view taken by numerical methods:

     (1)  y' = f(d;t,y)         differential equations
     (2)  c  = c(d;t,y)         algebraic equations (manifold is c=0)
     (3)  e  = e(d;t,y)         event triggers (watch for zero crossings)

with initial conditions t0,y0,d0 such that c=0. The discrete variables d are updated upon occurrence of specific events. When those events are functions of time or state, they are detected using the set of scalar-valued event trigger functions e (3).

In the more detailed view as seen from the System, we consider y={q,u,z} to be partitioned into position variables q, velocity variables u, and auxiliary variables z. There will be algebraic constraints involving q, u, and u's time derivatives udot. The system is now assumed to look like this:

     (4) qdot    = N(q) u
     (5) zdot    = zdot(d;t,q,u,z)
     (6) M(q) udot + ~G(q) mult = f(d;t,q,u,z)
         G(q) udot              = b(d;t,q,u)
                   [ pdotdot(d;t,q,u,udot) ]
     (7) udotErr = [ vdot(d;t,q,u,udot)    ] = 0
                   [ a(d;t,q,u,udot)       ]
     (8) uErr    = [ pdot(d;t,q,u) ]         = 0
                   [ v(d;t,q,u)    ]
     (9) qErr    = [ p(d;t,q) ]              = 0
                   [ n(q)     ]

The q's can also be dealt with directly as second order variables via

    (10) qdotdot = Ndot(q,qdot) u + N(q) udot

Here G = [P;V;A] with A(q) being the coefficient matrix for constraints appearing only at the acceleration level, and V(q)=partial(v)/partial(u) the coefficient matrix for the velocity (nonholonomic) constraints, and P(q)=partial(pdot)/partial(u) is the coefficient matrix of the first time derivatives of the position (holonomic) constraints. Note that uErr in Eq 8 is assumed to include equations resulting from differentiation of p() in Eq 9, as well as ones first introduced at the velocity level (nonholonomic constraints), and udotErr is similarly built from acceleration-only constraints a() and derivatives of higher-level constraints.

If a system allocates nq q's, nu u's, and nz z's the State will also allocate matching cache variables qdot, qdotdot, udot, and zdot. If mp position (holonomic) constraints (9), mpv velocity constraints (8) and mpva acceleration constraints (7) are allocated, the state creates cache entries of like sizes qErr, uErr, udotErr. In addition room for the mpva Lagrange multipliers 'mult' is allocated in the cache.

In the final view, the Subsystem view, the same variables and cache entries exist, but only the ones allocated by that Subsystem are visible. All of a Subsystem's q's are consecutive in memory, as are its u's, uErr's, etc., but the q's are not adjacent to the u's as they are for the System's view.

The default constructor creates a State containing no state variables and with its realization cache stage set to Stage::Empty. During subsystem construction, variables and cache entries for any stage can be allocated, however all Model stage variables must be allocated during this time. At the end of construction, call advanceSubsystemToStage(Topology) which will put the subsystem at Stage::Topology. Then the subsystems realize their Model stages, during which variables at any stage > Model, and cache entries at any stage >= Model can be allocated. After that call advanceSubsystemToStage(Model) which sets the stage to Stage::Model and disallows further state allocation.

Note that there is a global Stage for the state as a whole, and individual Stages for each subsystem. The global stage can never be higher than the lowest subsystem stage. Global state resources are allocated when the global Stage advances to "Model" and tossed out if that stage is invalidated. Similarly, cache resources are allocated at stage Instance and forgotten when Instance is invalidated. Note that subsystems will "register" their use of the global variable pools during their own modeling stages, but that the actual global resources won't exist until the system has been advanced to Model or Instance stage.

Implementation note

This class is actually a "handle" that contains only a pointer to the hidden implementation class, StateImpl. Most of the methods here are inline and simply forward to the implementation object; the implementations of these must wait for the declaration of StateImpl in StateImpl.h.

Constructor & Destructor Documentation

◆ State() [1/3]

SimTK::State::State ( )

Create an empty State; this allocates an implementation object on the heap.

◆ State() [2/3]

SimTK::State::State ( const State )

The copy constructor has deep copy semantics; that is, this creates a new copy of the source object, not a reference to the original object.

This makes the new State contain a copy of the state information in the source State, copying only state variables and not the cache. If the source state hasn't been realized to at least Stage::Model, then we don't copy its state variables either, except those associated with the Topology stage.

◆ State() [3/3]

SimTK::State::State ( State &&  source)

The move constructor is very fast. The source object is left empty.

◆ ~State()

SimTK::State::~State ( )

Destruct this State object and free up the heap space it is using.

Member Function Documentation

◆ operator=() [1/2]

State& SimTK::State::operator= ( const State )

Copy assignment has deep copy semantics; that is, this State will contain a copy of the source, not a reference into it.

This makes the current State contain a copy of the state information in the source State, copying only state variables and not the cache. If the source state hasn't been realized to at least Stage::Model, then we don't copy its state variables either, except those associated with the Topology stage.

◆ operator=() [2/2]

State& SimTK::State::operator= ( State &&  source)

Move assignment is very fast.

The source object is left in a valid but undefined condition.

◆ clear()

void SimTK::State::clear ( )

Restore State to default-constructed condition.

◆ isConsistent()

bool SimTK::State::isConsistent ( const SimTK::State otherState) const

Checks if a given state has the same number of state variables, constraints, etc as this state.

Returns true if the following quantities are the same for both this state and otherState.

  • number of subsystems
  • number of generalized coordinates (Q's)
  • number of generalized speeds (U's)
  • number of auxiliary state variables (Z's)
  • number of position constraints (QErr's)
  • number of velocity constraints (UErr's)
  • number of acceleration constraints (UDotErr's)
  • number of constraint Lagrange multipliers
  • number of event triggers

Returns false otherwise.

You can call this after Instance stage has been realized on both this state and otherState.

This method does NOT guarantee that both states are for the same system or that both states will work with the same system. Also, this method does NOT check for any relationship between the times in the two states.

◆ setNumSubsystems()

void SimTK::State::setNumSubsystems ( int  i)
inline

Set the number of subsystems in this state.

This is done during initialization of the State by a System; it completely wipes out anything that used to be in the State so use cautiously!

◆ initializeSubsystem()

void SimTK::State::initializeSubsystem ( SubsystemIndex  ,
const String name,
const String version 
)
inline

Set the name and version for a given subsystem, which must already have a slot allocated.

◆ addSubsystem()

SubsystemIndex SimTK::State::addSubsystem ( const String name,
const String version 
)
inline

Register a new subsystem as a client of this State.

The supplied strings are stored with the State but are not interpreted by it. The intent is that they can be used to perform "sanity checks" on deserialized States to make sure they match the currently instantiated System. The subsystem index (a small integer) is returned.

◆ getNumSubsystems()

int SimTK::State::getNumSubsystems ( ) const
inline

Return the number of Subsystems known to this State.

◆ getSubsystemName()

const String& SimTK::State::getSubsystemName ( SubsystemIndex  ) const
inline

◆ getSubsystemVersion()

const String& SimTK::State::getSubsystemVersion ( SubsystemIndex  ) const
inline

◆ getSubsystemStage()

const Stage& SimTK::State::getSubsystemStage ( SubsystemIndex  ) const
inline

◆ getSystemStage()

const Stage& SimTK::State::getSystemStage ( ) const
inline

This returns the global stage for this State.

◆ invalidateAll()

void SimTK::State::invalidateAll ( Stage  )
inline

If any subsystem or the system stage is currently at or higher than the passed-in one, back up to the stage just prior; otherwise do nothing.

This is for use if you have write access to the state and can invalidate even Topology and Model stages which may destroy state variables. "All" here refers to all Subysystems.

◆ invalidateAllCacheAtOrAbove()

void SimTK::State::invalidateAllCacheAtOrAbove ( Stage  ) const
inline

If any subsystem or the system stage is currently at or higher than the passed-in one, back up to the stage just prior; otherwise do nothing.

This const method can only be used to invalidate Stage::Instance or higher. To invalidate Model or Topology stage you must have write access to the state because invalidating those stages can destroy state variables in addition to cache entries. "All" here refers to all Subsystems.

◆ advanceSubsystemToStage()

void SimTK::State::advanceSubsystemToStage ( SubsystemIndex  ,
Stage   
) const
inline

Advance a particular Subsystem's current stage by one to the indicated stage.

The stage is passed in just to give us a chance to verify that all is as expected. You can only advance one stage at a time. Advancing to Topology, Model, or Instance stage affects what you can do later.

See also
advanceSystemToStage()

◆ advanceSystemToStage()

void SimTK::State::advanceSystemToStage ( Stage  ) const
inline

Advance the System-level current stage by one to the indicated stage.

This can only be done if all Subsystem have already been advanced to this Stage.

See also
advanceSubsystemToStage()

◆ getSystemTopologyStageVersion()

StageVersion SimTK::State::getSystemTopologyStageVersion ( ) const
inline

The Topology stage version number (an integer) stored in this State must match the topology cache version number stored in the System for which it is allegedly a state.

See also
System::getSystemTopologyCacheVersion()

◆ allocateQ()

QIndex SimTK::State::allocateQ ( SubsystemIndex  ,
const Vector qInit 
)
inline

Allocate generalized coordinates q, which are second order continuous state variables.

Matching cache entries qdot and qdotdot are allocated to hold the first and second time derivatives of q. The supplied vector qInit is used to specify the number of q's to be allocated and their initial values. The Subsystem-local QIndex of the first allocated q is returned; the others follow consecutively.

◆ allocateU()

UIndex SimTK::State::allocateU ( SubsystemIndex  ,
const Vector uInit 
)
inline

Allocate generalized speeds u, which are first order continuous state variables related to the derivatives of the second order q's by qdot=N(q)*u, for a System-defined coupling matrix N.

A matching cache entry udot is allocated to hold the time derivative of u. The supplied vector uInit is used to specify the number of u's to be allocated and their initial values. The Subsystem-local UIndex of the first allocated u is returned; the others follow consecutively.

◆ allocateZ()

ZIndex SimTK::State::allocateZ ( SubsystemIndex  ,
const Vector zInit 
)
inline

Allocate auxiliary first order continuous state variables z.

A matching cache entry zdot is allocated to hold the time derivative of z. The supplied vector zInit is used to specify the number of z's to be allocated and their initial values. The Subsystem-local ZIndex of the first allocated z is returned; the others follow consecutively.

◆ allocateQErr()

QErrIndex SimTK::State::allocateQErr ( SubsystemIndex  ,
int  nqerr 
) const
inline

Allocate nqerr cache slots to hold the current error for position-level (holonomic) constraint equations.

◆ allocateUErr()

UErrIndex SimTK::State::allocateUErr ( SubsystemIndex  ,
int  nuerr 
) const
inline

Allocate nuerr cache slots to hold the current error for velocity-level (nonholonomic and holonomic first derivative) constraint equations.

◆ allocateUDotErr()

UDotErrIndex SimTK::State::allocateUDotErr ( SubsystemIndex  ,
int  nudoterr 
) const
inline

Allocate nudoterr cache slots to hold the current error for acceleration-level (acceleration-only, nonholonomic first derivative, and holonomic second derivative) constraint equations.

This also allocates the same number of slots in the constraint multipliers vector.

◆ allocateEventTrigger()

EventTriggerByStageIndex SimTK::State::allocateEventTrigger ( SubsystemIndex  ,
Stage  stage,
int  nevent 
) const
inline

Allocate room for nevent witness function values that will be available at the indicated stage.

The Subsystem- and Stage-local index of the first allocated witness is returned; the rest follow consecutively.

◆ allocateDiscreteVariable()

DiscreteVariableIndex SimTK::State::allocateDiscreteVariable ( SubsystemIndex  ,
Stage  invalidates,
AbstractValue  
)
inline

The Stage supplied here in the call is the earliest subsystem stage which is invalidated by a change made to this discrete variable.

You may access the value of the discrete variable for reading (via getDiscreteVariable()) or writing (via updDiscreteVariable()) any time after it has been allocated. Access for writing has the side effect of reducing the subsystem and system stages for this State to one stage below the one supplied here, that is, the stage supplied here is invalidated. Note that you must have write access to the State in order to change the value of any state variable.

Ownership of the AbstractValue object supplied here is taken over by the State – don't delete the object after this call!

See also
getDiscreteVariable()
updDiscreteVariable()

◆ allocateAutoUpdateDiscreteVariable()

DiscreteVariableIndex SimTK::State::allocateAutoUpdateDiscreteVariable ( SubsystemIndex  ,
Stage  invalidates,
AbstractValue ,
Stage  updateDependsOn 
)
inline

This method allocates a DiscreteVariable whose value should be updated automatically after each time step.

A CacheEntry of the same value type as the variable is allocated to hold the update value. The discrete variable is allocated as described for allocateDiscreteVariable(), except that the invalidates stage must be higher than Stage::Time. The cache entry is allocated as described for allocateCacheEntry() without an automatic calculation (latest) stage. The cache entry is then considered to be the "update" value for the discrete variable. Update values play a similar role for discrete variables as derivatives play for continuous variables. That is, they define how the variable is to be updated when a TimeStepper accepts a step.

Update occurs as follows: at the start of every continuous interval, after all other pending events have been handled, a time stepper should call the State method autoUpdateDiscreteVariables(). That method looks at all the auto-update discrete variables to see which ones have valid update values. For each valid value, the discrete variable and its update value are swapped, and the new cache value is marked invalid.

Note
No stage is invalidated by the swap even though this is clearly modifying the state variable. It is up to the user of this variable to make sure that is reasonable, by using the update value, not the variable value for computations during realize(). In that way the results are always calculated using the value as it will be after an update. That means that no results will change when the swap occurs, so no stage needs to be invalidated upon updating. If you do use both values, make sure that all computed results remain unchanged from the end of one step to the beginning of the next.

The above behavior is entirely analogous to the treatment of continuous variables like q: the integrator ensures that only updated values of q are seen when evaluations are made at intermediate or trial steps; you should do the same. In contrast to this auto-update behavior, any explicit change to the discrete variable will invalidate the variable's invalidates stage just as for a non-auto-updating discrete variable. The auto-update cache entry is always invalidated by an explicit change to the variable, as well as by the updateDependsOn stage being invalidated.

Ownership of the AbstractValue object supplied here is taken over by the State – don't delete the object after this call! A clone() of this value will be used in the auto-update cache entry so there will be two objects of this type around at run time that get swapped back and forth between the state variable and the cache entry.

You can allocate discrete variables in a State at Topology stage or Model stage but not later. That is, you allocate the variable while the State is in Stage::Empty, and then it appears when you do realizeTopology(); or, you allocate the variable when the State is in Stage::Topology and it appears when you do realizeModel().

See also
allocateDiscreteVariable()
allocateCacheEntry()

◆ getDiscreteVarUpdateIndex()

CacheEntryIndex SimTK::State::getDiscreteVarUpdateIndex ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

For an auto-updating discrete variable, return the CacheEntryIndex for its associated update cache entry, otherwise return an invalid index.

◆ getDiscreteVarAllocationStage()

Stage SimTK::State::getDiscreteVarAllocationStage ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

At what stage was this State when this discrete variable was allocated? The answer must be Stage::Empty or Stage::Topology.

◆ getDiscreteVarInvalidatesStage()

Stage SimTK::State::getDiscreteVarInvalidatesStage ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

What is the earliest stage that is invalidated when this discrete variable is modified? All later stages are also invalidated.

This stage was set when the discrete variable was allocated and can't be changed with unallocating it first.

◆ getDiscreteVariable()

const AbstractValue& SimTK::State::getDiscreteVariable ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

Get the current value of the indicated discrete variable.

This requires only that the variable has already been allocated and will fail otherwise.

◆ getDiscreteVarLastUpdateTime()

Real SimTK::State::getDiscreteVarLastUpdateTime ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

Return the time of last update for this discrete variable.

◆ getDiscreteVarUpdateValue()

const AbstractValue& SimTK::State::getDiscreteVarUpdateValue ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

For an auto-updating discrete variable, return the current value of its associated update cache entry; this is the value the discrete variable will have the next time it is updated.

This will fail if the value is not valid or if this is not an auto-update discrete variable.

◆ updDiscreteVarUpdateValue()

AbstractValue& SimTK::State::updDiscreteVarUpdateValue ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

For an auto-updating discrete variable, return a writable reference to the value of its associated update cache entry.

This will be the value that this discrete variable will have when it is next updated. Don't forget to mark the cache entry valid after you have updated it. This will fail if this is not an auto-update discrete variable.

◆ isDiscreteVarUpdateValueRealized()

bool SimTK::State::isDiscreteVarUpdateValueRealized ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

Check whether the update value for this auto-update discrete variable has already been computed since the last change to state variables it depends on.

◆ markDiscreteVarUpdateValueRealized()

void SimTK::State::markDiscreteVarUpdateValueRealized ( SubsystemIndex  ,
DiscreteVariableIndex   
) const
inline

Mark the update value for this auto-update discrete variable as up-to-date with respect to the state variables it depends on.

◆ updDiscreteVariable()

AbstractValue& SimTK::State::updDiscreteVariable ( SubsystemIndex  ,
DiscreteVariableIndex   
)
inline

Get a writable reference to the value stored in the indicated discrete state variable dv, and invalidate stage dv.invalidates and all higher stages.

The current time is recorded as the variable's "last update time".

◆ setDiscreteVariable()

void SimTK::State::setDiscreteVariable ( SubsystemIndex  ,
DiscreteVariableIndex  ,
const AbstractValue  
)
inline

Alternate interface to updDiscreteVariable.

◆ allocateCacheEntry() [1/2]

CacheEntryIndex SimTK::State::allocateCacheEntry ( SubsystemIndex  ,
Stage  earliest,
Stage  latest,
AbstractValue value 
) const
inline

There are two Stages supplied explicitly as arguments to this method: earliest and latest.

The earliest Stage is the stage at which the cache entry could be calculated. Hence if the Subsystem stage is reduced below earliest the cache entry is known to be invalid. The latest Stage, if any, is the stage at which the cache entry is guaranteed to have been calculated (typically as the result of a System-wide realize() call to that stage). For stages earliest through latest-1, the cache entry may be valid, if it has already been calculated. In that case an explicit validity indicator will have been set at the time it was computed, via markCacheValueRealized(). That indicator is cleared automatically whenever the Subsystem stage is reduced below earliest. The validity indicator need not have been set in order for the cache entry to be deemed valid at latest stage.

If latest is given as Stage::Infinity then there is no guarantee that this Subsystem will automatically calculate a value for this cache entry, which makes it a "lazy" evaluation that is done only if requested. In that case the only way the cache entry can become valid is if the calculation is performed and the validity indicator is set explicitly with markCacheValueRealized(). Here is how we suggest you structure lazy evaluation of a cache entry CE of type CEType and CacheEntryIndex CEIndex (this is pseudocode):

(1) Allocate your lazy cache entry something like this:

CEIndex = s.allocateLazyCacheEntry(subsys,stage,new Value<CEType>());

(2) Write a realizeCE() method structured like this:

void realizeCE(const State& s) const {
if (s.isCacheValueRealized(subsys,CEIndex))
return;
// calculate the cache entry, update with updCacheEntry()
s.markCacheValueRealized(subsys,CEIndex);
}

(3) Write a getCE() method structured like this:

const CEType& getCE(const State& s) const {
realizeCE(s); // make sure CE has been calculated
return Value<CEType>::downcast(s.getCacheEntry(subsys,CEIndex));
}

(4) Write an updCE() method like this:

CEType& updCE(const State& s) const {
return Value<CEType>::updDowncast(s.updCacheEntry(subsys,CEIndex));
}

Then access CE only through your getCE() method. There should be only one place in your code where isCacheValueRealized() and markCacheValueRealized() are called for a particular cache entry. If you do this from multiple locations there is a high probability of a bug being introduced, especially due to later modification of the code.

Prior to the Subsystem advancing to earliest stage, and prior to latest stage unless the validity indicator is set, attempts to look at the value via getCacheEntry() will throw an exception. However, you may access the cache entry for writing via updCacheEntry() any time after stage earliest-1. If you evaluate it prior to latest, be sure to explicitly mark it valid. Note that cache entries are mutable so you do not need write access to the State in order to access a cache entry for writing.

Ownership of the AbstractValue object supplied here is taken over by the State – don't delete the object after this call!

See also
getCacheEntry(), updCacheEntry()
allocateLazyCacheEntry(), isCacheValueRealized(), markCacheValueRealized()

◆ allocateCacheEntry() [2/2]

CacheEntryIndex SimTK::State::allocateCacheEntry ( SubsystemIndex  sx,
Stage  stage,
AbstractValue value 
) const
inline

This is an abbreviation for allocation of a cache entry whose earliest and latest Stages are the same.

That is, this cache entry is guaranteed to be valid if its Subsystem has advanced to the supplied Stage or later, and is guaranteed to be invalid below that Stage.

◆ allocateLazyCacheEntry()

CacheEntryIndex SimTK::State::allocateLazyCacheEntry ( SubsystemIndex  sx,
Stage  earliest,
AbstractValue value 
) const
inline

This is an abbreviation for allocation of a lazy cache entry.

The earliest stage at which this can be evaluated is provided; but there is no stage at which the cache entry will automatically be evaluated. Instead you have to evaluate it explicitly when someone asks for it, and then call markCacheValueRealized() to indicate that the value is available. The value is automatically invalidated when the indicated stage earliest is invalidated in the State.

See also
allocateCacheEntry(), isCacheValueRealized(), markCacheValueRealized()

◆ allocateCacheEntryWithPrerequisites()

CacheEntryIndex SimTK::State::allocateCacheEntryWithPrerequisites ( SubsystemIndex  ,
Stage  earliest,
Stage  latest,
bool  q,
bool  u,
bool  z,
const Array_< DiscreteVarKey > &  discreteVars,
const Array_< CacheEntryKey > &  cacheEntries,
AbstractValue value 
)
inline

(Advanced) Allocate a cache entry with prerequisites other than just reaching a particular computation stage.

Possible prerequisites are continuous variables q, u, and z; any discrete variable; and any "upstream" cache entry whose earliest stage is no later than this one's earliest stage.

◆ getCacheEntryAllocationStage()

Stage SimTK::State::getCacheEntryAllocationStage ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

At what stage was this State when this cache entry was allocated? The answer must be Stage::Empty, Stage::Topology, or Stage::Model.

◆ getCacheEntry()

const AbstractValue& SimTK::State::getCacheEntry ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

Retrieve a const reference to the value contained in a particular cache entry.

The value must be up to date with respect to the state variables it depends on or this will throw an exception. No calculation will be performed here.

See also
updCacheEntry()
allocateCacheEntry(), isCacheValueRealized(), markCacheValueRealized()

◆ updCacheEntry()

AbstractValue& SimTK::State::updCacheEntry ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

Retrieve a writable reference to the value contained in a particular cache entry.

You can access a cache entry for writing any time after it has been allocated. This does not affect the current stage. The cache entry will neither be invalidated nor marked valid by accessing it here.

See also
getCacheEntry()
allocateCacheEntry(), isCacheValueRealized(), markCacheValueRealized()

◆ isCacheValueRealized()

bool SimTK::State::isCacheValueRealized ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

Check whether the value in a particular cache entry has been recalculated since the last change to the state variables it depends on.

Validity can result either from an explicit call to markCacheValueRealized() or by this State's stage reaching the latest stage specified when the cache entry was allocated, after which the value is presumed valid. If this method returns true, then you can access the value with getCacheEntry() without getting an exception thrown.

See also
allocateCacheEntry(), markCacheValueRealized(), getCacheEntry()

◆ markCacheValueRealized()

void SimTK::State::markCacheValueRealized ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

Mark the value of a particular cache entry as up to date after it has been recalculated.

This State's current stage must be at least the earliest stage as supplied when this cache entry was allocated, and it is unnecessary to call this method if the stage has reached the specified latest stage since after that we'll presume that the cache entry's value has been realized. Note that if the latest stage was given as Stage::Infinity then it is always necessary to call this method prior to accessing the cache entry's value. After a cache entry has been marked valid here, isCacheValueRealized() will return true. The cache entry is marked invalid automatically whenever a change occurs to a state variable on which it depends.

See also
allocateCacheEntry(), isCacheValueRealized(), getCacheEntry()

◆ markCacheValueNotRealized()

void SimTK::State::markCacheValueNotRealized ( SubsystemIndex  ,
CacheEntryIndex   
) const
inline

(Advanced) Normally cache entries are invalidated automatically, however this method allows manual invalidation of the value of a particular cache entry.

After a cache entry has been marked invalid here, isCacheValueRealized() will return false.

See also
isCacheValueRealized(), markCacheValueRealized()

◆ getNY()

int SimTK::State::getNY ( ) const
inline

Get the total number ny=nq+nu+nz of shared continuous state variables.

This is also the number of state derivatives in the cache entry ydot. Callable at Model stage.

◆ getNQ() [1/2]

int SimTK::State::getNQ ( ) const
inline

Get total number of shared q's (generalized coordinates; second order state variables).

This is also the number of first and second q time derivatives in the cache entries qdot and qdotdot. Callable at Model stage.

◆ getQStart() [1/2]

SystemYIndex SimTK::State::getQStart ( ) const
inline

Returns the y index at which the q's begin. Callable at Model stage.

◆ getNU() [1/2]

int SimTK::State::getNU ( ) const
inline

Get total number of shared u's (generalized speeds; mobilities).

This is also the number of u time derivatives in the cache entry udot. Callable at Model stage.

◆ getUStart() [1/2]

SystemYIndex SimTK::State::getUStart ( ) const
inline

Returns the y index at which the u's begin. Callable at Model stage.

◆ getNZ() [1/2]

int SimTK::State::getNZ ( ) const
inline

Get total number of shared z's (auxiliary state variables).

This is also the number of z time derivatives in the cache entry zdot. Callable at Model stage.

◆ getZStart() [1/2]

SystemYIndex SimTK::State::getZStart ( ) const
inline

Returns the y index at which the z's begin. Callable at Model stage.

◆ getNYErr()

int SimTK::State::getNYErr ( ) const
inline

Get the total number nyerr=nqerr+nuerr of shared cache entries for position-level and velocity-level constraint errors.

Callable at Instance stage.

◆ getNQErr() [1/2]

int SimTK::State::getNQErr ( ) const
inline

Return the total number nqerr=mp+nQuaternions of cache entries for position-level constraint errors.

Callable at Instance stage.

◆ getQErrStart() [1/2]

SystemYErrIndex SimTK::State::getQErrStart ( ) const
inline

Returns the yErr index at which the qErr's begin. Callable at Instance stage.

◆ getNUErr() [1/2]

int SimTK::State::getNUErr ( ) const
inline

Return the total number nuerr=mp+mv of cache entries for velocity-level constraint errors (including also errors in the time derivatives of position-level constraints).

Callable at Instance stage.

◆ getUErrStart() [1/2]

SystemYErrIndex SimTK::State::getUErrStart ( ) const
inline

Returns the yErr index at which the uErr's begin. Callable at Instance stage.

◆ getNUDotErr() [1/2]

int SimTK::State::getNUDotErr ( ) const
inline

Return the total number nudotErr=mp+mv+ma of cache entries for acceleration-level constraint errors (including also errors in the second time derivatives of position-level constraints and the first time derivatives of velocity-level constraints).

Callable at Instance stage.

◆ getNMultipliers() [1/2]

int SimTK::State::getNMultipliers ( ) const
inline

Return the total number of constraint multipliers; necessarily the same as the number of acceleration-level constraint errors nUDotErr.

Callable at Instance stage.

See also
getNUDotErr()

◆ getNEventTriggers()

int SimTK::State::getNEventTriggers ( ) const
inline

Return the total number of event trigger function slots in the cache.

Callable at Instance stage.

◆ getNEventTriggersByStage() [1/2]

int SimTK::State::getNEventTriggersByStage ( Stage  ) const
inline

Return the size of the partition of event trigger functions which are evaluated at a given Stage.

Callable at Instance stage.

◆ getEventTriggerStartByStage() [1/2]

SystemEventTriggerIndex SimTK::State::getEventTriggerStartByStage ( Stage  ) const
inline

Return the index within the global event trigger array at which the first of the event triggers associated with a particular Stage are stored; the rest follow contiguously.

Callable at Instance stage.

◆ getStateLock()

std::mutex& SimTK::State::getStateLock ( ) const
inline

Returns a mutex that should be used to lock the state whenever multiple threads are asynchronously writing/updating a common state cache.

A lock should always be used when thread-safe state is not guarenteed. If multiple threads are simply reading from the cache, locking the state may not be necessary.

◆ getQStart() [2/2]

SystemQIndex SimTK::State::getQStart ( SubsystemIndex  ) const
inline

◆ getNQ() [2/2]

int SimTK::State::getNQ ( SubsystemIndex  ) const
inline

◆ getUStart() [2/2]

SystemUIndex SimTK::State::getUStart ( SubsystemIndex  ) const
inline

◆ getNU() [2/2]

int SimTK::State::getNU ( SubsystemIndex  ) const
inline

◆ getZStart() [2/2]

SystemZIndex SimTK::State::getZStart ( SubsystemIndex  ) const
inline

◆ getNZ() [2/2]

int SimTK::State::getNZ ( SubsystemIndex  ) const
inline

◆ getQErrStart() [2/2]

SystemQErrIndex SimTK::State::getQErrStart ( SubsystemIndex  ) const
inline

◆ getNQErr() [2/2]

int SimTK::State::getNQErr ( SubsystemIndex  ) const
inline

◆ getUErrStart() [2/2]

SystemUErrIndex SimTK::State::getUErrStart ( SubsystemIndex  ) const
inline

◆ getNUErr() [2/2]

int SimTK::State::getNUErr ( SubsystemIndex  ) const
inline

◆ getUDotErrStart()

SystemUDotErrIndex SimTK::State::getUDotErrStart ( SubsystemIndex  ) const
inline

◆ getNUDotErr() [2/2]

int SimTK::State::getNUDotErr ( SubsystemIndex  ) const
inline

◆ getMultipliersStart()

SystemMultiplierIndex SimTK::State::getMultipliersStart ( SubsystemIndex  ) const
inline

◆ getNMultipliers() [2/2]

int SimTK::State::getNMultipliers ( SubsystemIndex  ) const
inline

◆ getEventTriggerStartByStage() [2/2]

SystemEventTriggerByStageIndex SimTK::State::getEventTriggerStartByStage ( SubsystemIndex  ,
Stage   
) const
inline

◆ getNEventTriggersByStage() [2/2]

int SimTK::State::getNEventTriggersByStage ( SubsystemIndex  ,
Stage   
) const
inline

◆ getEventTriggers()

const Vector& SimTK::State::getEventTriggers ( ) const
inline

◆ getEventTriggersByStage() [1/2]

const Vector& SimTK::State::getEventTriggersByStage ( Stage  ) const
inline

◆ getEventTriggersByStage() [2/2]

const Vector& SimTK::State::getEventTriggersByStage ( SubsystemIndex  ,
Stage   
) const
inline

◆ updEventTriggers()

Vector& SimTK::State::updEventTriggers ( ) const
inline

◆ updEventTriggersByStage() [1/2]

Vector& SimTK::State::updEventTriggersByStage ( Stage  ) const
inline

◆ updEventTriggersByStage() [2/2]

Vector& SimTK::State::updEventTriggersByStage ( SubsystemIndex  ,
Stage   
) const
inline

◆ getQ() [1/2]

const Vector& SimTK::State::getQ ( SubsystemIndex  ) const
inline

Per-subsystem access to the global shared variables.

◆ getU() [1/2]

const Vector& SimTK::State::getU ( SubsystemIndex  ) const
inline

◆ getZ() [1/2]

const Vector& SimTK::State::getZ ( SubsystemIndex  ) const
inline

◆ getUWeights() [1/2]

const Vector& SimTK::State::getUWeights ( SubsystemIndex  ) const
inline

◆ getZWeights() [1/2]

const Vector& SimTK::State::getZWeights ( SubsystemIndex  ) const
inline

◆ updQ() [1/2]

Vector& SimTK::State::updQ ( SubsystemIndex  )
inline

◆ updU() [1/2]

Vector& SimTK::State::updU ( SubsystemIndex  )
inline

◆ updZ() [1/2]

Vector& SimTK::State::updZ ( SubsystemIndex  )
inline

◆ updUWeights() [1/2]

Vector& SimTK::State::updUWeights ( SubsystemIndex  )
inline

◆ updZWeights() [1/2]

Vector& SimTK::State::updZWeights ( SubsystemIndex  )
inline

◆ getQDot() [1/2]

const Vector& SimTK::State::getQDot ( SubsystemIndex  ) const
inline

Per-subsystem access to the shared cache entries.

◆ getUDot() [1/2]

const Vector& SimTK::State::getUDot ( SubsystemIndex  ) const
inline

◆ getZDot() [1/2]

const Vector& SimTK::State::getZDot ( SubsystemIndex  ) const
inline

◆ getQDotDot() [1/2]

const Vector& SimTK::State::getQDotDot ( SubsystemIndex  ) const
inline

◆ updQDot() [1/2]

Vector& SimTK::State::updQDot ( SubsystemIndex  ) const
inline

◆ updUDot() [1/2]

Vector& SimTK::State::updUDot ( SubsystemIndex  ) const
inline

◆ updZDot() [1/2]

Vector& SimTK::State::updZDot ( SubsystemIndex  ) const
inline

◆ updQDotDot() [1/2]

Vector& SimTK::State::updQDotDot ( SubsystemIndex  ) const
inline

◆ getQErr() [1/2]

const Vector& SimTK::State::getQErr ( SubsystemIndex  ) const
inline

◆ getUErr() [1/2]

const Vector& SimTK::State::getUErr ( SubsystemIndex  ) const
inline

◆ getUDotErr() [1/2]

const Vector& SimTK::State::getUDotErr ( SubsystemIndex  ) const
inline

◆ getMultipliers() [1/2]

const Vector& SimTK::State::getMultipliers ( SubsystemIndex  ) const
inline

◆ getQErrWeights() [1/2]

const Vector& SimTK::State::getQErrWeights ( SubsystemIndex  ) const
inline

◆ getUErrWeights() [1/2]

const Vector& SimTK::State::getUErrWeights ( SubsystemIndex  ) const
inline

◆ updQErr() [1/2]

Vector& SimTK::State::updQErr ( SubsystemIndex  ) const
inline

◆ updUErr() [1/2]

Vector& SimTK::State::updUErr ( SubsystemIndex  ) const
inline

◆ updUDotErr() [1/2]

Vector& SimTK::State::updUDotErr ( SubsystemIndex  ) const
inline

◆ updMultipliers() [1/2]

Vector& SimTK::State::updMultipliers ( SubsystemIndex  ) const
inline

◆ updQErrWeights() [1/2]

Vector& SimTK::State::updQErrWeights ( SubsystemIndex  )
inline

◆ updUErrWeights() [1/2]

Vector& SimTK::State::updUErrWeights ( SubsystemIndex  )
inline

◆ getTime()

const Real& SimTK::State::getTime ( ) const
inline

You can call these as long as system stage >= Model.

◆ getY()

const Vector& SimTK::State::getY ( ) const
inline

◆ getQ() [2/2]

const Vector& SimTK::State::getQ ( ) const
inline

These are just views into Y.

◆ getU() [2/2]

const Vector& SimTK::State::getU ( ) const
inline

◆ getZ() [2/2]

const Vector& SimTK::State::getZ ( ) const
inline

◆ getUWeights() [2/2]

const Vector& SimTK::State::getUWeights ( ) const
inline

Get a unit weighting (1/unit change) for each u that can be used to weight a vector du so that the disparate elements are comparable in physical effect.

This permits mixing of generalized speeds that have different units, and scaling of generalized speeds that have differing amounts of leverage due to their positions in the multibody tree. This can be used to create a scaled norm that represents the overall significance of a change du to u.

Define a unit change di for each ui such that a change ui+eps*di to each generalized speed in turn produces a physical velocity change of roughly equal significance. Then a diagonal matrix Wu=diag(1/di) is a weighting matrix such that wdu=Wu*du is a vector in which each element wdu_i has units of "unit change" for its corresponding ui. This method returns a vector which is the diagonal of Wu.

These same weights on u also determine the scaling of the generalized coordinates q, because q and u are related via qdot=N*u. For cases where qdot_i=u_i, the numerical value of the unit change to q_i is just di because dP/dq_i == dV/du_i. Otherwise, they are related by Wq = N*Wu*pinv(N) where Wq is the weighting matrix for dq (block diagonal), and pinv() is the pseudoinverse.

For example, say you define unit scaling for an angle coordinate to be 1 radian (about 57 degrees), meaning that a 1 radian change of coordinate produces (roughly) one length unit of meaningful position change. Then if a generalized coordinate is measured in radians, its unit scale would be 1. If instead you created a generalized coordinate with units of degrees, its unit scale would be 57 degrees. That would allow mixing of such coordinates in the same system by bringing the coordinates into a physically-meaningful basis. Scaling is defined in the u basis where each variable is independent; the N matrix couples variables in the q basis. So here the units would actually be 1 radian/time unit and 57 degrees/time unit (numerically identical).

This is allocated and set to 1 at the end of realize(Model).

◆ getZWeights() [2/2]

const Vector& SimTK::State::getZWeights ( ) const
inline

Get a unit weighting (1/unit change) for each z that can be used to weight a vector dz so that the disparate elements are comparable in physical effect.

This defines a weighting matrix Wz=diag(1/unitchange_zi) such that wdz=Wz*dz is a vector in which each element wdz_i has units of "unit change" for its corresponding zi. This method returns a vector which is the diagonal of Wz.

◆ updUWeights() [2/2]

Vector& SimTK::State::updUWeights ( )
inline

Set u weights (and q weights indirectly).

You can call this after Model stage has been realized. This will invalidate just Report stage because it is not used in calculating udots.

◆ updZWeights() [2/2]

Vector& SimTK::State::updZWeights ( )
inline

Set z weights.

You can call this after Model stage has been realized. This will invalidate just Report stage because it is not used in calculating zdots.

◆ updTime()

Real& SimTK::State::updTime ( )
inline

You can call these as long as System stage >= Model, but the stage will be backed up if necessary to the indicated stage.

◆ updY()

Vector& SimTK::State::updY ( )
inline

◆ setTime()

void SimTK::State::setTime ( Real  t)
inline

An alternate syntax equivalent to updTime() and updY().

◆ setY()

void SimTK::State::setY ( const Vector y)
inline

◆ updQ() [2/2]

Vector& SimTK::State::updQ ( )
inline

These are just views into Y.

◆ updU() [2/2]

Vector& SimTK::State::updU ( )
inline

◆ updZ() [2/2]

Vector& SimTK::State::updZ ( )
inline

◆ setQ()

void SimTK::State::setQ ( const Vector q)
inline

Alternate interface.

◆ setU()

void SimTK::State::setU ( const Vector u)
inline

◆ setZ()

void SimTK::State::setZ ( const Vector z)
inline

◆ getYDot()

const Vector& SimTK::State::getYDot ( ) const
inline

◆ getQDot() [2/2]

const Vector& SimTK::State::getQDot ( ) const
inline

These are just views into YDot.

◆ getZDot() [2/2]

const Vector& SimTK::State::getZDot ( ) const
inline

◆ getUDot() [2/2]

const Vector& SimTK::State::getUDot ( ) const
inline

◆ getQDotDot() [2/2]

const Vector& SimTK::State::getQDotDot ( ) const
inline

This has its own space, not a view.

◆ updYDot()

Vector& SimTK::State::updYDot ( ) const
inline

These are mutable.

◆ updQDot() [2/2]

Vector& SimTK::State::updQDot ( ) const
inline

◆ updZDot() [2/2]

Vector& SimTK::State::updZDot ( ) const
inline

◆ updUDot() [2/2]

Vector& SimTK::State::updUDot ( ) const
inline

◆ updQDotDot() [2/2]

Vector& SimTK::State::updQDotDot ( ) const
inline

This is a separate shared cache entry, not part of YDot.

If you have a direct 2nd order integrator you can integrate QDotDot (twice) to get Q.

◆ getYErr()

const Vector& SimTK::State::getYErr ( ) const
inline

Return the current constraint errors for all constraints.

This is {QErr,UErr} packed and in that order.

◆ getQErr() [2/2]

const Vector& SimTK::State::getQErr ( ) const
inline

These are just views into YErr.

◆ getUErr() [2/2]

const Vector& SimTK::State::getUErr ( ) const
inline

◆ getUDotErr() [2/2]

const Vector& SimTK::State::getUDotErr ( ) const
inline

These have their own space, they are not views.

◆ getMultipliers() [2/2]

const Vector& SimTK::State::getMultipliers ( ) const
inline

◆ getQErrWeights() [2/2]

const Vector& SimTK::State::getQErrWeights ( ) const
inline

Get the unit weighting (1/unit error) for each of the mp+mquat position inline constraints equations.

Allocated and initialized to 1 on realize(Instance).

◆ getUErrWeights() [2/2]

const Vector& SimTK::State::getUErrWeights ( ) const
inline

Get the unit weighting (1/unit error) for each of the mp+mv velocity-level inline constraint equations, meaning mp time derivatives of position (holonomic) inline constraint equations followed by mv velocity (nonholonomic) constraints.

Typically the weight of position constraint derivatives is just the position constraint weight times the System's characteristic time scale.

There is no entry corresponding to quaternions here since they do not produce velocity-level constraints in Simbody's forumulation.

This is allocated and initialized to 1 on realize(Instance).

◆ updQErrWeights() [2/2]

Vector& SimTK::State::updQErrWeights ( )
inline

Set the unit weighting (1/unit error) for each of the mp+mquat position inline constraint equations.

You can call this after the weight variable is allocated at the end of Instance stage. Position stage is invalidated to force recalculation of weighted position constraint errors.

◆ updUErrWeights() [2/2]

Vector& SimTK::State::updUErrWeights ( )
inline

Set the unit weighting (1/unit error) for each of the mp+mv velocity-level inline constraints.

You can call this after the weight variable is allocated at the end of Instance stage. Velocity stage is invalidated to force recalculation of weighted velocity-level constraint errors.

◆ updYErr()

Vector& SimTK::State::updYErr ( ) const
inline

These are mutable.

◆ updQErr() [2/2]

Vector& SimTK::State::updQErr ( ) const
inline

◆ updUErr() [2/2]

Vector& SimTK::State::updUErr ( ) const
inline

◆ updUDotErr() [2/2]

Vector& SimTK::State::updUDotErr ( ) const
inline

◆ updMultipliers() [2/2]

Vector& SimTK::State::updMultipliers ( ) const
inline

◆ getSystemStageVersions()

void SimTK::State::getSystemStageVersions ( Array_< StageVersion > &  versions) const
inline

(Advanced) Record the current version numbers of each valid System-level stage.

This can be used to unambiguously determine what stages have been changed by some opaque operation, even if that operation realized the stages after modifying them. This is particularly useful for event handlers as a way for a time stepper to know how much damage may have been done by a handler, and thus how much reinitialization is required before continuing on.

See also
getLowestSystemStageDifference()

◆ getLowestSystemStageDifference()

Stage SimTK::State::getLowestSystemStageDifference ( const Array_< StageVersion > &  prevVersions) const
inline

(Advanced) Given a list of per-stage version numbers extracted by an earlier call to getSystemStageVersions(), note the lowest system stage in the current State whose version number differs from the corresponding previous version number.

Returns Stage::Infinity if all the stages present in prevVersions are valid and have identical versions now, even if there are additional valid stages now, since nothing the caller cared about before has been changed. If the current State is not realized as far as the previous one, then the first unrealized stage is returned if all the lower versions match.

See also
getSystemStageVersions()

◆ setSystemTopologyStageVersion()

void SimTK::State::setSystemTopologyStageVersion ( StageVersion  topoVersion)
inline

(Advanced) This explicitly modifies the Topology stage version; don't use this method unless you know what you're doing! This can be used to force compatibility with a System that has had Topology changes since this State was created.

This has no effect on the realization level.

See also
getSystemTopologyStageVersion(), System::getSystemTopologyCacheVersion()

◆ getQValueVersion()

ValueVersion SimTK::State::getQValueVersion ( ) const
inline

(Advanced) Return a ValueVersion for q, meaning an integer that is incremented whenever any q is changed (or more precisely whenever q or y is returned with writable access).

Will be 1 or greater if q has been allocated.

◆ getUValueVersion()

ValueVersion SimTK::State::getUValueVersion ( ) const
inline

(Advanced) Return a ValueVersion for u, meaning an integer that is incremented whenever any u is changed (or more precisely whenever u or y is returned with writable access).

Will be 1 or greater if u has been allocated.

◆ getZValueVersion()

ValueVersion SimTK::State::getZValueVersion ( ) const
inline

(Advanced) Return a ValueVersion for z, meaning an integer that is incremented whenever any z is changed (or more precisely whenever z or y is returned with writable access).

Will be 1 or greater if z has been allocated.

◆ getQDependents()

const ListOfDependents& SimTK::State::getQDependents ( ) const
inline

(Advanced) Return the list of cache entries for which q was specified as an explicit prerequisite.

See also
allocateCacheEntryWithPrerequisites()

◆ getUDependents()

const ListOfDependents& SimTK::State::getUDependents ( ) const
inline

(Advanced) Return the list of cache entries for which u was specified as an explicit prerequisite.

See also
allocateCacheEntryWithPrerequisites()

◆ getZDependents()

const ListOfDependents& SimTK::State::getZDependents ( ) const
inline

(Advanced) Return the list of cache entries for which z was specified as an explicit prerequisite.

See also
allocateCacheEntryWithPrerequisites()

◆ hasCacheEntry()

bool SimTK::State::hasCacheEntry ( const CacheEntryKey cacheEntry) const
inline

(Advanced) Check whether this State has a particular cache entry.

◆ getCacheEntryInfo()

const CacheEntryInfo& SimTK::State::getCacheEntryInfo ( const CacheEntryKey cacheEntry) const

(Advanced) Return a const reference to the cache entry information for a particular cache entry.

No validity checking is performed.

◆ updCacheEntryInfo()

CacheEntryInfo& SimTK::State::updCacheEntryInfo ( const CacheEntryKey cacheEntry)

(Advanced) Return a writable reference to the cache entry information for a particular cache entry.

No validity checking is performed.

◆ hasDiscreteVar()

bool SimTK::State::hasDiscreteVar ( const DiscreteVarKey discreteVar) const
inline

(Advanced) Check whether this State has a particular discrete state variable.

◆ getDiscreteVarInfo()

const DiscreteVarInfo& SimTK::State::getDiscreteVarInfo ( const DiscreteVarKey discreteVar) const

(Advanced) Return a reference to the discrete variable information for a particular discrete variable.

◆ getPerSubsystemInfo()

const PerSubsystemInfo& SimTK::State::getPerSubsystemInfo ( SubsystemIndex  ) const

(Advanced) Return a reference to the per-subsystem information in the state.

◆ autoUpdateDiscreteVariables()

void SimTK::State::autoUpdateDiscreteVariables ( )
inline

(Advanced) This is called at the beginning of every integration step to set the values of auto-update discrete variables from the values stored in their associated cache entries.

◆ toString()

String SimTK::State::toString ( ) const
inline

(Debugging) Not suitable for serialization.

◆ cacheToString()

String SimTK::State::cacheToString ( ) const
inline

(Debugging) Not suitable for serialization.


The documentation for this class was generated from the following file: