API
4.2
For C++ developers
|
This class holds a sequence of SimTK::States. More...
Public Member Functions | |
StatesTrajectory () | |
Create an empty trajectory of states. More... | |
size_t | getSize () const |
The number of SimTK::States in the trajectory. More... | |
TimeSeriesTable | exportToTable (const Model &model, const std::vector< std::string > &stateVars={}) const |
Export the continuous state variables to a data table, perhaps to write to a file and postprocess in MATLAB/Python/Excel. More... | |
Accessing individual SimTK::States | |
const SimTK::State & | operator[] (size_t index) const |
Get a const reference to the state at a given index in the trajectory. More... | |
const SimTK::State & | get (size_t index) const |
Get a const reference to the state at a given index in the trajectory. More... | |
const SimTK::State & | front () const |
Get a const reference to the first state in the trajectory. More... | |
const SimTK::State & | back () const |
Get a const reference to the last state in the trajectory. More... | |
Iterating through the trajectory | |
const_iterator | begin () const |
Iterator pointing to first SimTK::State; does not allow modifying the states. More... | |
const_iterator | end () const |
Iterator pointing past the end of the trajectory. More... | |
Modify the contents of the trajectory | |
void | clear () |
Clear all the states in the trajectory. More... | |
void | append (const SimTK::State &state) |
Append a SimTK::State to this trajectory. More... | |
Checks for integrity | |
bool | hasIntegrity () const |
Checks isNondecreasingInTime() and isConsistent(). More... | |
bool | isNondecreasingInTime () const |
Returns true if times are non-decreasing; false otherwise. More... | |
bool | isConsistent () const |
Checks if the states have the same number of state variables, constraints, etc. More... | |
bool | isCompatibleWith (const Model &model) const |
Weak check for if the trajectory can be used with the given model. More... | |
Public Types | |
typedef std::vector< SimTK::State >::const_iterator | const_iterator |
Iterator type that does not allow modifying the trajectory. More... | |
typedef SimTK::IteratorRange< const_iterator > | IteratorRange |
A helper type to allow using range for loops over a subset of the trajectory. More... | |
Static Public Member Functions | |
Create partial trajectory from a states table | |
static StatesTrajectory | createFromStatesStorage (const Model &model, const Storage &sto, bool allowMissingColumns=false, bool allowExtraColumns=false, bool assemble=false) |
This function is identical to createFromStatesTable() except that this function accepts a Storage instead of a TimeSeriesTable. More... | |
static StatesTrajectory | createFromStatesTable (const Model &model, const TimeSeriesTable &table, bool allowMissingColumns=false, bool allowExtraColumns=false, bool assemble=false) |
Create a partial trajectory of States from a states table. More... | |
static StatesTrajectory | createFromStatesStorage (const Model &model, const std::string &filepath) |
Convenience form of createFromStatesStorage() that takes the path to a Storage file instead of a Storage object. More... | |
Nested Classes | |
class | DataIsInDegrees |
Thrown by createFromStatesStorage(). More... | |
class | ExtraColumns |
Thrown when trying to create a StatesTrajectory from states data, and the data contains columns that do not correspond to continuous state variables. More... | |
class | IncompatibleModel |
Thrown when trying to use a StatesTrajectory with an incompatible model. More... | |
class | InconsistentState |
Thrown when trying to append a state that is not consistent with the rest of the trajectory. More... | |
class | MissingColumns |
Thrown when trying to create a StatesTrajectory from states data, and the data does not contain a column for every continuous state variable. More... | |
This class holds a sequence of SimTK::States.
You can obtain a StatesTrajectory during a simulation via the StatesTrajectoryReporter. You can also create a StatesTrajectory from a states storage (.sto) file (see createFromStatesStorage()). Users can modify a trajectory by appending states to it, but users cannot modify the individual states that are already in a trajectory.
This class was introduced in OpenSim version 4.0, and enables scripting (Python/MATLAB) and C++ users to postprocess their results with greater ease and flexibility than with an Analysis.
This class is designed to ensure the following:
A StatesTrajectory is not very useful on its own, since neither the trajectory nor the contained states know how the Components name the state variables they create. You probably want to use the trajectory with an OpenSim::Model, through which the state variables have a meaning (e.g., model.getStateVariableValue(states[0], "soleus_r/activation")
).
SimTK::States have a tight association with a specific OpenSim::Model (actually, with the SimTK::System within an OpenSim::Model). However, the StatesTrajectory does not know anything about the model to which it corresponds. So, for example, you could use a single StatesTrajectory with a generic gait2392 model as well as with a scaled (subject-specific) gait2392 model. This flexibility may be beneficial in some scenarios, but also allows one to accidentally use the wrong model with a given states trajectory, potentially leading to silent errors that could compromise a scientific study.
To increase your confidence that a StatesTrajectory matches a given Model, you can perform some weak checks with isCompatibleWith().
Here are a few basic things you can do with a StatesTrajectory, assuming you already have one:
Without a model, you can access the state variable values, but you won't know the identity of such state variables.
To do most things with the StatesTrajectory, you'll need a model as well as its underlying SimTK::System. It is therefore required that you call Model::initSystem()
before you try to use any states with the model:
Depending on the quantity you want to obtain, you may also need to realize the state to a certain stage:
You can iterate through a trajectory to access the value of a state variable at each time in the trajectory.
typedef std::vector<SimTK::State>::const_iterator OpenSim::StatesTrajectory::const_iterator |
Iterator type that does not allow modifying the trajectory.
Most users do not need to understand what this is.
typedef SimTK::IteratorRange<const_iterator> OpenSim::StatesTrajectory::IteratorRange |
A helper type to allow using range for loops over a subset of the trajectory.
|
inline |
Create an empty trajectory of states.
void OpenSim::StatesTrajectory::append | ( | const SimTK::State & | state | ) |
Append a SimTK::State to this trajectory.
This function ensures that the time in the new SimTK::State is greater than or equal to the time in the last SimTK::State in the trajectory.
The state that ends up in the trajectory is a deep copy of the one passed in.
|
inline |
Get a const reference to the last state in the trajectory.
|
inline |
Iterator pointing to first SimTK::State; does not allow modifying the states.
Allows using this class in a range for loop.
void OpenSim::StatesTrajectory::clear | ( | ) |
Clear all the states in the trajectory.
|
static |
This function is identical to createFromStatesTable() except that this function accepts a Storage instead of a TimeSeriesTable.
|
static |
Convenience form of createFromStatesStorage() that takes the path to a Storage file instead of a Storage object.
This convenience form uses the default values for allowMissingColumns
and allowExtraColumns
.
|
static |
Create a partial trajectory of States from a states table.
The resulting StatesTrajectory will restore continuous state variable values, but not discrete state variable values, modeling option values, etc. Also, keep in mind that states files usually do not contain the state values to full precision, and thus cannot exactly reproduce results from the initial state trajectory. Lastly, this function optionally modifies each state to obey any constraints in the model (by calling Model::assemble()).
The states in the resulting trajectory will be realized to SimTK::Stage::Instance. You should not use the resulting trajectory with an instance of the model other than the one you passed to this function (the state contains Instance-stage cache variables that are pointers to objects in the model; e.g., force elements).
ankle_r/ankle_angle_r/speed
used to be ankle_angle_r_u
, soleus_r/activation
used to be soleus_r.activation
, etc. This function can handle column labels that use the pre-v4.0 naming convention.model | The Model to which the states belong. A Model is necessary because the data file lists the state variables by name. |
table | The table containing state values. |
allowMissingColumns | If false, throws exception if there are continuous state variables in the Model for which there is no column in the table. If true, no exception is thrown but such state variables are set to NaN. |
allowExtraColumns | If false, throws exception if there are columns in the table that do not correspond to continuous state variables in the Model. If true, such columns of the table are ignored. |
assemble | Modify state variable values to satisfy kinematic constraints (by calling Model::assemble()). Use this option if the provided states are incomplete (for example, the values for dependent coordinates are unspecified). Caution: enforcing constraints can drastically alter the provided states if they do not already obey the constraints. Do not use this option with results from a forward simulation: the states trajectory from a forward simulation may not meet the model's assembly accuracy, and therefore assembling could alter the trajectory and cause inconsistency between coordinate values and speeds. |
Here is how you might use this function in python:
MissingColumns | See the description of the allowMissingColumns argument. |
ExtraColumns | See the description of the allowExtraColumns argument. |
NonUniqueLabels | Thrown if multiple columns in the table have the same name. |
DataIsInDegrees | Thrown if the table is in degrees (inDegrees=yes); angular quantities must use radians to properly create the trajectory. |
Referenced by OpenSim::analyze().
|
inline |
Iterator pointing past the end of the trajectory.
Allows using this class in a range for loop.
TimeSeriesTable OpenSim::StatesTrajectory::exportToTable | ( | const Model & | model, |
const std::vector< std::string > & | stateVars = {} |
||
) | const |
Export the continuous state variables to a data table, perhaps to write to a file and postprocess in MATLAB/Python/Excel.
The names of the columns in the table will be the absolute names of the continuous state variables (e.g., knee/flexion/angle
).
You must provide a model that is compatible with this trajectory, since only the model knows the names of the state variables.
By default, all continuous state variables are written to the table (one per column). If you only want some of them to be written to the table, use the stateVars
argument to specify their absolute names (e.g., knee/flexion/angle
).
IncompatibleModel | Thrown if the Model fails the check isCompatibleWith(). |
See DataAdapter for details on writing to files.
|
inline |
Get a const reference to the first state in the trajectory.
|
inline |
Get a const reference to the state at a given index in the trajectory.
IndexOutOfRange | If the index is greater than the size of the trajectory. |
size_t OpenSim::StatesTrajectory::getSize | ( | ) | const |
The number of SimTK::States in the trajectory.
bool OpenSim::StatesTrajectory::hasIntegrity | ( | ) | const |
Checks isNondecreasingInTime() and isConsistent().
The design of this class is such that this method should always return true. This check may be more useful in Python or MATLAB, in which it's possible to edit the trajectory such that this method could return false.
bool OpenSim::StatesTrajectory::isCompatibleWith | ( | const Model & | model | ) | const |
Weak check for if the trajectory can be used with the given model.
Returns true if the trajectory isConsistent() and if the number of speeds in the model matches the number of U's in state.
Returns false otherwise. This method cannot guarantee that the trajectory will work with the given model, and makes no attempt to determine if the trajectory was generated with the given model.
bool OpenSim::StatesTrajectory::isConsistent | ( | ) | const |
Checks if the states have the same number of state variables, constraints, etc.
Returns true if the following quantities are the same for all states in the trajectory:
Returns false otherwise.
bool OpenSim::StatesTrajectory::isNondecreasingInTime | ( | ) | const |
Returns true if times are non-decreasing; false otherwise.
|
inline |
Get a const reference to the state at a given index in the trajectory.
Here's an example of getting a state variable value from the first state in the trajectory:
This function does not check if the index is larger than the size of the trajectory; see get() if you want this check.