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

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.

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, static_targets=unspecified)

Add a parameter (static control) to the trajectory.

Parameters:

namestr

Name of the parameter.

unitsstr or None or _unspecified

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

valfloat or ndarray

Default value of the parameter at all nodes.

descstr

A description of the parameter.

optbool

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

targetsdict or None

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.

lowerfloat or ndarray

The lower bound of the parameter value.

upperfloat or ndarray

The upper bound of the parameter value.

scalerfloat or ndarray

The scaler of the parameter value for the optimizer.

adderfloat or ndarray

The adder of the parameter value for the optimizer.

ref0float or ndarray

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

reffloat or ndarray

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

shapeSequence of int

The shape of the parameter.

dynamicbool

True 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 _unspecified

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

static_targetsbool or Sequence or _unspecified

True if ALL targets in the ODE are not shaped with num_nodes as the first dimension (meaning they cannot have a unique value at each node). If False, ALL targets are expected to be shaped with the first dimension as the number of nodes. If given as a Sequence, it provides those targets not shaped with num_nodes. If left _unspecified, static targets will be determined automatically.

set_parameter_val

Trajectory.set_parameter_val(name, val=None, units=None)

Set the parameter values.

Parameters:

namestr

Name of the variable. This should be a parameter variable.

valndarray or Sequence or None

Array of state values.

unitsstr, optional

The units of the state values specified. If None, use the units associated with the target. If provided, must be compatible with the target units.

add_phase

Trajectory.add_phase(name, phase, **kwargs)

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.

link_phases

Trajectory.link_phases(phases, vars=None, locs=('final', 'initial'), connected=False, units=unspecified, scaler=None, adder=None, ref0=None, ref=None, linear=False)

Specify that phases in the given sequence are to 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 str

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

varssequence of str

The variables in the phases to be linked, or ‘*’. Providing ‘*’ will link time and all states. Linking control values or rates requires them to be listed explicitly.

locstuple of str

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

connectedbool

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

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.

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.

See also

add_linkage_constraint

Explicitly add a single phase linkage constraint.

simulate

Trajectory.simulate(times_per_seg=unspecified, method=unspecified, atol=unspecified, rtol=unspecified, first_step=unspecified, max_step=unspecified, record_file=None, case_prefix=None, reset_iter_counts=True, reports=False, interpolant='cubic')

Simulate the Trajectory using scipy.integrate.solve_ivp.

Parameters:

times_per_segint or None

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

methodstr

The scipy.integrate.solve_ivp integration method.

atolfloat

Absolute convergence tolerance for scipy.integrate.solve_ivp.

rtolfloat

Relative convergence tolerance for scipy.integrate.solve_ivp.

first_stepfloat

Initial step size for the integration.

max_stepfloat

Maximum step size for the integration.

record_filestr or None

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.

case_prefixstr or None

Prefix to prepend to coordinates when recording.

reset_iter_countsbool

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

reportsbool or None or str or Sequence

Reports setting for the subproblems run under simualate.

interpolantstr

The interpolation method to be used for the controls in the simulation phase.

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.