This is the handle class for the hidden State implementation. More...

#include <State.h>

Public Member Functions
	State ()
	Create an empty State.
	~State ()
void	clear ()
	Restore State to default-constructed condition.
void	setNumSubsystems (int i)
	Set the number of subsystems in this state.
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.
	State (const State &)
	Make the current State a copy of the source state, copying only state variables and not the cache.
State &	operator= (const State &)
	Make the current State a copy of the source state, copying only state variables and not the cache.
SubsystemIndex	addSubsystem (const String &name, const String &version)
	Register a new subsystem as a client of this State.
int	getNumSubsystems () const
const String &	getSubsystemName (SubsystemIndex) const
const String &	getSubsystemVersion (SubsystemIndex) const
const Stage &	getSubsystemStage (SubsystemIndex) const
const Stage &	getSystemStage () const
	This returns the global stage for this State.
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.
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.
void	advanceSubsystemToStage (SubsystemIndex, Stage) const
	Advance a particular Subsystem's current stage by one to the indicated stage.
void	advanceSystemToStage (Stage) const
	Advance the System-level current stage by one to the indicated stage.
QIndex	allocateQ (SubsystemIndex, const Vector &qInit)
	These continuous state variables are shared among all the Subsystems and are not allocated until the System is advanced to Stage::Model.
UIndex	allocateU (SubsystemIndex, const Vector &uInit)
ZIndex	allocateZ (SubsystemIndex, const Vector &zInit)
QErrIndex	allocateQErr (SubsystemIndex, int nqerr) const
	These constraint error cache entries are shared among all the subsystems and are not allocated until the System is advanced to Stage::Instance.
UErrIndex	allocateUErr (SubsystemIndex, int nuerr) const
UDotErrIndex	allocateUDotErr (SubsystemIndex, int nudoterr) const
EventIndex	allocateEventIndex (SubsystemIndex, int nevent=1) const
	This method is used to obtain one or more consecutive EventIndex's which are unique within the indicated Subsystem.
EventTriggerByStageIndex	allocateEventTrigger (SubsystemIndex, Stage, EventIndex, int nevent=1) const
	Some Events require a slot in the State cache to hold the current value of the event trigger function (a.k.a.
EventTriggerByStageIndex	allocateEventTrigger (SubsystemIndex, Stage, int nevent) const
const Vector &	getEventTriggers () const
const Vector &	getEventTriggersByStage (Stage) const
const Vector &	getEventTriggersByStage (SubsystemIndex, Stage) const
Vector &	updEventTriggers () const
Vector &	updEventTriggersByStage (Stage) const
Vector &	updEventTriggersByStage (SubsystemIndex, Stage) const
const Vector &	getQ (SubsystemIndex) const
	Per-subsystem access to the global shared variables.
const Vector &	getU (SubsystemIndex) const
const Vector &	getZ (SubsystemIndex) const
Vector &	updQ (SubsystemIndex)
Vector &	updU (SubsystemIndex)
Vector &	updZ (SubsystemIndex)
const Vector &	getQDot (SubsystemIndex) const
	Per-subsystem access to the shared cache entries.
const Vector &	getUDot (SubsystemIndex) const
const Vector &	getZDot (SubsystemIndex) const
const Vector &	getQDotDot (SubsystemIndex) const
Vector &	updQDot (SubsystemIndex) const
Vector &	updUDot (SubsystemIndex) const
Vector &	updZDot (SubsystemIndex) const
Vector &	updQDotDot (SubsystemIndex) const
const Vector &	getQErr (SubsystemIndex) const
const Vector &	getUErr (SubsystemIndex) const
const Vector &	getUDotErr (SubsystemIndex) const
const Vector &	getMultipliers (SubsystemIndex) const
Vector &	updQErr (SubsystemIndex) const
Vector &	updUErr (SubsystemIndex) const
Vector &	updUDotErr (SubsystemIndex) const
Vector &	updMultipliers (SubsystemIndex) const
const Real &	getTime () const
	You can call these as long as system stage >= Model.
const Vector &	getY () const
const Vector &	getQ () const
	These are just views into Y.
const Vector &	getU () const
const Vector &	getZ () const
Real &	updTime ()
	You can call these as long as System stage >= Model, but the stage will be backed up if necessary to the indicated stage.
Vector &	updY ()
void	setTime (Real t)
	An alternate syntax equivalent to updTime() and updY().
void	setY (const Vector &y)
Vector &	updQ ()
	These are just views into Y.
Vector &	updU ()
Vector &	updZ ()
void	setQ (const Vector &q)
	Alternate interface.
void	setU (const Vector &u)
void	setZ (const Vector &z)
const Vector &	getYDot () const
const Vector &	getQDot () const
	These are just views into YDot.
const Vector &	getZDot () const
const Vector &	getUDot () const
const Vector &	getQDotDot () const
	This has its own space, not a view.
Vector &	updYDot () const
	These are mutable.
Vector &	updQDot () const
Vector &	updZDot () const
Vector &	updUDot () const
Vector &	updQDotDot () const
	This is a separate shared cache entry, not part of YDot.
const Vector &	getYErr () const
	Return the current constraint errors for all constraints.
const Vector &	getQErr () const
	These are just views into YErr.
const Vector &	getUErr () const
const Vector &	getUDotErr () const
	These have their own space, they are not views.
const Vector &	getMultipliers () const
Vector &	updYErr () const
	These are mutable.
Vector &	updQErr () const
Vector &	updUErr () const
Vector &	updUDotErr () const
Vector &	updMultipliers () const
const Stage &	getLowestStageModified () const
	Return the lowest System Stage that was invalidated since the last time this "low water mark" was reset.
void	resetLowestStageModified () const
	Reset the invalid System Stage "low water mark" to the one just above the State's current System Stage.
void	autoUpdateDiscreteVariables ()
	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.
String	toString () const
String	cacheToString () const
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 but there is no corresponding global index.
DiscreteVariableIndex	allocateDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *)
	The Stage supplied here in the call is the lowest subsystem stage which is invalidated by a change made to this discrete variable.
DiscreteVariableIndex	allocateAutoUpdateDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *, Stage updateDependsOn)
	This method allocates a DiscreteVariable whose value should be updated automatically after each time step.
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.
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.
Stage	getDiscreteVarInvalidatesStage (SubsystemIndex, DiscreteVariableIndex) const
	What is the lowest stage that is invalidated when this discrete variable is modified? All higher stages are also invalidated.
const AbstractValue &	getDiscreteVariable (SubsystemIndex, DiscreteVariableIndex) const
	Get the current value of the indicated discrete variable.
Real	getDiscreteVarLastUpdateTime (SubsystemIndex, DiscreteVariableIndex) const
	Return the time of last update for this discrete variable.
const AbstractValue &	getDiscreteVarUpdateValue (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.
AbstractValue &	updDiscreteVarUpdateValue (SubsystemIndex, DiscreteVariableIndex) const
	For an auto-updating discrete variable, return a writable reference to the value of its associated update cache entry.
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.
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.
AbstractValue &	updDiscreteVariable (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.
void	setDiscreteVariable (SubsystemIndex, DiscreteVariableIndex, const AbstractValue &)
	Alternate interface to updDiscreteVariable.
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 *) const
	There are two Stages supplied explicitly as arguments to this method: earliest and latest.
CacheEntryIndex	allocateCacheEntry (SubsystemIndex sx, Stage g, AbstractValue *v) const
	This is an abbreviation for allocation of a cache entry whose earliest and latest Stages are the same.
CacheEntryIndex	allocateLazyCacheEntry (SubsystemIndex sx, Stage earliest, AbstractValue *v) const
	This is an abbreviation for allocation of a lazy cache entry.
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.
const AbstractValue &	getCacheEntry (SubsystemIndex, CacheEntryIndex) const
	Retrieve a const reference to the value contained in a particular cache entry.
AbstractValue &	updCacheEntry (SubsystemIndex, CacheEntryIndex) const
	Retrieve a writable reference to the value contained in a particular cache entry.
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.
void	markCacheValueRealized (SubsystemIndex, CacheEntryIndex) const
	Mark the value of a particular cache entry as up to date after it has been recalculated.
void	markCacheValueNotRealized (SubsystemIndex, CacheEntryIndex) const
	Normally cache entries are invalidated automatically, however this method allows manual invalidation of the value of a particular cache entry.
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.
int	getNQ () const
	Get total number of shared q's (generalized coordinates; second order state variables).
SystemYIndex	getQStart () const
	Returns the y index at which the q's begin. Callable at Model stage.
int	getNU () const
	Get total number of shared u's (generalized speeds; mobilities).
SystemYIndex	getUStart () const
	Returns the y index at which the u's begin. Callable at Model stage.
int	getNZ () const
	Get total number of shared z's (auxiliary state variables).
SystemYIndex	getZStart () const
	Returns the y index at which the z's begin. Callable at Model stage.
int	getNYErr () const
	Get the total number nyerr=nqerr+nuerr of shared cache entries for position-level and velocity-level constraint errors.
int	getNQErr () const
	Return the total number nqerr=mp+nQuaternions of cache entries for position-level constraint errors.
SystemYErrIndex	getQErrStart () const
	Returns the yErr index at which the qErr's begin. Callable at Instance stage.
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).
SystemYErrIndex	getUErrStart () const
	Returns the yErr index at which the uErr's begin. Callable at Instance stage.
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).
int	getNMultipliers () const
	Return the total number of constraint multipliers; necessarily the same as the number of acceleration-level constraint errors nUDotErr.
int	getNEventTriggers () const
	Return the total number of event trigger function slots in the cache.
int	getNEventTriggersByStage (Stage) const
	Return the size of the partition of event trigger functions which are evaluated at a given Stage.
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.
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
Global-to-Subsystem Maps
Once the dimensions and allocations of the global shared resources are known, you can call these methods to map a global resource index to Subsystem to which it belongs and the index by which that resource is known locally to the Subsystem. See also: Global Resource Dimensions Per-Subsystem Dimensions group
void	mapQToSubsystem (SystemQIndex, SubsystemIndex &, QIndex &) const
	For a given global q, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.
void	mapUToSubsystem (SystemUIndex, SubsystemIndex &, UIndex &) const
	For a given global u, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.
void	mapZToSubsystem (SystemZIndex, SubsystemIndex &, ZIndex &) const
	For a given global z, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.
void	mapQErrToSubsystem (SystemQErrIndex, SubsystemIndex &, QErrIndex &) const
	For a given global qErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.
void	mapUErrToSubsystem (SystemUErrIndex, SubsystemIndex &, UErrIndex &) const
	For a given global uErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.
void	mapUDotErrToSubsystem (SystemUDotErrIndex, SubsystemIndex &, UDotErrIndex &) const
	For a given global uDotErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.
void	mapMultiplierToSubsystem (SystemMultiplierIndex, SubsystemIndex &, MultiplierIndex &) const
	For a given global multiplier index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.
void	mapEventTriggerToSubsystem (SystemEventTriggerIndex, SubsystemIndex &, EventTriggerIndex &) const
	For a given global event trigger function index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.
void	mapEventTriggerToStage (SystemEventTriggerIndex, Stage &, SystemEventTriggerByStageIndex &) const
	For a given global event trigger function index, return the Stage at which that trigger function should be evaluated; callable at Instance stage.
void	mapSubsystemEventTriggerToStage (EventTriggerIndex, Stage &, EventTriggerByStageIndex &) const
	Given a Subsystem-wide event index, map that to a particular Stage and an index within that Stage.

Detailed Description

This is the handle class for the hidden State implementation.

This object is intended to contain all State information for a SimTK::System, except topological information which is stored in the System itself. A System is "const" after its topology has been constructed and realized.

Systems are composed of Subsystems, and the 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 occurence 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)

      (7) udotErr = [ pdotdot(d;t,q,u,udot) ] = 0
                    [ vdot(d;t,q,u,udot)    ]
                    [ a(d;t,q,u,udot)       ]

      (8) uErr    = [ pdot(d;t,q,u) ]
                    [ v(d;t,q,u)    ]         = 0

      (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.

Constructor & Destructor Documentation

SimTK::State::State ( )

Create an empty State.

SimTK::State::~State ( )

SimTK::State::State ( const State & )

Make the current State a copy of the source state, copying only state variables and not the cache.

If the source state hasn't been realized to Model stage, then we don't copy its state variables either, except those associated with the Topology stage.

Member Function Documentation

void SimTK::State::clear ( )

Restore State to default-constructed condition.

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

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!

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

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

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

Make the current State a copy of the source state, copying only state variables and not the cache.

If the source state hasn't been realized to Model stage, then we don't copy its state variables either, except those associated with the Topology stage.

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

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.

int SimTK::State::getNumSubsystems ( ) const

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

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

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

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

This returns the *global* stage for this State.

void SimTK::State::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.

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.

void SimTK::State::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.

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.

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

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()

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

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()

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

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.

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

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

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

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.

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

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

EventIndex SimTK::State::allocateEventIndex	(	SubsystemIndex	,
		int	nevent = `1`
	)		const

This method is used to obtain one or more consecutive EventIndex's which are unique within the indicated Subsystem.

These can be allocated in a State that has not yet been advanced to Instance stage, and the stage at which they are allocated is remembered so that reducing the stage below that causes the more-recently-allocated EventIndex's to be forgotten. When Instance stage is realized, global SystemEventIndex's will be allocated such that each (Subsystem,EventIndex) pair has a unique SystemEventIndex. Also, SystemEventIndex's are doled out consecutively within each Subsystem so finding the first one allows you to compute the rest for a given Subsystem.

EventTriggerByStageIndex SimTK::State::allocateEventTrigger	(	SubsystemIndex	,
		Stage	,
		EventIndex	,
		int	nevent = `1`
	)		const

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 SimTK::State::allocateEventTrigger	(	SubsystemIndex	,
		Stage	,
		int	nevent
	)		const

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

The Stage supplied here in the call is the lowest 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()

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

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.

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()

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

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

This is the same index as was returned by allocateAutoUpdateDiscreteVariable().

Stage SimTK::State::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.

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

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

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

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

Get the current value of the indicated discrete variable.

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

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

Return the time of last update for this discrete variable.

const AbstractValue& SimTK::State::getDiscreteVarUpdateValue	(	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.

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

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

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.

bool SimTK::State::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.

void SimTK::State::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.

AbstractValue& SimTK::State::updDiscreteVariable	(	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.

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

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

Alternate interface to updDiscreteVariable.

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

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 probabily 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()

CacheEntryIndex SimTK::State::allocateCacheEntry	(	SubsystemIndex	sx,
		Stage	g,
		AbstractValue *	v
	)		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.

CacheEntryIndex SimTK::State::allocateLazyCacheEntry	(	SubsystemIndex	sx,
		Stage	earliest,
		AbstractValue *	v
	)		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()

Stage SimTK::State::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.

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

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()

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

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()

bool SimTK::State::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.

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()

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

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()

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

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()

int SimTK::State::getNY ( ) const

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.

int SimTK::State::getNQ ( ) const

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.

SystemYIndex SimTK::State::getQStart ( ) const

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

int SimTK::State::getNU ( ) const

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.

SystemYIndex SimTK::State::getUStart ( ) const

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

int SimTK::State::getNZ ( ) const

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.

SystemYIndex SimTK::State::getZStart ( ) const

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

int SimTK::State::getNYErr ( ) const

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

Callable at Instance stage.

int SimTK::State::getNQErr ( ) const

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

Callable at Instance stage.

SystemYErrIndex SimTK::State::getQErrStart ( ) const

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

int SimTK::State::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).

Callable at Instance stage.

SystemYErrIndex SimTK::State::getUErrStart ( ) const

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

int SimTK::State::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).

Callable at Instance stage.

int SimTK::State::getNMultipliers ( ) const

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()

int SimTK::State::getNEventTriggers ( ) const

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

Callable at Instance stage.

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

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

Callable at Instance stage.

SystemEventTriggerIndex SimTK::State::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.

Callable at Instance stage.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void SimTK::State::mapQToSubsystem	(	SystemQIndex	,
		SubsystemIndex &	,
		QIndex &
	)		const

For a given global q, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.

void SimTK::State::mapUToSubsystem	(	SystemUIndex	,
		SubsystemIndex &	,
		UIndex &
	)		const

For a given global u, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.

void SimTK::State::mapZToSubsystem	(	SystemZIndex	,
		SubsystemIndex &	,
		ZIndex &
	)		const

For a given global z, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Model stage.

void SimTK::State::mapQErrToSubsystem	(	SystemQErrIndex	,
		SubsystemIndex &	,
		QErrIndex &
	)		const

For a given global qErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.

void SimTK::State::mapUErrToSubsystem	(	SystemUErrIndex	,
		SubsystemIndex &	,
		UErrIndex &
	)		const

For a given global uErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.

void SimTK::State::mapUDotErrToSubsystem	(	SystemUDotErrIndex	,
		SubsystemIndex &	,
		UDotErrIndex &
	)		const

For a given global uDotErr index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.

void SimTK::State::mapMultiplierToSubsystem	(	SystemMultiplierIndex	,
		SubsystemIndex &	,
		MultiplierIndex &
	)		const

For a given global multiplier index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.

This is necessarily the same Subsystme and index as for the corresponding global uDotErr.

void SimTK::State::mapEventTriggerToSubsystem	(	SystemEventTriggerIndex	,
		SubsystemIndex &	,
		EventTriggerIndex &
	)		const

For a given global event trigger function index, return the Subsystem that allocated it and the Subsystem-local index by which it is known; callable at Instance stage.

void SimTK::State::mapEventTriggerToStage	(	SystemEventTriggerIndex	,
		Stage &	,
		SystemEventTriggerByStageIndex &
	)		const

For a given global event trigger function index, return the Stage at which that trigger function should be evaluated; callable at Instance stage.

void SimTK::State::mapSubsystemEventTriggerToStage	(	EventTriggerIndex	,
		Stage &	,
		EventTriggerByStageIndex &
	)		const

Given a Subsystem-wide event index, map that to a particular Stage and an index within that Stage.

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

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

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

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

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

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

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

Per-subsystem access to the global shared variables.

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

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

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

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

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

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

Per-subsystem access to the shared cache entries.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

These are just views into Y.

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

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

Real& SimTK::State::updTime ( )

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

Vector& SimTK::State::updY ( )

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

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

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

Vector& SimTK::State::updQ ( )

These are just views into Y.

Vector& SimTK::State::updU ( )

Vector& SimTK::State::updZ ( )

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

Alternate interface.

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

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

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

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

These are just views into YDot.

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

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

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

This has its own space, not a view.

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

These are mutable.

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

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

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

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

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.

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

Return the current constraint errors for all constraints.

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

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

These are just views into YErr.

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

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

These have their own space, they are not views.

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

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

These are mutable.

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

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

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

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

const Stage& SimTK::State::getLowestStageModified ( ) const

Return the lowest System Stage that was invalidated since the last time this "low water mark" was reset.

The returned value is never higher than the one just following the State's current System Stage, but can be lower.

void SimTK::State::resetLowestStageModified ( ) const

Reset the invalid System Stage "low water mark" to the one just above the State's current System Stage.

void SimTK::State::autoUpdateDiscreteVariables ( )

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.

String SimTK::State::toString ( ) const

String SimTK::State::cacheToString ( ) const

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

State.h

SimTK::State Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation