State Class Reference

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	setNSubsystems (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	getNSubsystems () 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) 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.
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
DiscreteVariableIndex	allocateDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *)
	You can allocate a new DiscreteVariable in any State whose stage has not yet been advanced to Model stage.
std::pair < DiscreteVariableIndex, CacheEntryIndex >	allocateUpdatingDiscreteVariable (SubsystemIndex, Stage invalidates, AbstractValue *, Stage earliestUpdate)
	This method allocates a DiscreteVariable and a CacheEntry of the same value type.
CacheEntryIndex	allocateCacheEntry (SubsystemIndex, Stage earliest, Stage latest, AbstractValue *) const
	You can allocate a new CacheEntry in any State whose stage has not yet been advanced to Instance stage.
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.
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, the 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 AbstractValue &	getDiscreteVariable (SubsystemIndex, DiscreteVariableIndex) const
	OK if dv.stage==Model or stage >= Model.
Real	getDiscreteVarLastUpdateTime (SubsystemIndex, DiscreteVariableIndex) const
CacheEntryIndex	getDiscreteVarUpdateEntry (SubsystemIndex, DiscreteVariableIndex) const
const AbstractValue &	getDiscreteVarPrevValue (SubsystemIndex, DiscreteVariableIndex) const
AbstractValue &	updDiscreteVariable (SubsystemIndex, DiscreteVariableIndex)
	OK if dv.stage==Model or stage >= Model; set stage to dv.stage-1.
void	setDiscreteVariable (SubsystemIndex, DiscreteVariableIndex, const AbstractValue &)
	Alternate interface to updDiscreteVariable.
const AbstractValue &	getCacheEntry (SubsystemIndex, CacheEntryIndex) const
	Stage >= ce.stage.
AbstractValue &	updCacheEntry (SubsystemIndex, CacheEntryIndex) const
	Stage >= ce.stage-1; does not change stage.
bool	isCacheValueCurrent (SubsystemIndex, CacheEntryIndex) const
void	markCacheValueRealized (SubsystemIndex, CacheEntryIndex) 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	createRestrictedState (State &restrictedState, EnumerationSet< Stage > restrictedStages, std::set< SubsystemIndex > restrictedSubsystems)
	Transform a State into one which shares all the same data as this one, such that modifying either one will modify both of them.
const EnumerationSet< Stage > &	getRestrictedStages () const
	Get the set of stages which cannot be modified in this State.
const std::set< SubsystemIndex > &	getRestrictedSubsystems () const
	Get the set of subsystems which cannot be modified in this State.
String	toString () const
String	cacheToString () const
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 subsytems 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, which 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 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

State ( )

Create an empty State.

~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

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

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

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

References State::allocateCacheEntry().

Referenced by State::allocateCacheEntry().

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

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.

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

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

DiscreteVariableIndex allocateDiscreteVariable	(	SubsystemIndex	,
		Stage	invalidates,
		AbstractValue *
	)

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.

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

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.

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

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.

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.

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.

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.

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.

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.

UIndex allocateU	(	SubsystemIndex	,
		const Vector &	uInit
	)

UDotErrIndex allocateUDotErr	(	SubsystemIndex	,
		int	nudoterr
	)			const

UErrIndex allocateUErr	(	SubsystemIndex	,
		int	nuerr
	)			const

std::pair<DiscreteVariableIndex, CacheEntryIndex> allocateUpdatingDiscreteVariable	(	SubsystemIndex	,
		Stage	invalidates,
		AbstractValue *	,
		Stage	earliestUpdate
	)

This method allocates a DiscreteVariable and a CacheEntry of the same value type.

This can be done if the State hasn't yet been advanced to Model stage. 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.

Whenever the value of the discrete variable is accessed, the value of the update cache entry is returned instead if it is valid. 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. However, any explicit change to the discrete variable will invalidate the invalidates stage just as for a non-updating discrete variable. Note that this 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.

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 updateDiscreteVariables(). That method looks at all the updating 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. No stage is invalidated by the swap; see above for why that isn't necessary.

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

See also:: allocateDiscreteVariable(); allocateCacheEntry()

ZIndex allocateZ	(	SubsystemIndex	,
		const Vector &	zInit
	)

String cacheToString ( ) const

void clear ( )

Restore State to default-constructed condition.

void createRestrictedState	(	State &	restrictedState,
		EnumerationSet< Stage >	restrictedStages,
		std::set< SubsystemIndex >	restrictedSubsystems
	)

Transform a State into one which shares all the same data as this one, such that modifying either one will modify both of them.

The new State restricts which stages and subsystems may be modified. Any attempt to modify restricted data through that object will produce an exception.

This method can only add restrictions, not remove them. If this State was itself created by createRestrictedState(), the new state will inherit all of the restrictions from this one, in addition to any that are specified in the arguments.

const AbstractValue& getCacheEntry	(	SubsystemIndex	,
		CacheEntryIndex
	)			const

Stage >= ce.stage.

const AbstractValue& getDiscreteVariable	(	SubsystemIndex	,
		DiscreteVariableIndex
	)			const

OK if dv.stage==Model or stage >= Model.

Real getDiscreteVarLastUpdateTime	(	SubsystemIndex	,
		DiscreteVariableIndex
	)			const

const AbstractValue& getDiscreteVarPrevValue	(	SubsystemIndex	,
		DiscreteVariableIndex
	)			const

CacheEntryIndex getDiscreteVarUpdateEntry	(	SubsystemIndex	,
		DiscreteVariableIndex
	)			const

const Vector& getEventTriggers ( ) const

const Vector& getEventTriggersByStage	(	SubsystemIndex	,
		Stage
	)			const

const Vector& getEventTriggersByStage ( Stage ) const

SystemEventTriggerByStageIndex getEventTriggerStartByStage	(	SubsystemIndex	,
		Stage
	)			const

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.

Callable at Instance stage.

const Stage& 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.

const Vector& getMultipliers ( ) const

const Vector& getMultipliers ( SubsystemIndex ) const

SystemMultiplierIndex getMultipliersStart ( SubsystemIndex ) const

int getNEventTriggers ( ) const

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

Callable at Instance stage.

int getNEventTriggersByStage	(	SubsystemIndex	,
		Stage
	)			const

int getNEventTriggersByStage ( Stage ) const

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

Callable at Instance stage.

int getNMultipliers ( SubsystemIndex ) const

int 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 getNQ ( SubsystemIndex ) const

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

int getNQErr ( SubsystemIndex ) const

int getNQErr ( ) const

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

Callable at Instance stage.

int getNSubsystems ( ) const

int getNU ( SubsystemIndex ) const

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

int getNUDotErr ( SubsystemIndex ) const

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

Callable at Instance stage.

int getNUErr ( SubsystemIndex ) const

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

Callable at Instance stage.

int 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 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 getNZ ( SubsystemIndex ) const

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

const Vector& getQ ( ) const

These are just views into Y.

const Vector& getQ ( SubsystemIndex ) const

Per-subsystem access to the global shared variables.

const Vector& getQDot ( ) const

These are just views into YDot.

const Vector& getQDot ( SubsystemIndex ) const

Per-subsystem access to the shared cache entries.

const Vector& getQDotDot ( ) const

This has its own space, not a view.

const Vector& getQDotDot ( SubsystemIndex ) const

const Vector& getQErr ( ) const

These are just views into YErr.

const Vector& getQErr ( SubsystemIndex ) const

SystemQErrIndex getQErrStart ( SubsystemIndex ) const

SystemYErrIndex getQErrStart ( ) const

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

SystemQIndex getQStart ( SubsystemIndex ) const

SystemYIndex getQStart ( ) const

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

const EnumerationSet<Stage>& getRestrictedStages ( ) const

Get the set of stages which cannot be modified in this State.

Attempting to modify any of these stages will produce an exception.

const std::set<SubsystemIndex>& getRestrictedSubsystems ( ) const

Get the set of subsystems which cannot be modified in this State.

Attempting to modify any of these subsystems will produce an exception.

const String& getSubsystemName ( SubsystemIndex ) const

const Stage& getSubsystemStage ( SubsystemIndex ) const

const String& getSubsystemVersion ( SubsystemIndex ) const

const Stage& getSystemStage ( ) const

This returns the *global* stage for this State.

const Real& getTime ( ) const

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

Referenced by TimeStepper::getTime(), and Implementation::realizeMeasureTimeImpl().

const Vector& getU ( ) const

const Vector& getU ( SubsystemIndex ) const

const Vector& getUDot ( ) const

const Vector& getUDot ( SubsystemIndex ) const

const Vector& getUDotErr ( ) const

These have their own space, the are not views.

const Vector& getUDotErr ( SubsystemIndex ) const

SystemUDotErrIndex getUDotErrStart ( SubsystemIndex ) const

const Vector& getUErr ( ) const

const Vector& getUErr ( SubsystemIndex ) const

SystemUErrIndex getUErrStart ( SubsystemIndex ) const

SystemYErrIndex getUErrStart ( ) const

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

SystemUIndex getUStart ( SubsystemIndex ) const

SystemYIndex getUStart ( ) const

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

const Vector& getY ( ) const

const Vector& getYDot ( ) const

const Vector& getYErr ( ) const

Return the current constraint errors for all constraints.

const Vector& getZ ( ) const

const Vector& getZ ( SubsystemIndex ) const

const Vector& getZDot ( ) const

const Vector& getZDot ( SubsystemIndex ) const

SystemZIndex getZStart ( SubsystemIndex ) const

SystemYIndex getZStart ( ) const

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

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.

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

bool isCacheValueCurrent	(	SubsystemIndex	,
		CacheEntryIndex
	)			const

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 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 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 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 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 mapSubsystemEventTriggerToStage	(	EventTriggerIndex	,
		Stage &	,
		EventTriggerByStageIndex &
	)			const

Given a Subsystem-wide event index, map that to a particular Stage and an index within that 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 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 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 markCacheValueRealized	(	SubsystemIndex	,
		CacheEntryIndex
	)			const

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.

void resetLowestStageModified ( ) const

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

void setDiscreteVariable	(	SubsystemIndex	,
		DiscreteVariableIndex	,
		const AbstractValue &
	)

Alternate interface to updDiscreteVariable.

void setNSubsystems ( 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 setQ ( const Vector & q )

Alternate interface.

void setTime ( Real t )

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

void setU ( const Vector & u )

void setY ( const Vector & y )

void setZ ( const Vector & z )

String toString ( ) const

AbstractValue& updCacheEntry	(	SubsystemIndex	,
		CacheEntryIndex
	)			const

Stage >= ce.stage-1; does not change stage.

AbstractValue& updDiscreteVariable	(	SubsystemIndex	,
		DiscreteVariableIndex
	)

OK if dv.stage==Model or stage >= Model; set stage to dv.stage-1.

Vector& updEventTriggers ( ) const

Vector& updEventTriggersByStage	(	SubsystemIndex	,
		Stage
	)			const

Vector& updEventTriggersByStage ( Stage ) const

Vector& updMultipliers ( ) const

Vector& updMultipliers ( SubsystemIndex ) const

Vector& updQ ( )

These are just views into Y.

Vector& updQ ( SubsystemIndex )

Vector& updQDot ( ) const

Vector& updQDot ( SubsystemIndex ) const

Vector& 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.

Vector& updQDotDot ( SubsystemIndex ) const

Vector& updQErr ( ) const

Vector& updQErr ( SubsystemIndex ) 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& updU ( )

Vector& updU ( SubsystemIndex )

Vector& updUDot ( ) const

Vector& updUDot ( SubsystemIndex ) const

Vector& updUDotErr ( ) const

Vector& updUDotErr ( SubsystemIndex ) const

Vector& updUErr ( ) const

Vector& updUErr ( SubsystemIndex ) const

Vector& updY ( )

Vector& updYDot ( ) const

These are mutable.

Vector& updYErr ( ) const

These are mutable.

Vector& updZ ( )

Vector& updZ ( SubsystemIndex )

Vector& updZDot ( ) const

Vector& updZDot ( SubsystemIndex ) const

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

State.h

State Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation