Organizing Phases into Trajectories#

The majority of real-world use cases of optimal control involve complex trajectories that cannot be modeled with a single phase. For instance, different phases of a trajectory may have different equations of motion, different control parameterizations, or different path constraints. Phases are also necessary if the user wishes to impose intermediate constraints upon some variable, by imposing them as boundary constraints at a phase junction.

The Trajectory class in Dymos is intended to simplify the development of multi-phase problems. It serves as a Group which contains the various phases belonging to the trajectory, and it provides linkage constraints that dictate how phases are linked together. This enables trajectories that are not only a sequence of phases in time, but may include branching behavior, allowing us to do things like track/constrain the path of a jettisoned rocket stage.

It supports a get_values method similar to that of Phases that allows the user to retrieve the value of a variable within the trajectory. When verifying an answer with explicit simulation, the simulate method of Trajectory can simulate all of its member phases in parallel, providing a significant performance improvement for some cases.

Instantiating a Trajectory#

Instantiating a Trajectory is simple. Simply invoke Trajectory(). The trajectory object itself is an OpenMDAO Group which serves as a container for its constituent Phases.

  • phases An OpenMDAO Group or ParallelGroup holding the member phases

  • linkages A Dymos PhaseLinkageComp that manages all of the linkage constraints that dictate how the phases are connected.

Adding Phases#

Phases are added to a Trajectory using the add_phase method.

Trajectory.add_phase(name, phase, **kwargs)[source]

Add a phase to the trajectory.

Phases will be added to the Trajectory’s phases subgroup.

Parameters:
namestr

The name of the phase being added.

phasedymos Phase object

The Phase object to be added.

**kwargsdict

Additional arguments when adding the phase to the trajectory.

Returns:
PhaseBase

The Phase object added to the trajectory.

Defining Phase Linkages#

Having added phases to the Trajectory, they now exist as independent Groups within the OpenMDAO model. In order to enforce continuity among certain variables across phases, the user must declare which variables are to be continuous in value at each phase boundary. There are two methods in dymos which provide this functionality. The add_linkage_constraint method provides a very general way of coupling two phases together. It does so by generating a constraint of the following form:

(106)#\[\begin{align} c = \mathrm{sign}_a \mathrm{var}_a + \mathrm{sign}_b \mathrm{var}_b \end{align}\]

Method add_linkage_constraint lets the user specify the variables and phases to be compared for this constraint, as well as the location of the variable in each phase (either ‘initial’ or ‘final’) By default this method is setup to provide continuity in a variable between two phases:

  • the sign of variable a is +1 while the sign of variable b is -1.

  • the location of variable a is ‘final’ while the location of variable b is ‘initial’.

  • the default value of the constrained quantity is 0.0.

In this way, the default behavior constrains the final value of some variable in phase a to be the same as the initial value of some variable in phase b. Other values for these options can provide other functionality. For instance, to simulate a mass jettison, we could require that the initial value of mass in phase b be 1000 kg less than the value of mass at the end of phase a. Providing arguments equals = 1000, units='kg would achieve this.

Similarly, specifying other values for the locations of the variables in each phase can be used to ensure that two phases start or end at the same condition - such as the case in a branching trajectory or a rendezvous.

While add_linkage_constraint gives the user a powerful capability, providing simple state and time continuity across multiple phases would be a very verbose undertaking using this method. The link_phases method is intended to simplify this process. In the finite-burn orbit raising example, there are three phases: burn1, coast, burn2. This case is somewhat unusual in that the thrust acceleration is modeled as a state variable.
The acceleration needs to be zero in the coast phase, but continuous between burn1 and burn2, assuming no mass was jettisoned during the coast and that the thrust magnitude doesn’t change.

add_linkage_constraint#

Trajectory.add_linkage_constraint(phase_a, phase_b, var_a, var_b, loc_a='final', loc_b='initial', sign_a=unspecified, sign_b=unspecified, mult_a=unspecified, mult_b=unspecified, units=unspecified, lower=None, upper=None, equals=None, scaler=None, adder=None, ref0=None, ref=None, linear=False, connected=False)[source]

Explicitly add a single phase linkage constraint.

Phase linkage constraints are enforced by constraining the following equation:

mult_a * var_a + mult_b * var_b

The resulting value of this equation is constrained. This can satisfy ‘coupling’ or ‘linkage’ conditions across phase boundaries: enforcing continuity, common initial conditions, or common final conditions.

With default values, this equation can be used to enforce variable continuity at phase boundaries. For instance, constraining some variable x (either a state, control, parameter, or output of the ODE) to have the same value at the final point of phase ‘foo’ and the initial point of phase ‘bar’ is accomplished by:

` add_linkage_constraint('foo', 'bar', 'x', 'x') `

We may sometimes want two phases to have the same value of some variable at the start of each phase:

` add_linkage_constraint('foo', 'bar', 'x', 'x', loc_a='initial', loc_b='initial') `

(Here the specification of loc_b is unnecessary but helps in the clarity of whats going on.)

Or perhaps a phase has cyclic behavior. We may not know the exact value of some variable x at the start and end of the phase foo, but it must be the same value at each point.

` add_linkage_constraint('foo', 'foo', 'x', 'x') `

If lower, upper, and equals are all None, then dymos will use equals=0 by default. If the continuity condition is limited by some bounds instead, lower and upper can be used. For instance, perhaps the velocity (‘vel’) is allowed to have an impulsive change within a certain magnitude between two phases:

` add_linkage_constraint('foo', 'bar', 'vel', 'vel', lower=-100, upper=100, units='m/s') `

Parameters:
phase_astr

The first phase in the linkage constraint.

phase_bstr

The second phase in the linkage constraint.

var_astr

The linked variable from the first phase in the linkage constraint.

var_bstr

The linked variable from the second phase in the linkage constraint.

loc_astr

The location of the variable in the first phase of the linkage constraint (one of ‘initial’ or ‘final’).

loc_bstr

The location of the variable in the second phase of the linkage constraint (one of ‘initial’ or ‘final’).

sign_afloat

The multiplier applied to the variable from the first phase in the linkage constraint. This argument is deprecated in favor of mult_a.

sign_bfloat

The multiplier applied to the variable from the second phase in the linkage constraint. This argument is deprecated in favor of mult_b.

mult_afloat

The multiplier applied to the variable from the first phase in the linkage constraint.

mult_bfloat

The multiplier applied to the variable from the second phase in the linkage constraint.

unitsstr or None or _unspecified

Units of the linkage. If _unspecified, dymos will use the units from the variable in the first phase of the linkage. Units of the two specified variables must be compatible.

lowerfloat or array or None

The lower bound applied as a constraint on the linkage equation.

upperfloat or array or None

The upper bound applied as a constraint on the linkage equation.

equalsfloat or array or None

Specifies a targeted value for an equality constraint on the linkage equation.

scalerfloat or array or None

The scaler of the linkage constraint.

adderfloat or array or None

The adder of the linkage constraint.

ref0float or array or None

The zero-reference value of the linkage constraint.

reffloat or array or None

The unit-reference value of the linkage constraint.

linearbool

If True, treat this variable as a linear constraint, otherwise False. Linear constraints should only be applied if the variable on each end of the linkage is a design variable or a linear function of one.

connectedbool

If True, this constraint is enforced by direct connection rather than a constraint for the optimizer. This is only valid for states and time.

Trajectory-Level Parameters#

Often times, there are parameters which apply to the entirety of a trajectory that potentially need to be optimized. If we implemented these as parameters within each phase individually, we would need some constraints to ensure that they held the same value within each phase. To avoid this complexity, Dymos Trajectory objects support their own Parameters.

Like their Phase-based counterparts, Trajectory parameters may be design variables for the problem or they may be inputs to the trajectory from external sources.

When using Trajectory parameters, their values are connected to each phase as an Input Parameter within the Phase. Because ODEs in different phases may have different names for parameters (e.g. ‘mass’, ‘m’, ‘m_total’, etc) Dymos allows the user to specify the targeted ODE parameters on a phase-by-phase basis using the targets and target_params option. It can take on the following values.

  • If targets is None the trajectory parameter will be connected to the phase input parameter of the same name in each phase, if it exists (otherwise it is not connected to that phase).

  • Otherwise targets should be specified as a dictionary. And the behavior depends on the value associated with each phase name:

    • If the phase name is not in the given dictionary, attempt to connect to an existing parameter of the same name in that phase.

    • If the associated value is None, explicitly omit a connection to that phase.

    • If the associated value is a string, connect to an existing input parameter whose name is given by the string in that phase.

    • If the associated value is a Sequence, create an input parameter in that phase connected to the ODE targets given by the Sequence.

Explicit Simulation of Trajectories#

The simulate method on Trajectory is similar to that of the simulate method of Phases. When invoked, it will perform a simulation of each Phase in the trajectory.