Drake
WitnessFunction< T > Class Template Referenceabstract

Abstract class that describes a function that is able to help determine the time and state at which a simulation should be halted, which may be done for any number of purposes, including publishing or state reinitialization (i.e., event handling). More...

#include <drake/systems/framework/witness_function.h>

Inheritance diagram for WitnessFunction< T >:
[legend]
Collaboration diagram for WitnessFunction< T >:
[legend]

Public Member Functions

virtual ~WitnessFunction ()
 
 WitnessFunction (const System< T > &system, const WitnessFunctionDirection &dtype)
 Constructs the witness function with the given direction type. More...
 
const std::string & get_name () const
 Gets the name of this witness function (used primarily for logging and debugging). More...
 
void set_name (const std::string &name)
 Sets the name of this witness function. More...
 
void AddEvent (CompositeEventCollection< T > *events) const
 Adds the appropriate event that will be dispatched when this witness function triggers. More...
 
WitnessFunctionDirection get_dir_type () const
 Gets the direction(s) under which this witness function triggers. More...
 
Evaluate (const Context< T > &context) const
 Evaluates the witness function at the given context. More...
 
const System< T > & get_system () const
 Gets a reference to the System used by this witness function. More...
 
decltype(T()< T()) should_trigger (const T &w0, const T &wf) const
 Checks whether the witness function should trigger using given values at w0 and wf. More...
 
Does not allow copy, move, or assignment
 WitnessFunction (const WitnessFunction &)=delete
 
WitnessFunctionoperator= (const WitnessFunction &)=delete
 
 WitnessFunction (WitnessFunction &&)=delete
 
WitnessFunctionoperator= (WitnessFunction &&)=delete
 

Protected Member Functions

virtual void DoAddEvent (CompositeEventCollection< T > *events) const =0
 Derived classes will override this function to add the appropriate event that will be dispatched when this witness function triggers. More...
 
virtual T DoEvaluate (const Context< T > &context) const =0
 Derived classes will implement this function to evaluate the witness function at the given context. More...
 

Protected Attributes

std::string name_
 

Detailed Description

template<class T>
class drake::systems::WitnessFunction< T >

Abstract class that describes a function that is able to help determine the time and state at which a simulation should be halted, which may be done for any number of purposes, including publishing or state reinitialization (i.e., event handling).

For the ensuing discussion, consider two times (t₀ and t₁ > t₀) and states corresponding to those times (x(t₀) and x(t₁)). A witness function, w(t, x), "triggers" only when it crosses zero at a time t* where t₀ < t* ≤ t₁. Note the half-open interval. For an example of a witness function, consider the "signed distance" (i.e., Euclidean distance when bodies are disjoint and minimum translational distance when bodies intersect) between two rigid bodies; this witness function can be used to determine both the time of impact for rigid bodies and their states at that time of impact.

Precision in the definition of the witness function is necessary, because we want the witness function to trigger only once if, for example, w(t₀, x(t₀)) ≠ 0, w(t₁, x(t₁)) = 0, and w(t₂, x(t₂)) ≠ 0, for some t₂ > t₁. In other words, if the witness function is evaluated over the intervals [t₀, t₁] and [t₁, t₂], meaning that the zero occurs precisely at an interval endpoint, the witness function should trigger once. Similarly, the witness function should trigger exactly once if w(t₀, x(t₀)) ≠ 0, w(t*, x(t*)) = 0, and w(t₁, x(t₁)) = 0. We can define the trigger condition formally over interval [t₀, t₁] using the function:

T(w, t₀, x(t₀), t₁) =   1   if w(t₀, x(t₀)) ≠ 0 and
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) ≤ 0
                        0   if w(t₀, x(t₀)) = 0 or
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) > 0

where x(tₑ) for some tₑ ≥ t₀ is the solution to the ODE or DAE initial value problem ẋ = f(t, x) for initial condition x(t₀) = x₀ at time tₑ. We wish for the witness function to trigger if the trigger function evaluates to one. The trigger function can be further modified, if desired, to incorporate the constraint that the witness function should trigger only when crossing from positive values to negative values, or vice versa.

A good witness function should not cross zero repeatedly over a small interval of time (relative to the maximum designated integration step size) or over small changes in state; when a witness function has been "bracketed" over an interval of time (i.e., it changes sign), that witness function will ideally cross zero only once in that interval.

A witness function trigger time is isolated only to a small interval of time (as described in Simulator). The disadvantage of this scheme is that it always requires the length of the interval to be reduced to the requisite length and that each function evaluation (which requires numerical integration) is extraordinarily expensive. If, for example, the (slow) bisection algorithm were used to isolate the time interval, the number of integrations necessary to cut the interval from a length of ℓ to a length of ε will be log₂(ℓ / ε). Bisection is just one of several possible algorithms for isolating the time interval, though it's a reliable choice and always converges linearly.

Constructor & Destructor Documentation

WitnessFunction ( const WitnessFunction< T > &  )
delete
WitnessFunction ( WitnessFunction< T > &&  )
delete
virtual ~WitnessFunction ( )
inlinevirtual
WitnessFunction ( const System< T > &  system,
const WitnessFunctionDirection dtype 
)
inline

Constructs the witness function with the given direction type.

Member Function Documentation

void AddEvent ( CompositeEventCollection< T > *  events) const
inline

Adds the appropriate event that will be dispatched when this witness function triggers.

virtual void DoAddEvent ( CompositeEventCollection< T > *  events) const
protectedpure virtual

Derived classes will override this function to add the appropriate event that will be dispatched when this witness function triggers.

Example events are publish, perform a discrete variable update, and performing an unrestricted update. events is guaranteed to be non-null on entry.

Implemented in ClockWitness< T >.

virtual T DoEvaluate ( const Context< T > &  context) const
protectedpure virtual

Derived classes will implement this function to evaluate the witness function at the given context.

Parameters
contextan already-validated Context

Implemented in ClockWitness< T >, and LogisticWitness< T >.

T Evaluate ( const Context< T > &  context) const

Evaluates the witness function at the given context.

WitnessFunctionDirection get_dir_type ( ) const
inline

Gets the direction(s) under which this witness function triggers.

const std::string& get_name ( ) const
inline

Gets the name of this witness function (used primarily for logging and debugging).

const System<T>& get_system ( ) const
inline

Gets a reference to the System used by this witness function.

WitnessFunction& operator= ( WitnessFunction< T > &&  )
delete
WitnessFunction& operator= ( const WitnessFunction< T > &  )
delete
void set_name ( const std::string &  name)
inline

Sets the name of this witness function.

decltype(T() < T()) should_trigger ( const T &  w0,
const T &  wf 
) const
inline

Checks whether the witness function should trigger using given values at w0 and wf.

Note that this function is not specific to a particular witness function.

Member Data Documentation

std::string name_
protected

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