Drake
Drake C++ Documentation
SimulatorStatus Class Reference

Detailed Description

Holds the status return value from a call to Simulator::AdvanceTo() and related methods.

The argument t to AdvanceTo(t) is called the boundary time, and represents the maximum time to which the simulation trajectory will be advanced by a call to AdvanceTo(). (For methods that don't advance time, the current time is considered to be the boundary time.) A normal, successful return means that simulated time advanced successfully to the boundary time, without encountering a termination condition or error condition. AdvanceTo() may return earlier than the boundary time if one of those conditions is encountered. In that case the return object holds a reference to the subsystem that detected the condition and a human-friendly message from that subsystem that hopefully explains what happened.

#include <drake/systems/analysis/simulator_status.h>

Public Types

enum  ReturnReason { kReachedBoundaryTime, kReachedTerminationCondition, kEventHandlerFailed }
 

Public Member Functions

void SetReachedBoundaryTime ()
 Sets this status to "reached boundary time" with no message and with the final time set to the boundary time (this is the same as the post-construction default). More...
 
void SetReachedTermination (double termination_time, const SystemBase *system, std::string message)
 Sets this status to "reached termination" with the early-termination time and a message explaining why. More...
 
void SetEventHandlerFailed (double failure_time, const SystemBase *system, std::string message)
 Sets this status to "event handler failed" with the early-termination time and a message explaining why. More...
 
std::string FormatMessage () const
 Returns a human-readable message explaining the return result. More...
 
bool succeeded () const
 Returns true if we reached the boundary time with no surprises. More...
 
double boundary_time () const
 Returns the maximum time we could have reached with this call; whether we actually got there depends on the status. More...
 
double return_time () const
 Returns the time that was actually reached. More...
 
ReturnReason reason () const
 Returns the reason that a Simulator call returned. More...
 
const SystemBasesystem () const
 Optionally, returns the subsystem to which the status and contained message should be attributed. More...
 
const std::string & message () const
 For termination or error conditions, returns a human-readable message explaining what happened. More...
 
bool IsIdenticalStatus (const SimulatorStatus &other)
 Returns true if the other status contains exactly the same information as this status. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 SimulatorStatus (const SimulatorStatus &)=default
 
SimulatorStatusoperator= (const SimulatorStatus &)=default
 
 SimulatorStatus (SimulatorStatus &&)=default
 
SimulatorStatusoperator= (SimulatorStatus &&)=default
 

Member Enumeration Documentation

◆ ReturnReason

Enumerator
kReachedBoundaryTime 

This is the normal return: no termination or error condition was encountered before reaching the boundary time.

There is no message and no saved System.

kReachedTerminationCondition 

An event handler or monitor function returned with a "reached termination condition" EventStatus (has message with details).

For AdvanceTo() the return time may be earlier than the boundary time.

kEventHandlerFailed 

An event handler or monitor function returned with a "failed" EventStatus (has message with details).

For AdvanceTo() the return time may be earlier than the boundary time.

Constructor & Destructor Documentation

◆ SimulatorStatus() [1/2]

SimulatorStatus ( const SimulatorStatus )
default

◆ SimulatorStatus() [2/2]

SimulatorStatus ( SimulatorStatus &&  )
default

Member Function Documentation

◆ boundary_time()

double boundary_time ( ) const

Returns the maximum time we could have reached with this call; whether we actually got there depends on the status.

This is the time supplied in an AdvanceTo() call or the current time for methods that don't advance time, that is, Initialize() and AdvancePendingEvents().

◆ FormatMessage()

std::string FormatMessage ( ) const

Returns a human-readable message explaining the return result.

◆ IsIdenticalStatus()

bool IsIdenticalStatus ( const SimulatorStatus other)

Returns true if the other status contains exactly the same information as this status.

This is likely only useful for unit testing of SimulatorStatus.

◆ message()

const std::string& message ( ) const

For termination or error conditions, returns a human-readable message explaining what happened.

This is the message from the subsystem that detected the condition. FormatMessage() returns additional information and also includes this message.

◆ operator=() [1/2]

SimulatorStatus& operator= ( const SimulatorStatus )
default

◆ operator=() [2/2]

SimulatorStatus& operator= ( SimulatorStatus &&  )
default

◆ reason()

ReturnReason reason ( ) const

Returns the reason that a Simulator call returned.

◆ return_time()

double return_time ( ) const

Returns the time that was actually reached.

This will be boundary_time() if succeeded() returns true. Otherwise it is the time at which a termination or error condition was detected and may be earlier than boundary_time().

◆ SetEventHandlerFailed()

void SetEventHandlerFailed ( double  failure_time,
const SystemBase system,
std::string  message 
)

Sets this status to "event handler failed" with the early-termination time and a message explaining why.

◆ SetReachedBoundaryTime()

void SetReachedBoundaryTime ( )

Sets this status to "reached boundary time" with no message and with the final time set to the boundary time (this is the same as the post-construction default).

◆ SetReachedTermination()

void SetReachedTermination ( double  termination_time,
const SystemBase system,
std::string  message 
)

Sets this status to "reached termination" with the early-termination time and a message explaining why.

◆ succeeded()

bool succeeded ( ) const

Returns true if we reached the boundary time with no surprises.

◆ system()

const SystemBase* system ( ) const

Optionally, returns the subsystem to which the status and contained message should be attributed.

May be nullptr in which case the status should be attributed to the System as a whole.


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