Description

The states, controls, dynamics, parameters, goals, and constraints for a phase of the problem.

The dynamics are provided by the OpenSim Model.

This class allows you to define your problem, but does not let you do anything with your problem (this class only contains user input). Use MocoProblem::createRep() to create an instance of MocoProblemRep, which provides additional functionality.

Supported Model Components

Moco does not support all types of models. Specifically, the following components are not supported:

Actuators with multiple controls (non-ScalarActuators).

Inheritance diagram for OpenSim::MocoPhase:

#include <Moco/Moco/MocoProblem.h>

Public Member Functions
Model *	setModel (std::unique_ptr< Model > model)
	Set the Model whose dynamics should be used for this phase. More...

Model *	setModelCopy (Model model)
	The model is copied into the MocoPhase; further changes made to the passed-in model will have no effect on this MocoPhase. More...

void	setModelProcessor (ModelProcessor model)
	Set a model processor for creating the model for this phase. More...

ModelProcessor &	updModelProcessor ()
	Get a mutable reference to the internal ModelProcessor. More...

void	setTimeBounds (const MocoInitialBounds &, const MocoFinalBounds &)
	Set the bounds on the initial and final time for this phase. More...

void	printStateNamesWithSubstring (const std::string &name)
	Find and print the names of all state variables containing a substring.

void	setStateInfo (const std::string &name, const MocoBounds &bounds, const MocoInitialBounds &init={}, const MocoFinalBounds &final={})
	Set information about a single state variable in this phase. More...

void	setStateInfoPattern (const std::string &pattern, const MocoBounds &bounds, const MocoInitialBounds &init={}, const MocoFinalBounds &final={})
	Set information for state variables whose names match the provided regular expression. More...

void	printControlNamesWithSubstring (const std::string &name)
	Find and print the names of all control variables containing a substring.

void	setControlInfo (const std::string &name, const MocoBounds &, const MocoInitialBounds &={}, const MocoFinalBounds &={})
	Set information about a single control variable in this phase. More...

void	setDefaultSpeedBounds (const MocoBounds &bounds)
	Set the bounds on generalized speed state variables for which explicit bounds are not set. More...

void	setControlInfoPattern (const std::string &pattern, const MocoBounds &, const MocoInitialBounds &={}, const MocoFinalBounds &={})
	Set information for control variables whose names match the provided regular expression. More...

void	setBoundActivationFromExcitation (bool value)
	For muscles without explicit activation bounds, set the bounds for muscle activation (if activation dynamics are enabled) from the bounds for muscle control (excitation), using min/max control if explicit control bounds are not provided. More...

void	setKinematicConstraintBounds (const MocoBounds &bounds)
	Set the bounds on all of the kinematic constraint equations in this phase. More...

void	setMultiplierBounds (const MocoBounds &bounds)
	Set the bounds on all of the Lagrange multipliers in this phase. More...

template<typename MocoParamType , typename... Args>
MocoParamType *	addParameter (Args &&... args)
	Add a parameter to this phase. More...

template<typename MocoParamType >
MocoParamType *	addParameter (std::unique_ptr< MocoParamType > param)

template<typename MocoGoalType , typename... Args>
MocoGoalType *	addGoal (Args &&... args)
	Add a goal to this phase. More...

template<typename MocoGoalType >
MocoGoalType *	addGoal (std::unique_ptr< MocoGoalType > goal)
	Add a goal term to this phase. More...

template<typename MocoPCType , typename... Args>
MocoPCType *	addPathConstraint (Args &&... args)
	Add a path constraint to this phase. More...

template<typename MocoPCType >
MocoPCType *	addPathConstraint (std::unique_ptr< MocoPCType > pc)
	Add a path constraint to this phase. More...

const Model &	getModel () const
	Get the base model in the internal ModelProcessor. More...

Model &	updModel ()
	Get a mutable reference to the base model in the internal ModelProcessor. More...

const ModelProcessor &	getModelProcessor () const
	Get the ModelProcessor.

MocoInitialBounds	getTimeInitialBounds () const

MocoFinalBounds	getTimeFinalBounds () const

const MocoVariableInfo &	getStateInfo (const std::string &name) const
	Access explicit state infos provided to this phase. More...

const MocoVariableInfo &	getControlInfo (const std::string &name) const
	Access explicit control infos provided to this phase. More...

const MocoBounds &	getDefaultSpeedBounds () const

bool	getBoundActivationFromExcitation () const

const MocoBounds &	getKinematicConstraintBounds () const

const MocoBounds &	getMultiplierBounds () const

const MocoParameter &	getParameter (const std::string &name) const

MocoParameter &	updParameter (const std::string &name)

const MocoGoal &	getGoal (const std::string &name) const

MocoGoal &	updGoal (const std::string &name)

const MocoPathConstraint &	getPathConstraint (const std::string &name) const
	Get a MocoPathConstraint from this MocoPhase. More...

MocoPathConstraint &	updPathConstraint (const std::string &name)

Protected Member Functions
	OpenSim_DECLARE_PROPERTY (model, ModelProcessor, "OpenSim Model to provide dynamics.")

	OpenSim_DECLARE_PROPERTY (time_initial_bounds, MocoInitialBounds, "Bounds on initial value.")

	OpenSim_DECLARE_PROPERTY (time_final_bounds, MocoFinalBounds, "Bounds on final value.")

	OpenSim_DECLARE_PROPERTY (default_speed_bounds, MocoBounds, "Bounds for coordinate speeds if not specified in " "state_infos (default: [-50, 50]).")

	OpenSim_DECLARE_PROPERTY (bound_activation_from_excitation, bool, "For muscles without explicit activation bounds, set the bounds " "for muscle activation (if activation dynamics are enabled) from " "the bounds for muscle control (excitation), using " "min/max control if explicit control bounds are not " "provided. (default: true).")

	OpenSim_DECLARE_LIST_PROPERTY (state_infos, MocoVariableInfo, "The state variables' bounds.")

	OpenSim_DECLARE_LIST_PROPERTY (state_infos_pattern, MocoVariableInfo, "Set state variable bounds for all states matching a regular " "expression.")

	OpenSim_DECLARE_LIST_PROPERTY (control_infos, MocoVariableInfo, "The control variables' bounds.")

	OpenSim_DECLARE_LIST_PROPERTY (control_infos_pattern, MocoVariableInfo, "Set control variable bounds for all controls matching a regular " "expression.")

	OpenSim_DECLARE_LIST_PROPERTY (parameters, MocoParameter, "Parameter variables (model properties) to optimize.")

	OpenSim_DECLARE_LIST_PROPERTY (goals, MocoGoal, "Integral/endpoint quantities to minimize or constrain.")

	OpenSim_DECLARE_LIST_PROPERTY (path_constraints, MocoPathConstraint, "Path constraints to enforce in the optimal control problem.")

	OpenSim_DECLARE_PROPERTY (kinematic_constraint_bounds, MocoBounds, "The bounds on all the kinematic constraints in the model to be " "enforced. By default the constraints are strictly enforced (zero " "bounds).")

	OpenSim_DECLARE_PROPERTY (multiplier_bounds, MocoBounds, "Variable info to apply to all Lagrange multipliers in the " "problem. " "The default bounds are [-1000 1000].")

Member Function Documentation

◆ addGoal() [1/2]

template<typename MocoGoalType , typename... Args>

MocoGoalType* OpenSim::MocoPhase::addGoal ( Args &&... args )

inline

Add a goal to this phase.

Goal must have a name (MocoGoal::setName()), and the name must be unique. Note that goals have the name "goal" by default, so if you only have one goal, you don't need to set its name manually. C++ example:

auto goal0Ptr = phase.addGoal<MocoFinalTimeGoal>();

auto goal1Ptr = phase.addGoal<MocoFinalTimeGoal>("final_time");

You can edit the goal using the returned pointer. Python example:

goal = opensim.MocoFinalTimeGoal()

phase.addGoal(goal)

Matlab example:

goal = org.opensim.modeling.MocoFinalTimeGoal();

phase.addGoal(goal);

In both Python and Matlab, changes to goal will affect your problem.

◆ addGoal() [2/2]

template<typename MocoGoalType >

MocoGoalType* OpenSim::MocoPhase::addGoal ( std::unique_ptr< MocoGoalType > goal )

inline

Add a goal term to this phase.

Similar to above.

◆ addParameter()

template<typename MocoParamType , typename... Args>

MocoParamType* OpenSim::MocoPhase::addParameter ( Args &&... args )

inline

Add a parameter to this phase.

Parameter variables must have a name (MocoParameter::setName()), and the name must be unique. Note that parameters have the name "parameter" by default, but choosing a more appropriate name is recommended. C++ example:

// Using the base MocoParameter directly.
auto param0Ptr = phase.addParameter("mass", "body", "mass", {0, 10});
// Using a custom MocoParameter.
auto param1Ptr = phase.addParameter<MyCustomParameter>(...);

You can edit the parameter using the returned pointer. Python example:

param = opensim.MocoParameter()

phase.addParameter(param)

Matlab example:

param = org.opensim.modeling.MocoParameter();

phase.addParameter(param);

In both Python and Matlab, changes to param will affect your problem.

◆ addPathConstraint() [1/2]

template<typename MocoPCType , typename... Args>

MocoPCType* OpenSim::MocoPhase::addPathConstraint ( Args &&... args )

inline

Add a path constraint to this phase.

Path constraints must have a name (MocoPathConstraint::setName()), and the name must be unique. Note that path constraints have the name "path_constraint" by default, so if you only have one path constraint, you don't need to set its name manually. C++ example:

auto pcPtr = phase.addPathConstraint<MyPathConstraint>();

You can edit the constraint using the returned pointer. Python example:

pc = opensim.MyPathConstraint()

phase.addPathConstraint(pc)

Matlab example:

pc = MyPathConstraint();

phase.addPathConstraint(pc);

In both Python and Matlab, changes to pc will affect your problem.

◆ addPathConstraint() [2/2]

template<typename MocoPCType >

MocoPCType* OpenSim::MocoPhase::addPathConstraint ( std::unique_ptr< MocoPCType > pc )

inline

Add a path constraint to this phase.

Similar to above.

◆ getControlInfo()

const MocoVariableInfo& OpenSim::MocoPhase::getControlInfo ( const std::string & name ) const

Access explicit control infos provided to this phase.

Default bounds are obtained from the model. This function does not provide such automatically-populated bounds from the model. For that, use see MocoProblemRep::getControlInfo().

◆ getModel()

const Model& OpenSim::MocoPhase::getModel ( ) const

inline

Get the base model in the internal ModelProcessor.

This throws an exception if the ModelProcessor does not have a base model. By default, the model is an empty model.

◆ getPathConstraint()

const MocoPathConstraint& OpenSim::MocoPhase::getPathConstraint ( const std::string & name ) const

Get a MocoPathConstraint from this MocoPhase.

Note: this does not include MocoKinematicConstraints, use getKinematicConstraint() instead.

◆ getStateInfo()

const MocoVariableInfo& OpenSim::MocoPhase::getStateInfo ( const std::string & name ) const

Access explicit state infos provided to this phase.

For some state variables, default bounds are obtained from the model. This function does not provide such automatically-populated bounds from the model. For that, use see MocoProblemRep::getStateInfo().

◆ getTimeFinalBounds()

MocoFinalBounds OpenSim::MocoPhase::getTimeFinalBounds ( ) const

Note: the return value is constructed fresh on every call from the internal property. Avoid repeated calls to this function.

◆ getTimeInitialBounds()

MocoInitialBounds OpenSim::MocoPhase::getTimeInitialBounds ( ) const

Note: the return value is constructed fresh on every call from the internal property. Avoid repeated calls to this function.

◆ setBoundActivationFromExcitation()

void OpenSim::MocoPhase::setBoundActivationFromExcitation ( bool value )

inline

For muscles without explicit activation bounds, set the bounds for muscle activation (if activation dynamics are enabled) from the bounds for muscle control (excitation), using min/max control if explicit control bounds are not provided.

Default: true.

◆ setControlInfo()

void OpenSim::MocoPhase::setControlInfo	(	const std::string &	name,
		const MocoBounds &	,
		const MocoInitialBounds &	= `{}`,
		const MocoFinalBounds &	= `{}`
	)

Set information about a single control variable in this phase.

Similar to setStateInfo(). The name for a control is the path to the associated actuator (e.g., "/forceset/soleus_r"). If setting a control info for an actuator with multiple controls, the name should be the actuator path appended by the control index (e.g. "/actuator_0"); If info is not specified for a ScalarActuator (or if only the initial and/or final bounds are provided), the actuator's min and max control are used for the bounds over the phase. By default, non-ScalarActuators are unconstrained.

◆ setControlInfoPattern()

void OpenSim::MocoPhase::setControlInfoPattern	(	const std::string &	pattern,
		const MocoBounds &	,
		const MocoInitialBounds &	= `{}`,
		const MocoFinalBounds &	= `{}`
	)

Set information for control variables whose names match the provided regular expression.

You can use this to set bounds for all muscle activations, etc. Infos provided via setControlInfoPattern() take precedence over the default values from the model. Infos provided via setControlInfo() take precedence over infos provided with setControlInfoPattern(). If a state variable name matches multiple patterns, the info provided with the last pattern is used for that control variable.

◆ setDefaultSpeedBounds()

void OpenSim::MocoPhase::setDefaultSpeedBounds ( const MocoBounds & bounds )

inline

Set the bounds on generalized speed state variables for which explicit bounds are not set.

◆ setKinematicConstraintBounds()

void OpenSim::MocoPhase::setKinematicConstraintBounds ( const MocoBounds & bounds )

inline

Set the bounds on all of the kinematic constraint equations in this phase.

When creating a MocoProblemRep, these bounds are used to create MocoConstraintInfo's for each kinematic constraint equation in the phase.

◆ setModel()

Model* OpenSim::MocoPhase::setModel ( std::unique_ptr< Model > model )

Set the Model whose dynamics should be used for this phase.

The phase takes ownership of the passed-in model. This function returns a pointer to the model stored in the phase (identical to the passed-in model).

◆ setModelCopy()

Model* OpenSim::MocoPhase::setModelCopy ( Model model )

The model is copied into the MocoPhase; further changes made to the passed-in model will have no effect on this MocoPhase.

This function returns a pointer to the model stored in the phase (the copy).

◆ setModelProcessor()

void OpenSim::MocoPhase::setModelProcessor ( ModelProcessor model )

Set a model processor for creating the model for this phase.

Use this to provide a model as a .osim file.

◆ setMultiplierBounds()

void OpenSim::MocoPhase::setMultiplierBounds ( const MocoBounds & bounds )

inline

Set the bounds on all of the Lagrange multipliers in this phase.

When creating a MocoProblemRep, these bounds are used to create MocoVariableInfos for each Lagrange multiplier in the phase.

◆ setStateInfo()

void OpenSim::MocoPhase::setStateInfo	(	const std::string &	name,
		const MocoBounds &	bounds,
		const MocoInitialBounds &	init = `{}`,
		const MocoFinalBounds &	final = `{}`
	)

Set information about a single state variable in this phase.

Parameters

name	The name must match the path of a state variable in the model (e.g., `/hip/flexion/value` or `/hip/flexion/speed`).
bounds	The bounds on this state variable over the entire phase. If default-constructed (`{}`), then either the variable is unconstrained or default bounds are used (see below).
init	The bounds on this state variable at the start of the phase. By default, there are no additional bounds on the initial value (though the `bounds` over the entire phase still apply to the initial value).
final	Similar to `init` but for the value at the end of the phase.

For all bounds arguments: if you want to constrain to a single value, pass that single value. If you want to constrain to a range, pass the lower and upper bounds to the constructor as two arguments.

Default bounds

Coordinate values: the Coordinate's range is used (regardless of whether the coordinate is clamped).
Coordinate speeds: this class's default_speed_bounds property.
All other states: if a component has a SimTK::Vec2 output named statebounds_<state-name>, then this output is used to set default bounds for the state variable <state-name> for that component. The first element of the Vec2 is the lower bound and the second is the upper bound.

These defaults are also used if you completely omit state info for a state variable.

For states with default bounds, if you actually want a variable to be unconstrained, pass in MocoBounds::unconstrained().

Examples

Set bounds over the entire phase, but do not specify additional bounds on the value at the start and end of the phase.

phase.setStateInfo("/knee/flexion/value", {-1.5*SimTK::Pi, 0});

Allow any value throughout the phase (within the coordinate's range), but the initial value is 5.

phase.setStateInfo("/ankle/flexion/value", {}, 5);

Constrain the initial and final state to a single value of 0, but use default speed bounds elsewhere.

phase.setStateInfo("/ankle/flexion/speed", {}, 0, 0);

Make a coordinate value unconstrained.

phase.setStateInfo("/ankle/flexion/value", MocoBounds::unconstrained());

This function will overwrite any info that has previously been set for this state variable.

◆ setStateInfoPattern()

void OpenSim::MocoPhase::setStateInfoPattern	(	const std::string &	pattern,
		const MocoBounds &	bounds,
		const MocoInitialBounds &	init = `{}`,
		const MocoFinalBounds &	final = `{}`
	)

Set information for state variables whose names match the provided regular expression.

You can use this to set bounds for all muscle activations, etc. Infos provided via setStateInfoPattern() take precedence over the default values from the model. Infos provided via setStateInfo() take precedence over infos provided with setStateInfoPattern(). If a state variable name matches multiple patterns, the info provided with the last pattern is used for that state variable.

◆ setTimeBounds()

void OpenSim::MocoPhase::setTimeBounds	(	const MocoInitialBounds &	,
		const MocoFinalBounds &
	)

Set the bounds on the initial and final time for this phase.

If you want to constrain the initial time to a single value, pass that value to the constructor of MocoInitialBounds. If you want the initial time to fall within a range, pass the lower and upper bounds to the constructor of MocoInitialBounds. Likewise for MocoFinalBounds. This will overwrite bounds that were set previously, if any.

◆ updModel()

Model& OpenSim::MocoPhase::updModel ( )

inline

Get a mutable reference to the base model in the internal ModelProcessor.

This throws an exception if the ModelProcessor does not have a base model. By default, the model is an empty model.

◆ updModelProcessor()

ModelProcessor& OpenSim::MocoPhase::updModelProcessor ( )

Get a mutable reference to the internal ModelProcessor.

Use this to set the processor's base model or to add operators to the processor.

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

MocoProblem.h

Description

Supported Model Components

Public Member Functions

Protected Member Functions

Member Function Documentation

◆ addGoal() [1/2]

◆ addGoal() [2/2]

◆ addParameter()

◆ addPathConstraint() [1/2]

◆ addPathConstraint() [2/2]

◆ getControlInfo()

◆ getModel()

◆ getPathConstraint()

◆ getStateInfo()

◆ getTimeFinalBounds()

◆ getTimeInitialBounds()

◆ setBoundActivationFromExcitation()

◆ setControlInfo()

◆ setControlInfoPattern()

◆ setDefaultSpeedBounds()

◆ setKinematicConstraintBounds()

◆ setModel()

◆ setModelCopy()

◆ setModelProcessor()

◆ setMultiplierBounds()

◆ setStateInfo()

Default bounds

Examples

◆ setStateInfoPattern()

◆ setTimeBounds()

◆ updModel()

◆ updModelProcessor()