Simbody  3.5
SimTK::Measure_< T >::Result Class Reference

This Measure holds the result of some externally-determined computation, and helps to coordinate the validity of that computation with respect to the state variables. More...

+ Inheritance diagram for SimTK::Measure_< T >::Result:

Classes

class  Implementation
 

Public Member Functions

 SimTK_MEASURE_HANDLE_PREAMBLE (Result, Measure_< T >)
 
 Result (Subsystem &sub, Stage dependsOn, Stage invalidated)
 Create a new Result measure and add it to the indicated subsystem. More...
 
Stage getDependsOnStage () const
 Get the dependsOn stage for this measure's value. More...
 
Stage getInvalidatedStage () const
 Get the invalidated stage for this measure's value. More...
 
ResultsetDependsOnStage (Stage dependsOn)
 Change the dependsOn stage for this measure's value, which must be strictly less than the current setting for the invalidated stage. More...
 
ResultsetInvalidatedStage (Stage invalidated)
 Change the invalidated stage for this measure's value, which must be strictly greater than the current setting for the dependsOn stage. More...
 
ResultsetIsPresumedValidAtDependsOnStage (bool presume)
 Normally a Result measure's value is not considered valid unless we are notified explicitly that it is, via a call to markAsValid() or setValue(); this method allows the value to be assumed valid after the dependsOn stage has been realized. More...
 
bool getIsPresumedValidAtDependsOnStage () const
 Return the value of the "presumed valid at dependsOn stage" flag. More...
 
T & updValue (const State &state) const
 Obtain write access to the Measure's value in order to modify it. More...
 
void markAsValid (const State &state) const
 Mark the current value as valid. More...
 
bool isValid (const State &state) const
 Check whether the value contained in this Measure is currently valid. More...
 
void markAsNotValid (const State &state) const
 Manually mark the contained value as invalid. More...
 
void setValue (const State &state, const T &value) const
 Set a new value and mark it as valid. More...
 
 SimTK_MEASURE_HANDLE_POSTSCRIPT (Result, Measure_< T >)
 
- Public Member Functions inherited from SimTK::Measure_< T >
 SimTK_MEASURE_HANDLE_PREAMBLE_ABSTRACT (Measure_, AbstractMeasure)
 This class is still abstract so we don't want it to allocate an Implementation object in its default constructor. More...
 
const T & getValue (const State &s, int derivOrder=0) const
 Retrieve the Value of this Measure or one of its time derivatives, assuming the supplied State has been realized to at least the required stage for the selected value or derivative, as reported by getDependsOnStage(). More...
 
Measure_setDefaultValue (const T &defaultValue)
 Change the default value associated with this Measure. More...
 
const T & getDefaultValue () const
 Obtain a reference to the default value associated with this Measure. More...
 
 SimTK_MEASURE_HANDLE_POSTSCRIPT (Measure_, AbstractMeasure)
 
- Public Member Functions inherited from SimTK::AbstractMeasure
 AbstractMeasure (Implementation *g=0)
 Provide an Implementation for this AbstractMeasure and bump its reference count. More...
 
 AbstractMeasure (Subsystem &, Implementation *g, const SetHandle &)
 Construct this handle with a given Implementation object (whose reference count will be bumped) and then let the given Subsystem adopt this Measure (which will again bump the Implementation's reference count, leaving us with two new handles). More...
 
 AbstractMeasure (const AbstractMeasure &)
 Shallow copy constructor copies the pointer from the source Implementation object and bumps its reference count. More...
 
AbstractMeasureoperator= (const AbstractMeasure &source)
 Shallow assignment operator results in this handle referencing the same Implementation object as does the source. More...
 
 ~AbstractMeasure ()
 Destructor decrements the Implementation's reference count and deletes the object if the count goes to zero. More...
 
AbstractMeasureshallowAssign (const AbstractMeasure &)
 Shallow assignment operator destructs the current Implementation object (meaning its reference count is decremented and the object actually deleted only if the count goes to zero), then copies the Implementation pointer from the source and bumps its reference count. More...
 
AbstractMeasuredeepAssign (const AbstractMeasure &source)
 Deep assignment clones the Implementation object pointed to by the source handle, so that this handle ends up pointing to a new Measure object similar to the original but not yet contained in any Subsystem. More...
 
int getNumTimeDerivatives () const
 Every Measure can produce a value, and some can provide one or more total derivatives with respect to time of that value. More...
 
Stage getDependsOnStage (int derivOrder=0) const
 At what Stage can we expect the value of this AbstractMeasure or one of its time derivatives to be available? Users of Measures will typically impose restrictions on the levels they will accept. More...
 
bool isSameMeasure (const AbstractMeasure &other) const
 There can be multiple handles on the same Measure. More...
 
bool isEmptyHandle () const
 
bool isInSubsystem () const
 Test whether this Measure object has been adopted by a Subsystem. More...
 
const SubsystemgetSubsystem () const
 Return a reference to the Subsystem that owns this Measure. More...
 
MeasureIndex getSubsystemMeasureIndex () const
 Return the MeasureIndex by which this Measure is known to the Subsystem that owns it. More...
 
const ImplementationgetImpl () const
 
ImplementationupdImpl ()
 
bool hasImpl () const
 
int getRefCount () const
 

Detailed Description

template<class T>
class SimTK::Measure_< T >::Result

This Measure holds the result of some externally-determined computation, and helps to coordinate the validity of that computation with respect to the state variables.

The value must be set manually and explicitly marked valid when it is complete. The value will be automatically invalidated after a state change at or below a specified Stage, and changing the value here will automatically invalidate a specified Stage and above.

In constrast to Measure::Variable, Measure::Result is not a state variable; it is a cache variable meaning that it works with a const State. It is expected that the result can be recalculated from the state variables when needed, or contains ephemeral information that can be discarded.

No provision for derivatives is made; there is only the one result.

Constructor & Destructor Documentation

template<class T>
SimTK::Measure_< T >::Result::Result ( Subsystem sub,
Stage  dependsOn,
Stage  invalidated 
)
inline

Create a new Result measure and add it to the indicated subsystem.

The Result measure's value depends on earlier values calculated at dependsOn stage, so whenever that stage or earlier is invalidated, so is the value here. In addition, any change made to the value here will invalidate stage invalidated and all subsequent stages. The invalidated stage must be later than the dependsOn stage, and you cannot update the value here in a state that hasn't already been realized to the dependsOn stage. Set dependsOn = Stage::Empty if your value computation doesn't depend on anything else (that will be interpreted as Stage::Topology, however, since space for the value gets allocated then). Set invalidated = Stage::Infinity if you don't want anything invalidated when this value is changed.

Member Function Documentation

template<class T>
SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_PREAMBLE ( Result  ,
Measure_< T >   
)
template<class T>
Stage SimTK::Measure_< T >::Result::getDependsOnStage ( ) const
inline

Get the dependsOn stage for this measure's value.

template<class T>
Stage SimTK::Measure_< T >::Result::getInvalidatedStage ( ) const
inline

Get the invalidated stage for this measure's value.

template<class T>
Result& SimTK::Measure_< T >::Result::setDependsOnStage ( Stage  dependsOn)
inline

Change the dependsOn stage for this measure's value, which must be strictly less than the current setting for the invalidated stage.

If you set the dependsOn stage to Stage::Empty it will be interpreted as Stage::Topology since the value must always depend on at least topology. Setting the dependsOn stage is itself a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>
Result& SimTK::Measure_< T >::Result::setInvalidatedStage ( Stage  invalidated)
inline

Change the invalidated stage for this measure's value, which must be strictly greater than the current setting for the dependsOn stage.

This is a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>
Result& SimTK::Measure_< T >::Result::setIsPresumedValidAtDependsOnStage ( bool  presume)
inline

Normally a Result measure's value is not considered valid unless we are notified explicitly that it is, via a call to markAsValid() or setValue(); this method allows the value to be assumed valid after the dependsOn stage has been realized.

The reason this exists is that in some cases it is difficult to find a place from which to call markAsValid(). That means you must set the value during realization of the dependsOn stage, but there is no way for this to be checked automatically. Thus use of this feature can lead to very difficult-to-find bugs; you should try hard to find a place to call markAsValid() before resorting to this method. This is a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>
bool SimTK::Measure_< T >::Result::getIsPresumedValidAtDependsOnStage ( ) const
inline

Return the value of the "presumed valid at dependsOn stage" flag.

See also
setIsPresumedValidAtDependsOnStage() for a discussion.
template<class T>
T& SimTK::Measure_< T >::Result::updValue ( const State state) const
inline

Obtain write access to the Measure's value in order to modify it.

Calling this method marks the result invalid; you must explicitly validate it when you're done. Also, if this Measure was created with an invalidates stage, then that stage and all later stages in the given state are marked invalid also.

template<class T>
void SimTK::Measure_< T >::Result::markAsValid ( const State state) const
inline

Mark the current value as valid.

This is done automatically if you call setValue() but must be done manually if you use updValue() to access the value. Note that you cannot mark this valid if state hasn't been realized already to at least the stage prior to this measure's dependsOn stage; that is, you must at least be working on the dependsOn stage at the time this is called.

template<class T>
bool SimTK::Measure_< T >::Result::isValid ( const State state) const
inline

Check whether the value contained in this Measure is currently valid.

If true, you can call getValue() to obtain it. If false, calling getValue() will throw an exception.

template<class T>
void SimTK::Measure_< T >::Result::markAsNotValid ( const State state) const
inline

Manually mark the contained value as invalid.

This will also invalidate any stages in state that depend on this value. This is called automatically whenever the updValue() method is invoked, and the value starts out invalid. The value becomes valid either by calling markAsValid() explicitly or calling setValue().

Warning
If you have set this Result measure to be presumed valid at dependsOn stage, this method will have no effect.
template<class T>
void SimTK::Measure_< T >::Result::setValue ( const State state,
const T &  value 
) const
inline

Set a new value and mark it as valid.

For more flexibility, use the updValue() method and markAsValid() manually when you are done with the new value.

template<class T>
SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_POSTSCRIPT ( Result  ,
Measure_< T >   
)

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