# Variables¶

An Optimal Control problem in Dymos consists of the following variable types.

## Time¶

Optimal control problems in Dymos assume a system that is evolving in time. State variables typically obey some ordinary differential equation that provides the derivative of the states w.r.t. time.

Users can specify various options relating to time with the set_time_options method of Phase.

In Dymos, the phase time is controlled by two inputs:

• t_initial - The initial time of the phase
• t_duration - The duration of the phase

The bounds, scaling, and units of these variables may be set using set_time_options. In addition, the user can specify that the initial time or duration of a phase is to be connected to some external output by specifying input_initial = True or input_duration = True. In the case of fixed initial time or duration, or input initial time or duration, the optimization-related options have no effect and a warning will be raised if they are used.

The variables t_initial and t_duration are converted to time values at the nodes within the phase. Dymos computes the following time values, which can be used inside the ODE:

• time - The canonical time. At the start of the phase time = t_initial, and time = t_initial + t_duration at the end of the phase.
• time_phase - The elapsed time since the beginning of the phase. time_phase = time - t_initial
• t_initial - The initial time of the current phase (this value is the same at all nodes within the phase).
• t_duration - The phase time duration of the current phase (this value is the same at all nodes within the phase).

### Options for Time Variables¶

Option Default Acceptable Values Acceptable Types Description
duration_adder None N/A ['Number'] Adder for the duration of the integration variable across the phase.
duration_bounds (None, None) N/A ['Iterable'] Tuple of (lower, upper) bounds for the duration of the integration variable across the phase.
duration_ref None N/A ['Number'] Unit-reference value for the duration of the integration variable across the phase.
duration_ref0 None N/A ['Number'] Zero-reference value for the duration of the integration variable across the phase.
duration_scaler None N/A ['Number'] Scalar for the duration of the integration variable across the phase.
duration_val 1.0 N/A ['Number'] Value of the duration of the integration variable across the phase.
fix_duration False [True, False] ['bool'] If True, the phase duration is not a design variable.
fix_initial False [True, False] ['bool'] If True, the initial value of time is not a design variable.
initial_adder None N/A ['Number'] Adder for the initial value of the integration variable.
initial_bounds (None, None) N/A ['Iterable'] Tuple of (lower, upper) bounds for the integration variable at the start of the phase.
initial_ref None N/A ['Number'] Unit-reference value for the initial value of the integration variable.
initial_ref0 None N/A ['Number'] Zero-reference value for the initial value of the integration variable.
initial_scaler None N/A ['Number'] Scalar for the initial value of the integration variable.
initial_val 0.0 N/A ['Number'] Value of the integration variable at the start of the phase.
input_duration False [True, False] ['bool'] If True, the phase duration (t_duration) is expected to be connected to an external output source.
input_initial False [True, False] ['bool'] If True, the initial value of time (t_initial) is expected to be connected to an external output source.
t_duration_targets [] N/A ['Iterable'] targets in the ODE to which the total duration of the phase is connected
t_initial_targets [] N/A ['Iterable'] targets in the ODE to which the initial time of the phase is connected
targets [] N/A ['Iterable'] targets in the ODE to which the integration variable is connected
time_phase_targets [] N/A ['Iterable'] targets in the ODE to which the elapsed duration of the phase is connected
units s N/A ['str'] Units for the integration variable

## States¶

States are variables that define the current condition of the system. For instance, in trajectory optimization they are typically coordinates that define the position and velocity of the vehicle. They can also be things like component bulk temperatures or battery state-of-charge. In most dynamic systems, states obey some ordinary differential equation. As such, these are defined in an ODE object.

At the phase level, we assume that states evolve continuously such that they can be modeled as a series of one or more polynomials. The phase duration is broken into one or more segments on which each state (and each dynamic control) is modeled as a polynomial. The order of the polynomial is specified using the transcription_order method. In Dymos, the minimum state transcription order is 3.

Users can specify bounds and scaling of the state variables with the phase method add_state. The units and shape arguments are not required, as dymos will pull that information from the rate_source when possible. You may still add units if you would like the driver or the timeseries to see a different unit than what is defined in the rate source. There are two exceptions: - If the rate_source references a control that has no targets, shape is required. - If the rate_source is another state, that state needs to be declared first. If the relationship is circular, shape is required.

Settings on a previously-added state variable may be changed using the set_state_options method. The following options are valid:

### Options for State Variables¶

Option Default Acceptable Values Acceptable Types Description
adder None N/A ['Iterable', 'Number'] Adder of the state variable at the discretization nodes. This option is invalid if opt=False.
connected_initial False [True, False] ['bool'] Whether an input is created to pass in the initial state. This may be set by a trajectory that links phases.
continuity True N/A ['bool', 'dict'] Enforce continuity of state values at segment boundaries. This option is invalid if opt=False.
defect_ref None N/A ['Iterable', 'Number'] Unit-reference value of the state defects at the collocation nodes. This option is invalid if opt=False. If provided, this option overrides defect_scaler. If defect_scaler and defect_ref are both None but the state scaler or ref are provided, use those values as the defect scaler or ref.
defect_scaler None N/A ['Iterable', 'Number'] Scaler of the state variable defects at the collocation nodes. If defect_scaler and defect_ref are both None but the state scaler or ref are provided, use those values as the defect scaler or ref. This option is invalid if opt=False.
desc N/A ['str'] description of the state variable
final_bounds None N/A ['Iterable'] Bounds on the value of the state at the end of the phase. This option is invalid if opt=False.
fix_final False N/A ['bool', 'Iterable'] If True, the final value of this state is fixed and not a design variable. If the state variable has a non-scalar shape, this may be an iterable of bool for each index. This option is invalid if opt=False.
fix_initial False N/A ['bool', 'Iterable'] If True, the initial value of this state is fixed and not a design variable. If the state variable has a non-scalar shape, this may be an iterable of bool for each index. This option is invalid if opt=False.
initial_bounds None N/A ['Iterable'] Bounds on the value of the state at the start of the phase. This option is invalid if opt=False.
lower None N/A ['Iterable', 'Number'] Lower bound of the state variable at the discretization nodes. This option is invalid if opt=False.
name Required N/A ['str'] name of ODE state variable
opt True [True, False] ['bool'] If true, the values of this state are a design variable for the optimizer. Otherwise it exists as an unconnected input.
rate_source None N/A ['str'] ODE-path to the derivative of the state variable
ref None N/A ['Iterable', 'Number'] Unit-reference value of the state variable at the discretization nodes. This option is invalid if opt=False.
ref0 None N/A ['Iterable', 'Number'] Zero-reference value of the state variable at the discretization nodes. This option is invalid if opt=False.
scaler None N/A ['Iterable', 'Number'] Scaler of the state variable at the discretization nodes. This option is invalid if opt=False.
shape None N/A ['Iterable'] shape of the state variable, as determined by introspection
solve_segments None [True, False, 'forward', 'backward'] N/A If True (deprecated) or 'forward', collocation defects within eachsegment are solved with a Newton solver by fixing the initial value in thephase (if using compressed transcription) or segment (if not using compressed transcription). This provides a forward shooting (or multiple shooting)method. If 'backward', the final value in the phase or segment is fixedand a solver finds the other ones to mimic reverse propagation. If None, (the default) use the value of solve_segments in the transcription. Set to False to explicitly disable the use of a solver to converge the statetime history.
targets unspecified N/A N/A Targets in the ODE to which the state is connected
units unspecified N/A N/A units in which the state variable is defined
upper None N/A ['Iterable', 'Number'] Upper bound of the state variable at the discretization nodes. This option is invalid if opt=False.
val 1.0 N/A ['Iterable', 'Number'] Default value of the state variable at the discretization nodes

The Radau Pseudospectral and Gauss Lobatto phases types in Dymos use differential defects to approximate the evolution of the state variables with respect to time. In addition to scaling the state values, scaling the defect constraints correctly is important to good performance of the collocation algorithms. This is accomplished with the defect_scaler or defect_ref options. As the name implies, defect_scaler is multiplied by the defect value to provide the defect constraint value to the optimizer. Alternatively, the user can specify defect_ref. If provided, defect_ref overrides defect_scaler and is the value of the defect seen as 1 by the optimizer.

If the ODE is explicitly depending on a state's value (for example, the brachistochrone ODE is a function of the bead's speed), then the user specifies those inputs in the ODE to which the state is to be connected using the targets option. It can take the following values:

• (default) If left unspecified, targets assumes a special dymos.utils.misc._unspecified value. In this case, dymos will attempt to connect to an input of the same name at the top of the ODE (either promoted there, or there because the ODE is a single component).

• None The state is explicitly not connected to any inputs in the ODE.

• str or sequence of str The state values are connected to inputs of the given name or names in the ODE. These targets are specified by their path relative to the top level of the ODE.

To simplify state specifications, using the first option (not specifying targets) and promoting targets of the state to inputs of the same name at the top-level of the ODE.

## Controls¶

Typically, an ODE will have inputs that impact its values but, unlike states, don't define the system itself. Such inputs include things like throttle level, elevator deflection angle, or spring constants. In Dymos, dynamic inputs are referred to as controls, while static inputs are called parameters.

Dynamic controls are values which we might expect to vary continuously throughout a trajectory, like an elevator deflection angle for instance. The value of these controls are often determined by an optimizer.

Note

The order of a dynamic control polynomial in a segment is one less than the state transcription order (i.e. a dynamic control in a phase with transcription_order=3 will be represented by a second-order polynomial.

### Options for Control Variables¶

Option Default Acceptable Values Acceptable Types Description
adder None N/A ['Iterable', 'Number'] The adder of the control variable at the nodes. This option is invalid if opt=False.
continuity True N/A ['bool', 'dict'] Enforce continuity of control values at segment boundaries. This option is invalid if opt=False.
desc N/A ['str'] The description of the control variable.
dynamic True [True, False] ['bool'] If True, the value of the shape of the parameter will be (num_nodes, ...), allowing the variable to be used as either a static or dynamic control. This impacts the shape of the partial derivatives matrix. Unless a parameter is large and broadcasting a value to each individual node would be inefficient, users should stick to the default value of True.
fix_final False [True, False] ['bool'] If True, the final value of this control is fixed and not a design variable. This option is invalid if opt=False.
fix_initial False [True, False] ['bool'] If True, the initial value of this control is fixed and not a design variable. This option is invalid if opt=False.
lower None N/A ['Iterable', 'Number'] The lower bound of the control variable at the nodes. This option is invalid if opt=False.
name Required N/A ['str'] The name of ODE system parameter to be controlled.
opt True [True, False] ['bool'] If True, the control value will be a design variable for the optimization problem. If False, allow the control to be connected externally.
rate2_continuity False N/A ['bool', 'dict'] Enforce continuity of control second derivatives at segment boundaries. This option is invalid if opt=False.
rate2_continuity_scaler 1.0 N/A ['Number'] Scaler of the dimensionless rate continuity constraint at segment boundaries. This option is invalid if opt=False.
rate2_targets unspecified N/A N/A The targets in the ODE to which the control 2nd derivative is connected
rate_continuity True N/A ['bool', 'dict'] Enforce continuity of control first derivatives in dimensionless time at segment boundaries. This option is invalid if opt=False.
rate_continuity_scaler 1.0 N/A ['Number'] Scaler of the dimensionless rate continuity constraint at segment boundaries. This option is invalid if opt=False.
rate_targets unspecified N/A N/A The targets in the ODE to which the control rate is connected
ref None N/A ['Iterable', 'Number'] The unit-reference value of the control variable at the nodes. This option is invalid if opt=False.
ref0 None N/A ['Iterable', 'Number'] The zero-reference value of the control variable at the nodes. This option is invalid if opt=False.
scaler None N/A ['Iterable', 'Number'] The scaler of the control variable at the nodes. This option is invalid if opt=False.
shape None N/A ['Iterable'] The shape of the control variable at each point in time.
targets unspecified N/A N/A Targets in the ODE to which the state is connected
units unspecified N/A N/A The units in which the control variable is defined.
upper None N/A ['Iterable', 'Number'] The upper bound of the control variable at the nodes. This option is invalid if opt=False.
val [0.] N/A ['Iterable', 'ndarray', 'Number'] The default value of the control variable at the control discretization nodes.

Control values are connected to the ODE using the targets argument. The values of this argument obey the same rules as those for states.

The control first and second derivatives w.r.t. time may also be connected to the ODE. First derivatives of controls in Dymos assume the name <control_name>_rate. Second derivatives of controls in Dymos assume the name <control_name>_rate2. Control rates are automatically connected if a top-level input of the ODE is named <control_name>_rate or <control_name>_rate2. These variables are available in the timeseries output as timeseries.control_rates.<control_name>_rate and timeseries.control_rates.<control_name>_rate2, respectively.

## Polynomial Controls¶

Sometimes it can be easier to optimize a problem by reducing the freedom in the controls. For instance, one might want the control to be linearly or quadratically varying throughout a phase, rather than having a different value specified at each node. In Dymos, this role is filled by the PolynomialControl. Polynomial controls are specified at some limited number of points throughout a phase, and then have their values interpolated to each node in each segment.

### Options for Polynomial Control Variables¶

Option Default Acceptable Values Acceptable Types Description
adder None N/A ['Iterable', 'Number'] The adder of the control variable at the nodes. Thisoption is invalid if opt=False.
desc N/A ['str'] The description of the control variable.
dynamic True [True, False] ['bool'] If True, the value of the shape of the parameter will be (num_nodes, ...), allowing the variable to be used as either a static or dynamic control. This impacts the shape of the partial derivatives matrix. Unless a parameter is large and broadcasting a value to each individual node would be inefficient, users should stick to the default value of True.
fix_final False [True, False] ['bool'] If True, the final value of this control is fixed and not a design variable. This option is invalid if opt=False.
fix_initial False [True, False] ['bool'] If True, the initial value of this control is fixed and not a design variable. This option is invalid if opt=False.
lower None N/A ['Iterable', 'Number'] The lower bound of the control variable at the nodes. This option is invalid if opt=False.
name Required N/A ['str'] The name of ODE system parameter to be controlled.
opt True [True, False] ['bool'] If True, the control value will be a design variable for the optimization problem. If False, allow the control to be connected externally.
order None N/A ['int'] A integer that provides the interpolation order when the control is to assume a single polynomial basis across the entire phase, or None to use the default control behavior.
rate2_targets unspecified N/A N/A The targets in the ODE to which the polynomial control 2nd derivative is connected
rate_targets unspecified N/A N/A The targets in the ODE to which the polynomial control rate is connected
ref None N/A ['Iterable', 'Number'] The unit-reference value of the control variable at the nodes. This option is invalid if opt=False.
ref0 None N/A ['Iterable', 'Number'] The zero-reference value of the control variable at the nodes. This option is invalid if opt=False.
scaler None N/A ['Iterable', 'Number'] The scaler of the control variable at the nodes. This option is invalid if opt=False.
shape None N/A ['Iterable'] The shape of the control variable at each point in time.
targets unspecified N/A N/A Targets in the ODE to which the state is connected
units unspecified N/A N/A The units in which the control variable is defined.
upper None N/A ['Iterable', 'Number'] The upper bound of the control variable at the nodes. This option is invalid if opt=False.
val [0.] N/A ['Iterable', 'ndarray', 'Number'] The default value of the control variable at the control discretization nodes.

Polynomial values are connected to the ODE using the targets argument. The values of this argument obey the same rules as those for states.

The polynomial control first and second derivatives w.r.t. time may also be connected to the ODE. First derivatives of controls in Dymos assume the name <control_name>_rate. Second derivatives of controls in Dymos assume the name <control_name>_rate2. Control rates are automatically connected if a top-level input of the ODE is named <control_name>_rate or <control_name>_rate2. These variables are available in the timeseries output as timeseries.polynomial_control_rates.<control_name>_rate and timeseries.polynomial_control_rates.<control_name>_rate2, respectively.

## Parameters¶

Some inputs impact the system but have one set value throughout the trajectory. We refer to these non-time-varying inputs as parameters, since they typically involve parameters which define a system. Parameters could include things like the wingspan of a vehicle or the mass of a heatsink. In Dymos, parameters can be optimized (by providing argument opt = True). If not optimized they can be targets for connections from outside of the Phase or Trajectory.

### Options for Parameters¶

Option Default Acceptable Values Acceptable Types Description
adder None N/A ['Iterable', 'Number'] The adder of the parameter. This option is invalid if opt=False.
desc N/A ['str'] The description of the parameter.
dynamic True [True, False] ['bool'] True if this parameter can be used as a dynamic control, else False
include_timeseries True [True, False] ['bool'] True if the static parameters should be included in output timeseries, else False
lower None N/A ['Iterable', 'Number'] The lower bound of the parameter. This option is invalid if opt=False.
name Required N/A ['str'] The name of ODE system parameter to be set via parameter.
opt True [True, False] ['bool'] If True, the control value will be a design variable for the optimization problem. If False, allow the control to be connected externally.
ref None N/A ['Iterable', 'Number'] The unit-reference value of the parameter. This option is invalid if opt=False.
ref0 None N/A ['Iterable', 'Number'] The zero-reference value of the parameter. This option is invalid if opt=False.
scaler None N/A ['Iterable', 'Number'] The scaler of the parameter. This option is invalid if opt=False.
shape unspecified N/A N/A The shape of the parameter.
targets unspecified N/A N/A Targets in the ODE to which the state is connected
units unspecified N/A N/A The units in which the parameter is defined.
upper None N/A ['Iterable', 'Number'] The upper bound of the parameter. This option is invalid if opt=False.
val [0.] N/A ['Iterable', 'ndarray', 'Number'] The default value of the parameter in the phase.

Parameters can have their values determined by the optimizer, or they can be passed in from an external source.

Parameters obey the same connection rules as other variables, if targets is left unspecified.

Parameters are available in the timeseries output as timeseries.parameters.<parameter_name>. Since parameters are constant throughout a trajectory, some users may want to prevent them from inclusion in the timeseries. This can be done by specifying include_timeseries = False in the parameter options.