|
Simbody
|
|
Simbody
|
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...
#include <Measure.h>
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. | |
| Stage | getDependsOnStage () const |
| Get the dependsOn stage for this measure's value. | |
| Stage | getInvalidatedStage () const |
| Get the invalidated stage for this measure's value. | |
| Result & | setDependsOnStage (Stage dependsOn) |
| Change the dependsOn stage for this measure's value, which must be strictly less than the current setting for the invalidated stage. | |
| Result & | setInvalidatedStage (Stage invalidated) |
| Change the invalidated stage for this measure's value, which must be strictly greater than the current setting for the dependsOn stage. | |
| Result & | setIsPresumedValidAtDependsOnStage (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. | |
| bool | getIsPresumedValidAtDependsOnStage () const |
| Return the value of the "presumed valid at dependsOn stage" flag. | |
| T & | updValue (const State &state) const |
| Obtain write access to the Measure's value in order to modify it. | |
| void | markAsValid (const State &state) const |
| Mark the current value as valid. | |
| bool | isValid (const State &state) const |
| Check whether the value contained in this Measure is currently valid. | |
| void | markAsNotValid (const State &state) const |
| Manually mark the contained value as invalid. | |
| void | setValue (const State &state, const T &value) const |
| Set a new value and mark it as valid. | |
| SimTK_MEASURE_HANDLE_POSTSCRIPT (Result, Measure_< T >) | |
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.
| 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.
| SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_PREAMBLE | ( | Result | , |
| Measure_< T > | |||
| ) |
| Stage SimTK::Measure_< T >::Result::getDependsOnStage | ( | ) | const [inline] |
Get the dependsOn stage for this measure's value.
| Stage SimTK::Measure_< T >::Result::getInvalidatedStage | ( | ) | const [inline] |
Get the invalidated stage for this measure's value.
| 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.
| 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.
| 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.
| bool SimTK::Measure_< T >::Result::getIsPresumedValidAtDependsOnStage | ( | ) | const [inline] |
Return the value of the "presumed valid at dependsOn stage" flag.
| 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.
| 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.
| 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.
| 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().
| 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.
| SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_POSTSCRIPT | ( | Result | , |
| Measure_< T > | |||
| ) |
1.7.3
