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

(CAUTION: still under development) This is a Measure whose value at time t is the value that its source operand had at time t-delay for a specified delay. More...

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

Classes

class  Implementation
 

Public Member Functions

 Delay (Subsystem &sub, const Measure_< T > &source, Real delay)
 Create a Measure whose output is the same as the given source measure but delayed by a time delay. More...
 
DelaysetUseLinearInterpolationOnly (bool linearOnly)
 (Advanced) Restrict the Delay measure to use only linear interpolation to estimate delayed values. More...
 
DelaysetCanUseCurrentValue (bool canUseCurrentValue)
 (Advanced) Allow the Delay measure to refer to the current value when estimating the delayed value. More...
 
DelaysetSourceMeasure (const Measure_< T > &source)
 Replace the source measure. More...
 
DelaysetDelay (Real delay)
 Change the delay time. More...
 
bool getUseLinearInterpolationOnly () const
 Return the value of the "use linear interpolation only" flag. More...
 
bool getCanUseCurrentValue () const
 Return the value of the "can use current value" flag. More...
 
const Measure_< T > & getSourceMeasure () const
 Obtain a reference to the source Measure. More...
 
Real getDelay () const
 Get the amount of time by which this Measure is delaying its source Measure. More...
 
- 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 >::Delay

(CAUTION: still under development) This is a Measure whose value at time t is the value that its source operand had at time t-delay for a specified delay.

For times prior to the start of a simulation this Measure behaves as though the source value had been constant at its initial value.

When the source Measure can provide a time derivative dvalue we use saved (t,value,dvalue) triples surrounding the required time to construct a cubic Hermite interpolant giving a third-order accurate estimate of the delayed value. Otherwise we use more data points to construct the cubic interpolant but the accuracy cannot be guaranteed. If there aren't enough data points, then linear interpolation is used instead. There is an option to force use of linear interpolation if you prefer.

In the case where the delayed time is within the current step, we would need the current source value in order to interpolate. We assume that is not available (commonly the current value depends on the delayed value) so have to extrapolate beyond the last buffered value in that case. Extrapolation is considerably less accurate than interpolation, so when step sizes are large compared to delay times the accuracy of the delayed value is reduced. In cases where the source does not depend on its delayed value, you can request that the current value be used if necessary, ensuring consistent accuracy. Alternatively, you can set the maximum integrator step size to be just less than the minimum delay time, guaranteeing that there will always be an entry already in the buffer that is later than any requested delayed time. That could have a substantial performance penalty if steps much larger than the delay would otherwise have been taken.

Implementation

This Measure maintains a variable-sized buffer holding values that the source measure and its time derivative (if available) had at each time step starting just prior to t-delay until just before the current time t. New values are added to the end of the buffer as integrator steps are completed, and old values that are no longer needed are removed from the beginning. When a value is requested at current time t, the Measure interpolates using values from just prior to t-delay and just afterwards to approximate the value at t-delay.

See also
Measure_::Integrate, Measure_::Differentiate

Constructor & Destructor Documentation

template<class T>
SimTK::Measure_< T >::Delay::Delay ( Subsystem sub,
const Measure_< T > &  source,
Real  delay 
)
inline

Create a Measure whose output is the same as the given source measure but delayed by a time delay.

Member Function Documentation

template<class T>
Delay& SimTK::Measure_< T >::Delay::setUseLinearInterpolationOnly ( bool  linearOnly)
inline

(Advanced) Restrict the Delay measure to use only linear interpolation to estimate delayed values.

By default it uses cubic interpolation whenever possible. Cubic interpolation will almost always be better but can be unstable in some circumstances. Despite its name this flag also applies to extrapolation if we have to do any. This is a topological change.

template<class T>
Delay& SimTK::Measure_< T >::Delay::setCanUseCurrentValue ( bool  canUseCurrentValue)
inline

(Advanced) Allow the Delay measure to refer to the current value when estimating the delayed value.

Normally we expect that the current value might depend on the delayed value so is not available at the time we ask for the delayed value. That means that if the delayed time is between the current time and the last saved time (that is, it is a time during the current integration step), the measure will have to extrapolate from the last-saved values to avoid requiring the current value to be available. With this approach the "depends on" time for a Delay measure is just Time stage since it does not depend on any current calculations. However, extrapolation is much less accurate than interpolation so if you don't mind the "depends on" stage for a Delay measure being the same stage as for its source measure, then you can get nicer interpolated values. This is a topological change.

template<class T>
Delay& SimTK::Measure_< T >::Delay::setSourceMeasure ( const Measure_< T > &  source)
inline

Replace the source measure.

This is a topological change.

template<class T>
Delay& SimTK::Measure_< T >::Delay::setDelay ( Real  delay)
inline

Change the delay time.

This is a topological change.

template<class T>
bool SimTK::Measure_< T >::Delay::getUseLinearInterpolationOnly ( ) const
inline

Return the value of the "use linear interpolation only" flag.

template<class T>
bool SimTK::Measure_< T >::Delay::getCanUseCurrentValue ( ) const
inline

Return the value of the "can use current value" flag.

template<class T>
const Measure_<T>& SimTK::Measure_< T >::Delay::getSourceMeasure ( ) const
inline

Obtain a reference to the source Measure.

template<class T>
Real SimTK::Measure_< T >::Delay::getDelay ( ) const
inline

Get the amount of time by which this Measure is delaying its source Measure.


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