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 PrescribedController 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...

OSIMMOCO_API TimeSeriesTable	OpenSim::calcGeneralizedForces (Model model, const MocoTrajectory &trajectory, const std::vector< std::string > &forcePaths)
	Compute the set of generalized coordinate forces from the provided Model and MocoTrajectory. 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.; If the MocoTrajectory was generated from a MocoStudy with Controllers in the model, first call MocoTrajectory::generateControlsFromModelControllers() to populate the trajectory with the correct model controls.

References OpenSim::createControlNamesFromModel(), OpenSim::MocoTrajectory::exportToControlsTable(), OpenSim::MocoTrajectory::exportToDerivativesWithoutAccelerationsTable(), OpenSim::MocoTrajectory::exportToStatesTable(), OpenSim::AbstractDataTable::getNumColumns(), and OpenSim::Model::initSystem().

◆ calcGeneralizedForces()

OSIMMOCO_API TimeSeriesTable OpenSim::calcGeneralizedForces	(	Model	model,
		const MocoTrajectory &	trajectory,
		const std::vector< std::string > &	forcePaths
	)

Compute the set of generalized coordinate forces from the provided Model and MocoTrajectory.

The MocoTrajectory should be compatible with the provided Model (e.g., generated from a MocoStudy with the same Model). Only the model Forces that are specified in forcePaths are applied to the model when calculating the generalized forces.

SimbodyMatterSubsystem::calcResidualForce() is used to calculate the joint moments. This takes the set of Lagrange multipliers from the MocoTrajectory and uses them to apply the correct constraint forces to the model.

The generalized coordinate forces are returned as a TimeSeriesTable, where the column labels match the convention used by the InverseDynamicsTool: the coordinates names with suffixes denoting whether they are translational (e.g. pelvis_tx_force) or rotational (e.g., ankle_angle_r_moment) generalized forces.

Examples:: exampleMocoTrack.m.

◆ 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. 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. Centers of pressure are computed assuming the that the contact plane's normal is in the y-direction, which is the OpenSim convention.

The forces and torques are computed from the first six outputs of getRecordValues(), while the centers of pressure are computed from the second six outputs. The first six outputs should correspond to the contact force components applied to the foot bodies (e.g., the "sphere" forces in SmoothSphereHalfSpaceForce), and the second six outputs should correspond to the contact force components applied to the contact place (e.g., the "half-space" forces in SmoothSphereHalfSpaceForce). The contact plane is often attached to ground for foot-ground contact models, but it need not be, as long as the contact plane normal is in the y-direction.

In general, this utility needs getRecordValues() to report the following force and torque information at the specified indices:

index	component (body)
0	force-x (foot)
1	force-y (foot)
2	force-z (foot)
3	torque-x (foot)
4	torque-y (foot)
5	torque-z (foot)
6	force-x (contact plane)
7	force-y (contact plane)
8	force-z (contact plane)
9	torque-x (contact plane)
10	torque-y (contact plane)
11	torque-z (contact plane)

Examples:: example2DWalking.cpp, and example2DWalking.m.

◆ 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.

◆ 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.

◆ 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 PrescribedController appended that will compute the control values from the MocoTrajectory.

This function will also add SignalGenerators to prescribe Input control values for any InputControllers in the model.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.

◆ 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 andexpects all Controllers in the model to be in the Model's ControllerSet.

Classes

Functions