# 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).

### Renaming the integration variable#

In some casees the integration in a phase might take place over some non-time variable. For instance, in the race car example, thee dynamics are integrated over the track length `s`

. In such cases it might be preferable to rename the time variable to make the outputs somewhat more understandable. This can be achieved by using the `name`

parameter to `set_time_options`

, for instance:

```
phase.set_time_options(name='s', ...)
```

When doing so, the timeseries will replace `time`

with the given name `s`

and `time_phase`

with `s_phase`

.
If one wishes to use the renamed integration variablee (or the phase-relative version), it can be used in the `add_objective`

and `add_boundary_constraint`

and `add_path_constraint`

methods on `Phase`

. For instance:

```
phase.set_time_options(name='W', ...)
.
.
.
phase.add_objective('W', loc='final')
```

### Recovering time for the timeseries outputs#

When creating timeseries plots in dymos, it expects the `phase_name.timeseries.time`

to be present. In a multi-phase trajectory where some phases use a different variable of integratoin, it may be helpful to to add an expression for time to the timeseries manually.

For instance, the race car example integrates the expression `dt_ds`

to accumulate the elapsed time of the phase as a state named `t`

. This can be manulally added to the timeseries outputs

```
phase.add_timeseries_output('t', output_name='time')
```

Similarly, we can form linkage constraints that would link two phases where time might be the integration variable in one phase and a state variable in a subsequent phase.

### Options for Time Variables#

```
om.show_options_table("dymos.phase.options.TimeOptionsDictionary")
```

Option | Default | Acceptable Values | Acceptable Types | Description |
---|---|---|---|---|

duration_adder | N/A | 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 | N/A | N/A | ['Number'] | Unit-reference value for the duration of the integration variable across the phase. |

duration_ref0 | N/A | N/A | ['Number'] | Zero-reference value for the duration of the integration variable across the phase. |

duration_scaler | N/A | 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 | N/A | 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 | N/A | N/A | ['Number'] | Unit-reference value for the initial value of the integration variable. |

initial_ref0 | N/A | N/A | ['Number'] | Zero-reference value for the initial value of the integration variable. |

initial_scaler | N/A | 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. |

name | time | N/A | ['str'] | Name of the integraiton variable in the phase. |

t_duration_balance_options | {} | N/A | N/A | options dictionary for the duration residual |

t_duration_targets | [] | N/A | N/A | targets in the ODE to which the total duration of the phase is connected |

t_initial_targets | [] | N/A | N/A | targets in the ODE to which the initial time of the phase is connected |

targets | unspecified | N/A | N/A | targets in the ODE to which the integration variable is connected |

time_phase_targets | unspecified | N/A | N/A | 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#

```
om.show_options_table("dymos.phase.options.StateOptionsDictionary")
```

Option | Default | Acceptable Values | Acceptable Types | Description | Deprecation |
---|---|---|---|---|---|

adder | N/A | N/A | ['Iterable', 'Number'] | Adder of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

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. | State option 'connected_initial' is deprecated. Please use 'input_initial' instead. |

continuity | True | N/A | ['bool', 'dict'] | Enforce continuity of state values at segment boundaries. This option is invalid if opt=False. | N/A |

continuity_ref | N/A | N/A | ['Number'] | Reference unit value for continuity at segment boundaries instead of scaler.This option is invalid if opt=False. | N/A |

continuity_scaler | N/A | N/A | ['Number'] | Scaler for continuity at segment boundaries. This option is invalid if opt=False. | N/A |

defect_ref | N/A | 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. | N/A |

defect_scaler | N/A | 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. | N/A |

desc | N/A | ['str'] | description of the state variable | N/A | |

final_bounds | N/A | N/A | ['Iterable'] | Bounds on the value of the state at the end of the phase. This option is invalid if opt=False. | N/A |

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. | N/A |

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. | N/A |

initial_bounds | N/A | N/A | ['Iterable'] | Bounds on the value of the state at the start of the phase. This option is invalid if opt=False. | N/A |

input_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. | N/A |

lower | N/A | N/A | ['Iterable', 'Number'] | Lower bound of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

name | **Required** | N/A | ['str'] | name of ODE state variable | N/A |

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. | N/A |

rate_source | N/A | N/A | ['str'] | ODE-path or phase variable providing the derivative of the state variable | N/A |

ref | N/A | N/A | ['Iterable', 'Number'] | Unit-reference value of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

ref0 | N/A | N/A | ['Iterable', 'Number'] | Zero-reference value of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

scaler | N/A | N/A | ['Iterable', 'Number'] | Scaler of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

shape | N/A | N/A | ['Iterable'] | shape of the state variable, as determined by introspection | N/A |

solve_segments | N/A | [False, 'forward', 'backward'] | N/A | If '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. | N/A |

source | N/A | N/A | ['str'] | RHS-path or phase variable providing value of the state variable, for Analytic transcription only! | N/A |

targets | unspecified | N/A | N/A | Targets in the ODE to which the state is connected | N/A |

units | unspecified | N/A | N/A | units in which the state variable is defined | N/A |

upper | N/A | N/A | ['Iterable', 'Number'] | Upper bound of the state variable at the discretization nodes. This option is invalid if opt=False. | N/A |

val | 1.0 | N/A | ['Iterable', 'Number'] | Default value of the state variable at the discretization nodes | N/A |

The Radau Pseudospectral and Gauss Lobatto phase 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#

```
om.show_options_table("dymos.phase.options.ControlOptionsDictionary")
```

Option | Default | Acceptable Values | Acceptable Types | Description |
---|---|---|---|---|

adder | N/A | 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. |

continuity_ref | N/A | N/A | ['Number'] | Reference unit value for continuity at segment boundaries instead of scaler.This option is invalid if opt=False. |

continuity_scaler | N/A | N/A | ['Number'] | Scaler for continuity at segment boundaries. This option is invalid if opt=False. |

desc | N/A | ['str'] | The description of the control variable. | |

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 | N/A | 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_ref | N/A | N/A | ['Number'] | Reference unit value for rate2 continuity at segment boundaries instead of scaler.This option is invalid if opt=False. |

rate2_continuity_scaler | N/A | N/A | ['Number'] | Scaler of the rate2 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_ref | N/A | N/A | ['Number'] | Reference unit value for rate continuity at segment boundaries instead of scaler.This option is invalid if opt=False. |

rate_continuity_scaler | N/A | N/A | ['Number'] | Scaler of the 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 | N/A | N/A | ['Iterable', 'Number'] | The unit-reference value of the control variable at the nodes. This option is invalid if opt=False. |

ref0 | N/A | N/A | ['Iterable', 'Number'] | The zero-reference value of the control variable at the nodes. This option is invalid if opt=False. |

scaler | N/A | N/A | ['Iterable', 'Number'] | The scaler of the control variable at the nodes. This option is invalid if opt=False. |

shape | N/A | 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 | N/A | 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#

```
om.show_options_table("dymos.phase.options.PolynomialControlOptionsDictionary")
```

Option | Default | Acceptable Values | Acceptable Types | Description |
---|---|---|---|---|

adder | N/A | 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. | |

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 | N/A | 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 | N/A | 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 | N/A | N/A | ['Iterable', 'Number'] | The unit-reference value of the control variable at the nodes. This option is invalid if opt=False. |

ref0 | N/A | N/A | ['Iterable', 'Number'] | The zero-reference value of the control variable at the nodes. This option is invalid if opt=False. |

scaler | N/A | N/A | ['Iterable', 'Number'] | The scaler of the control variable at the nodes. This option is invalid if opt=False. |

shape | N/A | 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 | N/A | 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#

```
om.show_options_table("dymos.phase.options.ParameterOptionsDictionary")
```

Option | Default | Acceptable Values | Acceptable Types | Description | Deprecation |
---|---|---|---|---|---|

adder | N/A | N/A | ['Iterable', 'Number'] | The adder of the parameter. This option is invalid if opt=False. | N/A |

desc | N/A | ['str'] | The description of the parameter. | N/A | |

dynamic | unspecified | [True, False, unspecified] | N/A | True if this parameter can be used as a dynamic control, else False.If _unspecified, attempt to determine through introspection. | Option dynamic has been replaced by option 'static_target' and will be removed in Dymos 2.0.0. Note that 'static_target' has the opposite meaning of option 'dynamic', so parameters with option 'dynamic' set to False should now use 'static_target' set to True. |

include_timeseries | N/A | [True, False] | ['bool'] | True if the static parameters should be included in output timeseries, else False.If None (default) set the value based on Phase.timeseries_options["include_parameters"] | N/A |

lower | N/A | N/A | ['Iterable', 'Number'] | The lower bound of the parameter. This option is invalid if opt=False. | N/A |

name | **Required** | N/A | ['str'] | The name of ODE system parameter to be set via parameter. | N/A |

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. | N/A |

ref | N/A | N/A | ['Iterable', 'Number'] | The unit-reference value of the parameter. This option is invalid if opt=False. | N/A |

ref0 | N/A | N/A | ['Iterable', 'Number'] | The zero-reference value of the parameter. This option is invalid if opt=False. | N/A |

scaler | N/A | N/A | ['Iterable', 'Number'] | The scaler of the parameter. This option is invalid if opt=False. | N/A |

shape | unspecified | N/A | N/A | The shape of the parameter. | N/A |

static_target | unspecified | N/A | N/A | True if the target of this parameter does NOT have a unique value at each node in the ODE.If _unspecified, attempt to determine through introspection. | Use option `static_targets` to specify whether all targets are static (static_targets=True), none are static (static_targets=False), static_targets are determined via introspection (static_targets=_unspecified), or give an explicit sequence of the static targets. |

static_targets | unspecified | N/A | N/A | If a boolean, specifies whether all targets are static (True), or no targets are static (False). Otherwise, provide a list of the static targets within the ODE. If left unspecified, static targets will be determined by finding inptus tagged with 'dymos.static_target'. | N/A |

targets | unspecified | N/A | N/A | Targets in the ODE to which the state is connected | N/A |

units | unspecified | N/A | N/A | The units in which the parameter is defined. | N/A |

upper | N/A | N/A | ['Iterable', 'Number'] | The upper bound of the parameter. This option is invalid if opt=False. | N/A |

val | 0.0 | N/A | ['Iterable', 'ndarray', 'Number'] | The default value of the parameter in the phase. | N/A |

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.