Moco Utilities

These are free functions and utility classes in the Moco library. More...

Classes
class	OpenSim::FileDeletionThrowerException
	Thrown by FileDeletionThrower::throwIfDeleted(). More...
class	OpenSim::FileDeletionThrower
	This class helps a user cause an exception within the code. More...

Functions
template<typename T >
TimeSeriesTable_< T >	OpenSim::analyzeMocoTrajectory (Model model, const MocoTrajectory &trajectory, const std::vector< std::string > &outputPaths)
	Calculate the requested outputs using the model in the problem and the provided StatesTrajectory and controls table. More...
OSIMMOCO_API void	OpenSim::prescribeControlsToModel (const MocoTrajectory &trajectory, Model &model, std::string functionType="GCVSpline")
	Given a MocoTrajectory and the associated OpenSim model, return the model with a prescribed controller appended that will compute the control values from the MocoTrajectory. More...
OSIMMOCO_API MocoTrajectory	OpenSim::simulateTrajectoryWithTimeStepping (const MocoTrajectory &trajectory, Model model, double integratorAccuracy=SimTK::NaN)
	Use the controls and initial state in the provided trajectory to simulate the model using an ODE time stepping integrator (OpenSim::Manager), and return the resulting states and controls. More...
OSIMMOCO_API MocoTrajectory	OpenSim::createPeriodicTrajectory (const MocoTrajectory &halfPeriodTrajectory, std::vector< std::string > addPatterns={".*pelvis_tx/value"}, std::vector< std::string > negatePatterns={ ".*pelvis_list(?!/value).*", ".*pelvis_rotation.*", ".*pelvis_tz(?!/value).*", ".*lumbar_bending(?!/value).*", ".*lumbar_rotation.*"}, std::vector< std::string > negateAndShiftPatterns={ ".*pelvis_list/value", ".*pelvis_tz/value", ".*lumbar_bending/value"}, std::vector< std::pair< std::string, std::string >> symmetryPatterns={{R"(_r(\_|$))", "_l$1"}, {R"(_l(\_|$))", "_r$1"}})
	Convert a trajectory covering half the period of a symmetric motion into a trajectory over the full period. More...
OSIMMOCO_API int	OpenSim::getMocoParallelEnvironmentVariable ()
	This obtains the value of the OPENSIM_MOCO_PARALLEL environment variable. More...
OSIMMOCO_API TimeSeriesTable	OpenSim::createExternalLoadsTableForGait (Model model, const StatesTrajectory &trajectory, const std::vector< std::string > &forcePathsRightFoot, const std::vector< std::string > &forcePathsLeftFoot)
	Obtain the ground reaction forces, centers of pressure, and torques resulting from Force elements (e.g., SmoothSphereHalfSpaceForce), using a model and states trajectory. More...
OSIMMOCO_API TimeSeriesTable	OpenSim::createExternalLoadsTableForGait (Model model, const MocoTrajectory &trajectory, const std::vector< std::string > &forcePathsRightFoot, const std::vector< std::string > &forcePathsLeftFoot)
	Same as above, but with a MocoTrajectory instead of a StatesTrajectory. More...

Detailed Description

These are free functions and utility classes in the Moco library.

Function Documentation

analyzeMocoTrajectory()

template<typename T >

TimeSeriesTable_<T> OpenSim::analyzeMocoTrajectory	(	Model	model,
		const MocoTrajectory &	trajectory,
		const std::vector< std::string > &	outputPaths
	)

Calculate the requested outputs using the model in the problem and the provided StatesTrajectory and controls table.

The controls table is used to set the model's controls vector. We assume the StatesTrajectory and controls table contain the same time points. The output paths can be regular expressions. For example, ".*activation" gives the activation of all muscles.

The output paths must correspond to outputs that match the type provided in the template argument, otherwise they are not included in the report.

Note

The provided trajectory is not modified to satisfy kinematic constraints, but SimTK::Motions in the Model (e.g., PositionMotion) are applied. Therefore, this function expects that you've provided a trajectory that already satisfies kinematic constraints. If your provided trajectory does not satisfy kinematic constraints, many outputs will be incorrect. For example, in a model with a patella whose location is determined by a CoordinateCouplerConstraint, the length of a muscle that crosses the patella will be incorrect.

Parameters and Lagrange multipliers in the MocoTrajectory are not applied to the model.

References OpenSim::createPeriodicTrajectory(), OpenSim::MocoTrajectory::exportToControlsTable(), OpenSim::MocoTrajectory::exportToStatesTable(), OpenSim::getMocoParallelEnvironmentVariable(), OpenSim::prescribeControlsToModel(), and OpenSim::simulateTrajectoryWithTimeStepping().

createExternalLoadsTableForGait() [1/2]

OSIMMOCO_API TimeSeriesTable OpenSim::createExternalLoadsTableForGait	(	Model	model,
		const StatesTrajectory &	trajectory,
		const std::vector< std::string > &	forcePathsRightFoot,
		const std::vector< std::string > &	forcePathsLeftFoot
	)

Obtain the ground reaction forces, centers of pressure, and torques resulting from Force elements (e.g., SmoothSphereHalfSpaceForce), using a model and states trajectory.

Forces and torques are expressed in the ground frame with respect to the ground origin. Hence, the centers of pressure are at the origin. Paths to Force elements should be provided separately for elements of the right and left feet. The output is a table formatted for use with OpenSim tools; the labels of the columns distinguish between right ("<>_r") and left ("<>_l") forces, centers of pressure, and torques. The forces and torques used are taken from the first six outputs of getRecordValues(); this order is of use for, for example, the SmoothSphereHalfSpaceForce contact model but might have a different meaning for different contact models.

Examples:

example2DWalking.cpp, and example2DWalking.m.

Referenced by OpenSim::FileDeletionThrower::throwIfDeleted().

createExternalLoadsTableForGait() [2/2]

OSIMMOCO_API TimeSeriesTable OpenSim::createExternalLoadsTableForGait	(	Model	model,
		const MocoTrajectory &	trajectory,
		const std::vector< std::string > &	forcePathsRightFoot,
		const std::vector< std::string > &	forcePathsLeftFoot
	)

Same as above, but with a MocoTrajectory instead of a StatesTrajectory.

createPeriodicTrajectory()

OSIMMOCO_API MocoTrajectory OpenSim::createPeriodicTrajectory	(	const MocoTrajectory &	halfPeriodTrajectory,
		std::vector< std::string >	addPatterns = {".*pelvis_tx/value"},
		std::vector< std::string >	negatePatterns = { ".*pelvis_list(?!/value).*", ".*pelvis_rotation.*", ".*pelvis_tz(?!/value).*", ".*lumbar_bending(?!/value).*", ".*lumbar_rotation.*"},
		std::vector< std::string >	negateAndShiftPatterns = { ".*pelvis_list/value", ".*pelvis_tz/value", ".*lumbar_bending/value"},
		std::vector< std::pair< std::string, std::string >>	symmetryPatterns = {{R"(_r(\_|$))", "_l$1"}, {R"(_l(\_|$))", "_r$1"}}
	)

Convert a trajectory covering half the period of a symmetric motion into a trajectory over the full period.

This is useful for simulations of half a gait cycle. This converts time, states, controls, and derivatives; all other quantities from the input trajectory are ignored. If a column in the trajectory does not match addPatterns, negatePatterns, negateAndShiftPatterns, or symmetryPatterns, then the second half of the period contains the same data as the first half.

Parameters

halfPeriodTrajectory	The input trajectory covering half a period.
addPatterns	If a column label matches an addPattern, then the second half of the period for that column is (first_half_trajectory + half_period_value - initial_value).
negatePatterns	If a column label matches a negatePattern, then the second half of the period for that column is (-first_half_trajectory). This is usually relevant for only 3D models.
negateAndShiftPatterns	If a column label matches a negateAndShiftPattern, then the second half of the period for that column is (-first_half_trajectory + 2 * half_period_value). This is usually relevant for only 3D models.
symmetryPatterns	This argument is a list of pairs, where the first element of the pair is a pattern to match, and the second is a substitution to convert the column label into the opposite column label of the symmetric pair. If a column label matches a symmetryPattern, then its first half-period is copied into the second half of the period for the column identified by the substitution.

The default values for the patterns are intended to handle the column labels for typical 2D or 3D OpenSim gait models. The default values for negatePatterns, negateAndShiftPatterns, and symmetryPatterns warrant an explanation. The string pattern before the regex "(?!/value)" is followed by anything except "/value" since it is contained in the negative lookahead "(?!...)". R"()" is a string literal that permits us to not escape backslash characters. The regex "_r(\/|_|$)" matches "_r" followed by either a forward slash (which is escaped), an underscore, OR the end of the string ($). Since the forward slash and end of the string are within parentheses, whatever matches this is captured and is available in the substitution (the second element of the pair) as $1. The default symmetry patterns cause the following replacements:

• "/jointset/hip_r/hip_flexion_r/value" becomes "/jointset/hip_l/hip_flexion_l/value"
• "/forceset/soleus_r" becomes "/forceset/soleus_l"

Examples:

example2DWalking.cpp, example2DWalking.m, and example2DWalkingMetabolics.cpp.

Referenced by OpenSim::analyzeMocoTrajectory().

getMocoParallelEnvironmentVariable()

OSIMMOCO_API int OpenSim::getMocoParallelEnvironmentVariable

(

)

This obtains the value of the OPENSIM_MOCO_PARALLEL environment variable.

The value has the following meanings:

• 0: run in series (not parallel).
• 1: run in parallel using all cores.
• greater than 1: run in parallel with this number of parallel jobs. If the environment variable is not set, this function returns -1.

This variable does not indicate which calculations are parallelized or how the parallelization is achieved. Moco may even ignore or override the setting from the environment variable. See documentation elsewhere (e.g., from a specific MocoSolver) for more information.

Referenced by OpenSim::analyzeMocoTrajectory().

prescribeControlsToModel()

OSIMMOCO_API void OpenSim::prescribeControlsToModel	(	const MocoTrajectory &	trajectory,
		Model &	model,
		std::string	functionType = "GCVSpline"
	)

Given a MocoTrajectory and the associated OpenSim model, return the model with a prescribed controller appended that will compute the control values from the MocoTrajectory.

This can be useful when computing state-dependent model quantities that require realization to the Dynamics stage or later. The function used to fit the controls can either be GCVSpline or PiecewiseLinearFunction.

Referenced by OpenSim::analyzeMocoTrajectory().

simulateTrajectoryWithTimeStepping()

OSIMMOCO_API MocoTrajectory OpenSim::simulateTrajectoryWithTimeStepping	(	const MocoTrajectory &	trajectory,
		Model	model,
		double	integratorAccuracy = SimTK::NaN
	)

Use the controls and initial state in the provided trajectory to simulate the model using an ODE time stepping integrator (OpenSim::Manager), and return the resulting states and controls.

We return a MocoTrajectory (rather than a StatesTrajectory) to facilitate comparing optimal control solutions with time stepping. Use integratorAccuracy to override the default setting.

Note

This function expects all Actuators in the model to be in the Model's ForceSet.

Referenced by OpenSim::analyzeMocoTrajectory().