Skip to content

The Trajectory API

class dymos.Trajectory

Class definition for a Trajectory group. A Trajectory object serves as a container for one or more Phases, as well as the linkage conditions between phases.


Public API Methods:

add_linkage_constraint(self, phase_a, phase_b, var_a, var_b, loc_a='final', loc_b='initial', sign_a=1.0, sign_b=-1.0, units=unspecified, lower=None, upper=None, equals=None, scaler=None, adder=None, ref0=None, ref=None, linear=False, connected=False)

Explicitly add a single phase linkage constraint.

Phase linkage constraints are enforced by constraining the following equation:

sign_a * var_a + sign_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')

Arguments:

phase_a: The first phase in the linkage constraint.

phase_b: The second phase in the linkage constraint.

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

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

loc_a: The location of the variable in the first phase of the linkage constraint (one of 'initial' or 'final').

loc_b: The location of the variable in the second phase of the linkage constraint (one of 'initial' or 'final').

sign_a: The sign applied to the variable from the first phase in the linkage constraint.

sign_b: The sign applied to the variable from the second phase in the linkage constraint.

units: 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.

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

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

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

scaler: The scaler of the linkage constraint.

adder: The adder of the linkage constraint.

ref0: The zero-reference value of the linkage constraint.

ref: The unit-reference value of the linkage constraint.

linear: 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.

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

add_parameter(self, name, units, val=unspecified, desc=unspecified, opt=False, targets=unspecified, custom_targets=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, shape=unspecified, dynamic=unspecified)

Add a parameter (static control) to the trajectory.

Arguments:

name: Name of the parameter.

units: Units in which the parameter is defined. If 0, use the units declared for the parameter in the ODE.

val: Default value of the parameter at all nodes.

desc: A description of the parameter.

opt: If True the value(s) of this parameter will be design variables in the optimization problem. The default is False.

targets: If None, then the parameter will be connected to the controllable parameter in the ODE of each phase. For each phase where no such controllable parameter exists, a warning will be issued. If targets is given as a dict, the dict should provide the relevant phase names as keys, each associated with the respective controllable parameter as a value.

custom_targets: By default, the parameter will be connect to the parameter/targets of the given name in each phase. This argument can be used to override that behavior on a phase by phase basis.

lower: The lower bound of the parameter value.

upper: The upper bound of the parameter value.

scaler: The scaler of the parameter value for the optimizer.

adder: The adder of the parameter value for the optimizer.

ref0: The zero-reference value of the parameter for the optimizer.

ref: The unit-reference value of the parameter for the optimizer.

shape: The shape of the parameter.

dynamic: True if the targets in the ODE may be dynamic (if the inputs are sized to the number of nodes) else False.

add_phase(self, name, phase, kwargs)**

Add a phase to the trajectory.

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

Arguments:

name: The name of the phase being added.

phase: The Phase object to be added.

**kwargs: Additional arguments when adding the phase to the trajectory.

link_phases(self, phases, vars=None, locs=('final', 'initial'), connected=False)

Specify that phases in the given sequence are to be assume continuity of the given variables.

This method caches the phase linkages, and may be called multiple times to express more complex behavior (branching phases, phases only continuous in some variables, etc).

The location at which the variables should be coupled in the two phases are provided with a two character string:

  • 'final' specifies the value at the end of the phase (at time t_initial + t_duration)
  • 'initial' specifies the value at the start of the phase (at time t_initial)

Arguments:

phases: The names of the phases in this trajectory to be sequentially linked.

vars: The variables in the phases to be linked, or ''. Providing '' will time and all states. Linking control values or rates requires them to be listed explicitly.

locs: A two-element tuple of the two-character location specification. For every pair in phases, the location specification refers to which location in the first phase is connected to which location in the second phase. If the user wishes to specify different locations for different phase pairings, those phase pairings must be made in separate calls to link_phases.

connected: Set to True to directly connect the phases being linked. Otherwise, create constraints for the optimizer to solve.

simulate(self, times_per_seg=10, method='RK45', atol=1e-09, rtol=1e-09, record_file=None)

Simulate the Trajectory using scipy.integrate.solve_ivp.

Arguments:

times_per_seg: Number of equally spaced times per segment at which output is requested. If None, output will be provided at all Nodes.

method: The scipy.integrate.solve_ivp integration method.

atol: Absolute convergence tolerance for scipy.integrate.solve_ivp.

rtol: Relative convergence tolerance for scipy.integrate.solve_ivp.

record_file: If a string, the file to which the result of the simulation will be saved. If None, no record of the simulation will be saved.