# The Trajectory API

## Contents

# The Trajectory API#

## add_linkage_constraint#

- Trajectory.add_linkage_constraint(
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)[source]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') ``

- Parameters

phase_astrThe first phase in the linkage constraint.

phase_bstrThe second phase in the linkage constraint.

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

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

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

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

sign_afloatThe sign applied to the variable from the first phase in the linkage constraint.

sign_bfloatThe sign applied to the variable from the second phase in the linkage constraint.

unitsstr or None or _unspecifiedUnits 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 NoneThe lower bound applied as a constraint on the linkage equation.

upperfloat or array or NoneThe upper bound applied as a constraint on the linkage equation.

equalsfloat or array or NoneSpecifies a targeted value for an equality constraint on the linkage equation.

scalerfloat or array or NoneThe scaler of the linkage constraint.

adderfloat or array or NoneThe adder of the linkage constraint.

ref0float or array or NoneThe zero-reference value of the linkage constraint.

reffloat or array or NoneThe unit-reference value of the linkage constraint.

linearboolIf 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.

connectedboolIf 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#

- Trajectory.add_parameter(
name,units=unspecified,val=unspecified,desc=unspecified,opt=False,targets=unspecified,lower=unspecified,upper=unspecified,scaler=unspecified,adder=unspecified,ref0=unspecified,ref=unspecified,shape=unspecified,dynamic=unspecified,static_target=unspecified)[source]Add a parameter (static control) to the trajectory.

- Parameters

namestrName of the parameter.

unitsstr or None or _unspecifiedUnits in which the parameter is defined. If _unspecified, use the units declared for the parameter in the ODE.

valfloat or ndarrayDefault value of the parameter at all nodes.

descstrA description of the parameter.

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

targetsdict or NoneIf 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.

lowerfloat or ndarrayThe lower bound of the parameter value.

upperfloat or ndarrayThe upper bound of the parameter value.

scalerfloat or ndarrayThe scaler of the parameter value for the optimizer.

adderfloat or ndarrayThe adder of the parameter value for the optimizer.

ref0float or ndarrayThe zero-reference value of the parameter for the optimizer.

reffloat or ndarrayThe unit-reference value of the parameter for the optimizer.

shapeSequence of intThe shape of the parameter.

dynamicboolTrue if the targets in the ODE may be dynamic (if the inputs are sized to the number of nodes) else False. This argument is deprecated in favor of static_target.

static_targetbool or _unspecifiedTrue if the targets in the ODE are not shaped with num_nodes as the first dimension (meaning they cannot have a unique value at each node). Otherwise False.

## add_phase#

- Trajectory.add_phase(
name,phase,**kwargs)[source]Add a phase to the trajectory.

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

- Parameters

namestrThe name of the phase being added.

phasedymos Phase objectThe Phase object to be added.

**kwargsdictAdditional arguments when adding the phase to the trajectory.

- Returns

- PhaseBase
The Phase object added to the trajectory.

## link_phases#

- Trajectory.link_phases(
phases,vars=None,locs=('final', 'initial'),connected=False)[source]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 one of two strings:

‘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)

- Parameters

phasessequence of strThe names of the phases in this trajectory to be sequentially linked.

varssequence of strThe 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.

locstuple of strA two-element tuple of a 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.

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

See also

`add_linkage_constraint`

Explicitly add a single phase linkage constraint.

## simulate#

- Trajectory.simulate(
times_per_seg=10,method=unspecified,atol=unspecified,rtol=unspecified,first_step=unspecified,max_step=unspecified,record_file=None,case_prefix=None,reset_iter_counts=True,reports=False)[source]Simulate the Trajectory using scipy.integrate.solve_ivp.

- Parameters

times_per_segint or NoneNumber of equally spaced times per segment at which output is requested. If None, output will be provided at all Nodes.

methodstrThe scipy.integrate.solve_ivp integration method.

atolfloatAbsolute convergence tolerance for scipy.integrate.solve_ivp.

rtolfloatRelative convergence tolerance for scipy.integrate.solve_ivp.

first_stepfloatInitial step size for the integration.

max_stepfloatMaximum step size for the integration.

record_filestr or NoneIf a string, the file to which the result of the simulation will be saved. If None, no record of the simulation will be saved.

case_prefixstr or NonePrefix to prepend to coordinates when recording.

reset_iter_countsboolIf True and model has been run previously, reset all iteration counters.

reportsbool or None or str or SequenceReports setting for the subproblems run under simualate.

- Returns

- problem
An OpenMDAO Problem in which the simulation is implemented. This Problem interface can be interrogated to obtain timeseries outputs in the same manner as other Phases to obtain results at the requested times.