Phase Options#
Phase.options#
General options available to all dymos Phases.
| Option | Default | Acceptable Values | Acceptable Types | Description |
|---|---|---|---|---|
| assembled_jac_type | csc | ['csc', 'dense'] | N/A | Linear solver(s) in this group or implicit component, if using an assembled jacobian, will use this type. |
| auto_order | False | [True, False] | ['bool'] | If True the order of subsystems is determined automatically based on the dependency graph. It will not break or reorder cycles. |
| auto_solvers | True | [True, False] | ['bool'] | If True, attempt to automatically assign solvers if necessary. |
| control_options | {} | N/A | ['dict'] | Options for each control in this phase. |
| ode_class | N/A | N/A | N/A | System defining the ODE |
| ode_init_kwargs | {} | N/A | ['dict'] | Keyword arguments provided when initializing the ODE System |
| parameter_options | {} | N/A | ['dict'] | Options for each parameter in this phase. |
| state_options | {} | N/A | ['dict'] | Options for each state in this phase. |
| time_options | ======================= ============ ================= ================ ======================== 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_opti {} N/A N/A options dictionary for ons 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 ======================= ============ ================= ================ ======================== | N/A | ['TimeOptionsDictionary'] | Options for time in this phase. |
| transcription | **Required** | N/A | ['TranscriptionBase'] | Transcription technique of the optimal control problem. |
The transcription is an instance of one of the transcriptions available in Dymos.
Other options listed below control the behavior of various aspects of Phases.
While most have corresponding phase methods for setting these values, users may now use the set method of OpenMDAO’s OptionsDictionary to set the values of these options.
Phase.timeseries_options#
These options control the behavior of timeseries within a Phase.
| Option | Default | Acceptable Values | Acceptable Types | Description |
|---|---|---|---|---|
| include_control_rates | False | [True, False] | ['bool'] | If True, include control rates in the timeseries outputs by default. |
| include_parameters | False | [True, False] | ['bool'] | If True, include the parameters in the timeseries outputs by default. |
| include_state_rates | False | [True, False] | ['bool'] | If True, include state rates in the timeseries outputs by default. |
| include_t_phase | False | [True, False] | ['bool'] | If True, include the elapsed phase time in the timeseries outputs by default. |
| use_prefix | False | [True, False] | ['bool'] | If True, prefix the timeseries variable output with the type of variable (this is legacy behavior that changed in Dymos 1.8.0) |
Phase.refine_options#
These options control grid refinement within each Phase.
| Option | Default | Acceptable Values | Acceptable Types | Description |
|---|---|---|---|---|
| max_order | 14 | N/A | ['int'] | Maximum transcription order for segments in this phase. |
| min_order | 3 | N/A | ['int'] | Minimum transcription order for segments in this phase. |
| refine | True | [True, False] | ['bool'] | If True, this Phase may be refined during the grid refinement procedure. |
| smoothness_factor | 1.2 | N/A | ['float'] | Maximum allowed ratio of state second derivatives across refinement iterations |
| tolerance | 0.0001 | N/A | ['float'] | Default tolerance for grid refinement in this phase. |
Phase.simulate_options#
These options control the behavior of phase explicit simulation.
| Option | Default | Acceptable Values | Acceptable Types | Description |
|---|---|---|---|---|
| atol | 1e-06 | N/A | ['float', 'array'] | Absolute error tolerance for variable step integration. |
| first_step | N/A | N/A | ['float'] | Initial step size, or None if the algorithm should choose. |
| max_step | inf | N/A | ['float'] | Maximum allowable step size |
| method | DOP853 | ['RK23', 'RK45', 'DOP853', 'BDF', 'Radau', 'LSODA'] | N/A | The method used by simulate to propagate the ODE. |
| rtol | 0.001 | N/A | ['float', 'array'] | Relative error tolerance for variable step integration. |
| times_per_seg | 10 | N/A | ['int'] | The default number of output times per segment for Phase.simulate.If None, and not provided as an argument to simulate, use thesame grid as the Phase transcription. |
Phase Methods#
set_time_options#
- Phase.set_time_options(units=unspecified, fix_initial=unspecified, fix_duration=unspecified, input_initial=unspecified, input_duration=unspecified, initial_val=unspecified, initial_bounds=unspecified, initial_scaler=unspecified, initial_adder=unspecified, initial_ref0=unspecified, initial_ref=unspecified, duration_val=unspecified, duration_bounds=unspecified, duration_scaler=unspecified, duration_adder=unspecified, duration_ref0=unspecified, duration_ref=unspecified, targets=unspecified, time_phase_targets=unspecified, t_initial_targets=unspecified, t_duration_targets=unspecified, name=unspecified)[source]
Sets options for time in the phase.
Only those options which are specified in the arguments will be updated.
- Parameters:
- unitsstr
The default units for time variables in the phase. Default is ‘s’.
- fix_initialbool
If True, the initial time of the phase is not treated as a design variable for the optimization problem.
- fix_durationbool
If True, the duration of the phase is not treated as a design variable for the optimization problem.
- input_initialbool
If True, the user is expected to link phase.t_initial to an external output source. Providing input_initial=True makes all initial time optimization settings irrelevant.
- input_durationbool
If True, the user is expected to link phase.t_duration to an external output source. Providing input_duration=True makes all time duration optimization settings irrelevant.
- initial_valfloat
Default value of the time at the start of the phase.
- initial_boundsiterable of (float, float)
The bounds (lower, upper) for time at the start of the phase.
- initial_scalerfloat
Scalar for the initial value of time.
- initial_adderfloat
Adder for the initial value of time.
- initial_ref0float
Zero-reference for the initial value of time.
- initial_reffloat
Unit-reference for the initial value of time.
- duration_valfloat
Default value for the time duration of the phase.
- duration_boundsiterable of (float, float)
The bounds (lower, upper) for the time duration of the phase.
- duration_scalerfloat
Scaler for phase time duration.
- duration_adderfloat
Adder for phase time duration.
- duration_ref0float
Zero-reference for phase time duration.
- duration_reffloat
Unit-reference for phase time duration.
- targetsiterable of str
Targets in the ODE for the value of current time.
- time_phase_targetsiterable of str
Targets in the ODE for the value of current phase elapsed time.
- t_initial_targetsiterable of str
Targets in the ODE for the value of phase initial time.
- t_duration_targetsiterable of str
Targets in the ODE for the value of phase time duration.
- namestr
Name of the integration variable for this phase. Default is ‘time’.
set_time_val#
- Phase.set_time_val(initial=None, duration=None, units=None)[source]
Set the values for initial time and the duration of the phase.
- Parameters:
- initialfloat or None
Value for the initial time.
- durationfloat or None
Value for the phase duration.
- unitsstr or None
Units of the time. If none are specified, the default units are used.
add_state#
- Phase.add_state(name, units=unspecified, shape=unspecified, rate_source=unspecified, targets=unspecified, val=unspecified, fix_initial=unspecified, fix_final=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, defect_scaler=unspecified, defect_ref=unspecified, continuity_scaler=unspecified, continuity_ref=unspecified, solve_segments=unspecified, connected_initial=unspecified, source=unspecified, input_initial=unspecified, initial_targets=unspecified, opt=unspecified, initial_bounds=unspecified, final_bounds=unspecified)[source]
Add a state variable to be integrated by the phase.
- Parameters:
- namestr
Name of the state variable in the RHS.
- unitsstr or None
Units in which the state variable is defined. Internally components may use different units for the state variable, but the IndepVarComp which provides its value will provide it in these units, and collocation defects will use these units. If units is not specified here then the unit will be determined from the rate_source.
- shapetuple of int
The shape of the state variable. For instance, a 3D cartesian position vector would have a shape of (3,). This only needs to be specified if the rate_source target points to a control or state whose shape isn’t known in time.
- rate_sourcestr
The path to the ODE output which provides the rate of this state variable.
- targetsstr or Sequence of str
The path to the targets of the state variable in the ODE system. If given this will override the value given by the @declare_state decorator on the ODE. In the future, if left _unspecified (the default), the phase variable will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- valndarray
The default value of the state at the state discretization nodes of the phase.
- fix_initialbool(False)
If True, omit the first value of the state from the design variables (prevent the optimizer from changing it).
- fix_finalbool(False)
If True, omit the final value of the state from the design variables (prevent the optimizer from changing it).
- lowerfloat or ndarray or None (None)
The lower bound of the state at the nodes of the phase.
- upperfloat or ndarray or None (None)
The upper bound of the state at the nodes of the phase.
- scalerfloat or ndarray or None (None)
The scaler of the state value at the nodes of the phase.
- adderfloat or ndarray or None (None)
The adder of the state value at the nodes of the phase.
- ref0float or ndarray or None (None)
The zero-reference value of the state at the nodes of the phase.
- reffloat or ndarray or None (None)
The unit-reference value of the state at the nodes of the phase.
- defect_scalerfloat or ndarray
The scaler of the state defect at the collocation nodes of the phase.
- defect_reffloat or ndarray
The unit-reference value of the state defect at the collocation nodes of the phase. If provided, this value overrides defect_scaler.
- continuity_scalerfloat
Constraint scaler used to enforce the continuity mismatch defect between segments when transcription is not compressed.
- continuity_reffloat
Reference unit value of the continuity mismatch defect between segments when transcription is not compressed. Used in place of scaler.
- solve_segmentsbool(False)
If True, a solver will be used to converge the collocation defects within a segment. Note that the state continuity defects between segements will still be handled by the optimizer.
- connected_initialbool
If True, then the initial value for this state comes from an externally connected source. Deprecated - use input_initial.
- sourcestr
The path to the ODE output which provides the solution for this state variable when using an Analytic transcription.
- input_initialbool
If True, then the initial value for this state comes is an input.
- initial_targetsstr
The path to the ODE inputs to which the initial value of this state should be connected.
- optbool
If True, state values are fixed at the input values and the optimizer resolves defect constraints by varying the other design variables in the phase.
- initial_boundstuple
The bounds (lower, upper) of the state variable at the initial point in the phase.
- final_boundstuple
The bounds (lower, upper) of the state variable at the final point in the phase.
set_state_options#
- Phase.set_state_options(name, units=unspecified, shape=unspecified, rate_source=unspecified, targets=unspecified, val=unspecified, fix_initial=unspecified, fix_final=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, defect_scaler=unspecified, defect_ref=unspecified, continuity_scaler=unspecified, continuity_ref=unspecified, solve_segments=unspecified, connected_initial=unspecified, source=unspecified, input_initial=unspecified, initial_targets=unspecified, opt=unspecified, initial_bounds=unspecified, final_bounds=unspecified)[source]
Set options that apply the EOM state variable of the given name.
- Parameters:
- namestr
Name of the state variable in the RHS.
- unitsstr or None
Units in which the state variable is defined. Internally components may use different units for the state variable, but the IndepVarComp which provides its value will provide it in these units, and collocation defects will use these units. If units is not specified here then the unit will be determined from the rate_source.
- shapetuple of int
The shape of the state variable. For instance, a 3D cartesian position vector would have a shape of (3,). This only needs to be specified if the rate_source target points to a control or state whose shape isn’t known in time.
- rate_sourcestr
The path to the ODE output which provides the rate of this state variable.
- targetsstr or Sequence of str
The path to the targets of the state variable in the ODE system. If given this will override the value given by the @declare_state decorator on the ODE. In the future, if left _unspecified (the default), the phase variable will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- valndarray
The default value of the state at the state discretization nodes of the phase.
- fix_initialbool(False)
If True, omit the first value of the state from the design variables (prevent the optimizer from changing it).
- fix_finalbool(False)
If True, omit the final value of the state from the design variables (prevent the optimizer from changing it).
- lowerfloat or ndarray or None (None)
The lower bound of the state at the nodes of the phase.
- upperfloat or ndarray or None (None)
The upper bound of the state at the nodes of the phase.
- scalerfloat or ndarray or None (None)
The scaler of the state value at the nodes of the phase.
- adderfloat or ndarray or None (None)
The adder of the state value at the nodes of the phase.
- ref0float or ndarray or None (None)
The zero-reference value of the state at the nodes of the phase.
- reffloat or ndarray or None (None)
The unit-reference value of the state at the nodes of the phase.
- defect_scalerfloat or ndarray
The scaler of the state defect at the collocation nodes of the phase.
- defect_reffloat or ndarray
The unit-reference value of the state defect at the collocation nodes of the phase. If provided, this value overrides defect_scaler.
- continuity_scalerfloat
Constraint scaler used to enforce the continuity mismatch defect between segments when transcription is not compressed.
- continuity_reffloat
Reference unit value of the continuity mismatch defect between segments when transcription is not compressed. Used in place of scaler.
- solve_segmentsbool(False)
If True, a solver will be used to converge the collocation defects within a segment. Note that the state continuity defects between segements will still be handled by the optimizer.
- connected_initialbool
If True, then the initial value for this state comes from an externally connected source. Deprecated - use input_initial.
- sourcestr
The path to the ODE output which provides the solution for this state variable when using an Analytic transcription.
- input_initialbool
If True, then the initial value for this state comes is an input.
- initial_targetsstr or Sequence of str
The path to the ODE inputs to which the initial value of this state should be connected.
- optbool
If True, state values are fixed at the input values and the optimizer resolves defect constraints by varying the other design variables in the phase.
- initial_boundstuple
The bounds (lower, upper) of the state variable at the initial point in the phase.
- final_boundstuple
The bounds (lower, upper) of the state variable at the final point in the phase.
set_state_val#
- Phase.set_state_val(name, vals=None, time_vals=None, units=None, interpolation_kind='linear')[source]
Set the necessary input values for state as appropriate for the specified transcription.
- Parameters:
- namestr
Name of the variable. This should be a state variable.
- valsndarray or Sequence or float or None
Array of state values.
- time_valsndarray or Sequence or None
Array of integration variable 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.
- interpolation_kindstr
Specifies the kind of interpolation, as per the scipy.interpolate package. One of (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’ where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
add_control#
- Phase.add_control(name, order=unspecified, units=unspecified, desc=unspecified, opt=unspecified, fix_initial=unspecified, fix_final=unspecified, targets=unspecified, rate_targets=unspecified, rate2_targets=unspecified, val=unspecified, shape=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, continuity=unspecified, continuity_scaler=unspecified, continuity_ref=unspecified, rate_continuity=unspecified, rate_continuity_scaler=unspecified, rate_continuity_ref=unspecified, rate2_continuity=unspecified, rate2_continuity_scaler=unspecified, rate2_continuity_ref=unspecified, control_type=unspecified)[source]
Adds a dynamic control variable to be tied to a parameter in the ODE.
- Parameters:
- namestr
The name assigned to the control variable. If the ODE has been decorated with parameters, this should be the name of a control in the system.
- orderint
The order of the polynomial control variable. This option is invalid if control_type is ‘full’.
- unitsstr or None
The units with which the control parameter in this phase will be defined. It must be compatible with the units of the targets to which the control is connected.
- descstr
A description of the control variable.
- optbool
If True, the control value will be a design variable for the optimization problem. If False, allow the control to be connected externally.
- fix_initialbool
If True, the initial value of this control is fixed and not a design variable. This option is invalid if opt=False.
- fix_finalbool
If True, the final value of this control is fixed and not a design variable. This option is invalid if opt=False.
- targetsSequence of str or None
Targets in the ODE to which this control is connected. In the future, if left _unspecified (the default), the phase control will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- rate_targetsSequence of str or None
The targets in the ODE to which the control rate is connected.
- rate2_targetsSequence of str or None
The parameter in the ODE to which the control 2nd derivative is connected.
- valfloat
The default value of the control variable at the control input nodes.
- shapeSequence of int
The shape of the control variable at each point in time. Only needed for controls that don’t have a target in the ode.
- lowerSequence of Number or None
The lower bound of the control variable at the nodes. This option is invalid if opt=False.
- upperSequence or Number or None
The upper bound of the control variable at the nodes. This option is invalid if opt=False.
- scalerfloat or None
The scaler of the control variable at the nodes. This option is invalid if opt=False.
- adderfloat or None
The adder of the control variable at the nodes. This option is invalid if opt=False.
- ref0float or None
The zero-reference value of the control variable at the nodes. This option is invalid if opt=False.
- reffloat or None
The unit-reference value of the control variable at the nodes. This option is invalid if opt=False.
- continuitybool
Enforce continuity of control values at segment boundaries. This option is invalid if opt=False.
- continuity_scalerbool
Scaler of the continuity constraint. This option is invalid if opt=False. This option is only relevant in the Radau pseudospectral transcription where the continuity constraint is nonlinear. For Gauss-Lobatto the continuity constraint is linear.
- continuity_refbool
Reference unit value to be used in place of continuity scaler.
- rate_continuitybool
Enforce continuity of control first derivatives (in dimensionless time) at segment boundaries. This option is invalid if opt=False.
- rate_continuity_scalerfloat
Scaler of the rate continuity constraint at segment boundaries. This option is invalid if opt=False.
- rate_continuity_reffloat or None
Reference unit value of the rate continuity constraint at segment boundaries, for use in place of rate_continuity_scaler.
- rate2_continuitybool or None
Enforce continuity of control second derivatives at segment boundaries. This option is invalid if opt=False.
- rate2_continuity_scalerfloat or None
Scaler of the dimensionless rate continuity constraint at segment boundaries. This option is invalid if opt=False.
- rate2_continuity_reffloat or None
Reference unit value of the rate2 continuity constraint at segment boundaries, for use in place of rate_continuity_scaler.
- control_typestr
The type of control variable. Valid options include ‘full’ and ‘polynomial’.
Notes
rate and rate2 continuity are not enforced for input controls.
set_control_options#
- Phase.set_control_options(name, order=unspecified, units=unspecified, desc=unspecified, opt=unspecified, fix_initial=unspecified, fix_final=unspecified, targets=unspecified, rate_targets=unspecified, rate2_targets=unspecified, val=unspecified, shape=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, continuity=unspecified, continuity_scaler=unspecified, continuity_ref=unspecified, rate_continuity=unspecified, rate_continuity_scaler=unspecified, rate_continuity_ref=unspecified, rate2_continuity=unspecified, rate2_continuity_scaler=unspecified, rate2_continuity_ref=unspecified, control_type=unspecified)[source]
Set options on an existing dynamic control variable in the phase.
- Parameters:
- namestr
The name assigned to the control variable. If the ODE has been decorated with parameters, this should be the name of a control in the system.
- orderint
The order of the polynomial control variable. This option is invalid if control_type is ‘full’.
- unitsstr or None
The units with which the control parameter in this phase will be defined. It must be compatible with the units of the targets to which the control is connected.
- descstr
A description of the control variable.
- optbool
If True, the control value will be a design variable for the optimization problem. If False, allow the control to be connected externally.
- fix_initialbool
If True, the initial value of this control is fixed and not a design variable. This option is invalid if opt=False.
- fix_finalbool
If True, the final value of this control is fixed and not a design variable. This option is invalid if opt=False.
- targetsSequence of str or None
Targets in the ODE to which this control is connected. In the future, if left _unspecified (the default), the phase control will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- rate_targetsSequence of str or None
The targets in the ODE to which the control rate is connected.
- rate2_targetsSequence of str or None
The parameter in the ODE to which the control 2nd derivative is connected.
- valfloat
The default value of the control variable at the control input nodes.
- shapeSequence of int
The shape of the control variable at each point in time. Only needed for controls that don’t have a target in the ode.
- lowerSequence of Number or None
The lower bound of the control variable at the nodes. This option is invalid if opt=False.
- upperSequence or Number or None
The upper bound of the control variable at the nodes. This option is invalid if opt=False.
- scalerfloat or None
The scaler of the control variable at the nodes. This option is invalid if opt=False.
- adderfloat or None
The adder of the control variable at the nodes. This option is invalid if opt=False.
- ref0float or None
The zero-reference value of the control variable at the nodes. This option is invalid if opt=False.
- reffloat or None
The unit-reference value of the control variable at the nodes. This option is invalid if opt=False.
- continuitybool
Enforce continuity of control values at segment boundaries. This option is invalid if opt=False.
- continuity_scalerbool
Scaler of the continuity constraint. This option is invalid if opt=False. This option is only relevant in the Radau pseudospectral transcription where the continuity constraint is nonlinear. For Gauss-Lobatto the continuity constraint is linear.
- continuity_refbool
Reference unit value to be used in place of continuity scaler.
- rate_continuitybool
Enforce continuity of control first derivatives (in dimensionless time) at segment boundaries. This option is invalid if opt=False.
- rate_continuity_scalerfloat
Scaler of the rate continuity constraint at segment boundaries. This option is invalid if opt=False.
- rate_continuity_reffloat or None
Reference unit value of the rate continuity constraint at segment boundaries, for use in place of rate_continuity_scaler.
- rate2_continuitybool or None
Enforce continuity of control second derivatives at segment boundaries. This option is invalid if opt=False.
- rate2_continuity_scalerfloat or None
Scaler of the dimensionless rate continuity constraint at segment boundaries. This option is invalid if opt=False.
- rate2_continuity_reffloat or None
Reference unit value of the rate2 continuity constraint at segment boundaries, for use in place of rate_continuity_scaler.
- control_typestr
The type of control variable. Valid options include ‘full’ and ‘polynomial’.
Notes
rate and rate2 continuity are not enforced for input controls.
set_control_val#
- Phase.set_control_val(name, vals=None, time_vals=None, units=None, interpolation_kind='linear')[source]
Set the control values as appropriate.
- Parameters:
- namestr
Name of the variable. This should be a control variable.
- valsndarray or Sequence or None
Array of state values.
- time_valsndarray or Sequence or None
Array of integration variable 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.
- interpolation_kindstr
Specifies the kind of interpolation, as per the scipy.interpolate package. One of (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’ where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
add_polynomial_control#
- Phase.add_polynomial_control(name, order, desc=unspecified, val=unspecified, units=unspecified, opt=unspecified, fix_initial=unspecified, fix_final=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, targets=unspecified, rate_targets=unspecified, rate2_targets=unspecified, shape=unspecified)[source]
Adds a polynomial control variable to be tied to a parameter in the ODE.
Polynomial controls are defined by values at the Legendre-Gauss-Lobatto nodes of a single polynomial, defined on [-1, 1] in phase tau space.
For a polynomial control of a given order, the number of nodes used to define the polynomial is (order + 1).
- Parameters:
- namestr
Name of the controllable parameter in the ODE.
- orderint
The order of the interpolating polynomial used to represent the control value in phase tau space.
- descstr
A description of the polynomial control.
- valfloat or ndarray
Default value of the control at all nodes. If val scalar and the control is dynamic it will be broadcast.
- unitsstr or None or 0
Units in which the control variable is defined. If 0, use the units declared for the parameter in the ODE.
- optbool
If True (default) the value(s) of this control will be design variables in the optimization problem, in the path ‘phase_name.indep_controls.controls:control_name’. If False, the values of this control will exist as input controls:{name}.
- fix_initialbool
If True, the given initial value of the polynomial control is not a design variable and will not be changed during the optimization.
- fix_finalbool
If True, the given final value of the polynomial control is not a design variable and will not be changed during the optimization.
- lowerfloat or ndarray
The lower bound of the control at the nodes of the phase.
- upperfloat or ndarray
The upper bound of the control at the nodes of the phase.
- scalerfloat or ndarray
The scaler of the control value at the nodes of the phase.
- adderfloat or ndarray
The adder of the control value at the nodes of the phase.
- ref0float or ndarray
The zero-reference value of the control at the nodes of the phase.
- reffloat or ndarray
The unit-reference value of the control at the nodes of the phase.
- targetsSequence of str or None
Targets in the ODE to which this polynomial control is connected.
- rate_targetsNone or str
The name of the parameter in the ODE to which the first time-derivative of the control value is connected.
- rate2_targetsNone or str
The name of the parameter in the ODE to which the second time-derivative of the control value is connected.
- shapeSequence of int
The shape of the control variable at each point in time.
set_polynomial_control_options#
- Phase.set_polynomial_control_options(name, order=unspecified, desc=unspecified, val=unspecified, units=unspecified, opt=unspecified, fix_initial=unspecified, fix_final=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, targets=unspecified, rate_targets=unspecified, rate2_targets=unspecified, shape=unspecified)[source]
Set options on an existing polynomial control variable in the phase.
- Parameters:
- namestr
Name of the controllable parameter in the ODE.
- orderint
The order of the interpolating polynomial used to represent the control value in phase tau space.
- descstr
A description of the polynomial control.
- valfloat or ndarray
Default value of the control at all nodes. If val scalar and the control is dynamic it will be broadcast.
- unitsstr or None or 0
Units in which the control variable is defined. If 0, use the units declared for the parameter in the ODE.
- optbool
If True (default) the value(s) of this control will be design variables in the optimization problem, in the path ‘phase_name.indep_controls.controls:control_name’. If False, the values of this control will exist as input controls:{name}.
- fix_initialbool
If True, the given initial value of the polynomial control is not a design variable and will not be changed during the optimization.
- fix_finalbool
If True, the given final value of the polynomial control is not a design variable and will not be changed during the optimization.
- lowerfloat or ndarray
The lower bound of the control at the nodes of the phase.
- upperfloat or ndarray
The upper bound of the control at the nodes of the phase.
- scalerfloat or ndarray
The scaler of the control value at the nodes of the phase.
- adderfloat or ndarray
The adder of the control value at the nodes of the phase.
- ref0float or ndarray
The zero-reference value of the control at the nodes of the phase.
- reffloat or ndarray
The unit-reference value of the control at the nodes of the phase.
- targetsSequence of str or None
Targets in the ODE to which this polynomial control is connected.
- rate_targetsNone or str
The name of the parameter in the ODE to which the first time-derivative of the control value is connected.
- rate2_targetsNone or str
The name of the parameter in the ODE to which the second time-derivative of the control value is connected.
- shapeSequence of int
The shape of the control variable at each point in time.
set_polynomial_control_val#
- Phase.set_polynomial_control_val(name, vals=None, time_vals=None, units=None, interpolation_kind='linear')[source]
Set the polynomial control values as appropriate.
- Parameters:
- namestr
Name of the variable. This should be a polynomial control variable.
- valsndarray or Sequence or None
Array of state values.
- time_valsndarray or Sequence or None
Array of integration variable 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.
- interpolation_kindstr
Specifies the kind of interpolation, as per the scipy.interpolate package. One of (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’ where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
add_parameter#
- Phase.add_parameter(name, val=unspecified, units=unspecified, opt=False, desc=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, targets=unspecified, shape=unspecified, dynamic=unspecified, static_target=unspecified, include_timeseries=unspecified, static_targets=unspecified)[source]
Add a parameter (static control variable) to the phase.
- Parameters:
- namestr
Name of the parameter.
- valfloat or ndarray
Default value of the parameter at all nodes.
- unitsstr or None or 0
Units in which the parameter is defined. If 0, use the units declared for the parameter in the ODE.
- optbool
If True, the value(s) of this parameter will be design variables in the optimization problem, in the path ‘phase_name.indep_controls.controls:control_name’. If False (default), the this parameter will still be owned by an IndepVarComp in the phase, but it will not be a design variable in the optimization.
- descstr
A description of the parameter.
- 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.
- targetsSequence of str or None
Targets in the ODE to which this parameter is connected. In the future, if left _unspecified (the default), the phase parameter will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- 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.
- 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.
- include_timeseriesbool
True if the static parameters should be included in output timeseries, else 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_options#
- Phase.set_parameter_options(name, val=unspecified, units=unspecified, opt=False, desc=unspecified, lower=unspecified, upper=unspecified, scaler=unspecified, adder=unspecified, ref0=unspecified, ref=unspecified, targets=unspecified, shape=unspecified, dynamic=unspecified, static_target=unspecified, include_timeseries=unspecified, static_targets=unspecified)[source]
Set options for an existing parameter (static control variable) in the phase.
- Parameters:
- namestr
Name of the parameter.
- valfloat or ndarray
Default value of the parameter at all nodes.
- unitsstr or None or 0
Units in which the parameter is defined. If 0, use the units declared for the parameter in the ODE.
- optbool
If True the value(s) of this parameter will be design variables in the optimization problem, in the path ‘phase_name.indep_controls.controls:control_name’. If False (default), the this parameter will still be owned by an IndepVarComp in the phase, but it will not be a design variable in the optimization.
- descstr
A description of the parameter.
- 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.
- targetsSequence of str or None
Targets in the ODE to which this parameter is connected. In the future, if left _unspecified (the default), the phase parameter will try to connect to an ODE input of the same name. Set targets to None to prevent this.
- 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 option is deprecated.
- 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.
- include_timeseriesbool
True if the static parameters should be included in output timeseries, else 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#
- Phase.set_parameter_val(name, val=None, units=None)[source]
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_timeseries#
- Phase.add_timeseries(name, transcription, subset='all')[source]
Adds a new timeseries output upon which outputs can be provided.
- Parameters:
- namestr
A name for the timeseries output path.
- transcriptionstr
A transcription object which provides a grid upon which the outputs of the timeseries are provided.
- subsetstr
The name of the node subset in the given transcription at which outputs are to be provided.
add_timeseries_output#
- Phase.add_timeseries_output(name, output_name=None, units=unspecified, shape=unspecified, timeseries='timeseries', **kwargs)[source]
Add a variable to the timeseries outputs of the phase.
If name is given as an expression, this expression will be passed to an OpenMDAO ExecComp and the result computed and stored in the timeseries output under the variable name to the left of the equal sign.
- Parameters:
- namestr, or list of str
The name(s) of the variable to be used as a timeseries output, or a mathematical expression to be used as a timeseries output. If a name, it must be one of the integration variable, the phase-relative value of the integration variable (e.g. ‘time_phase’, one of the states, controls, control rates, or parameters, in the phase, the path to an output variable in the ODE, or a glob pattern matching some outputs in the ODE.
- output_namestr or None or list or dict
The name of the variable as listed in the phase timeseries outputs. By default this is the last element in name when split by dots. The user may override the timeseries name if splitting the path causes name collisions.
- unitsstr or None or _unspecified
The units to express the timeseries output. If None, use the units associated with the target. If provided, must be compatible with the target units. If a list of names is provided, units can be a matching list or dictionary.
- shapetuple or _unspecified
The shape of the timeseries output variable. This must be provided (if not scalar) since Dymos doesn’t necessarily know the shape of ODE outputs until setup time.
- timeseriesstr or None
The name of the timeseries to which the output is being added.
- **kwargs
Additional arguments passed to the exec comp.
add_boundary_constraint#
- Phase.add_boundary_constraint(name, loc, constraint_name=None, units=None, shape=None, indices=None, lower=None, upper=None, equals=None, scaler=None, adder=None, ref=None, ref0=None, linear=False, flat_indices=False)[source]
Add a boundary constraint to a variable in the phase.
- Parameters:
- namestr
Name of the variable to constrain. May also provide an expression to be evaluated and constrained. If a single variable and the name is not a state, control, or ‘time’, then this is assumed to be the path of the variable to be constrained in the ODE. If an expression, it must be provided in the form of an equation with a left- and right-hand side.
- locstr
The location of the boundary constraint (‘initial’ or ‘final’).
- constraint_namestr or None
- The name of the boundary constraint. By default, this is ‘var_constraint’ if name is a single variable,
or the left-hand side of the equation if name is an expression.
- unitsstr or None
The units in which the boundary constraint is to be applied. If None, use the units associated with the constrained output. If provided, must be compatible with the variables units.
- shapetuple, list, ndarray, or None
The shape of the variable being boundary-constrained. This can be inferred automatically for time, states, controls, and parameters, but is required if the constrained variable is an output of the ODE system.
- indicestuple, list, ndarray, slice, or None
The indices of the output variable to be boundary constrained at either the initial or final time in the phase. When the variable is multi-dimensional, this should be a list of lists, one for each dimension, containing the indices to be constrained. Note the behavior of indices changes depending on the value of the flat_indices option.
- lowerfloat or ndarray, optional
Lower boundary for the variable.
- upperfloat or ndarray, optional
Upper boundary for the variable.
- equalsfloat or ndarray, optional
Equality constraint value for the variable.
- scalerfloat or ndarray, optional
Value to multiply the model value to get the scaled value. Scaler is second in precedence.
- adderfloat or ndarray, optional
Value to add to the model value to get the scaled value. Adder is first in precedence.
- reffloat or ndarray, optional
Value of response variable that scales to 1.0 in the driver.
- ref0float or ndarray, optional
Value of response variable that scales to 0.0 in the driver.
- linearbool
Set to True if constraint is linear. Setting this to True when the constraint is not a linear function of the design variables will result in a failure of the optimization.
- flat_indicesbool
If True, treat indices as flattened C-ordered indices of elements to constrain. Otherwise, indices should be a tuple or list giving the elements to constrain at each point in time.
add_path_constraint#
- Phase.add_path_constraint(name, constraint_name=None, units=None, shape=None, indices=None, lower=None, upper=None, equals=None, scaler=None, adder=None, ref=None, ref0=None, linear=False, flat_indices=False)[source]
Add a path constraint to a variable in the phase.
- Parameters:
- namestr
Name of the variable to constrain. May also provide an expression to be evaluated and constrained. If a single variable and the name is not a state, control, or ‘time’, then this is assumed to be the path of the variable to be constrained in the ODE. If an expression, it must be provided in the form of an equation with a left- and right-hand side.
- constraint_namestr or None
- The name of the path constraint. By default, this is ‘var_constraint’ if name is a single variable,
or the left-hand side of the equation if name is an expression.
- unitsstr or None
The units in which the boundary constraint is to be applied. If None, use the units associated with the constrained output. If provided, must be compatible with the variables units.
- shapetuple, list, ndarray, or None
The shape of the variable being boundary-constrained. This can be inferred automatically for time, states, controls, and parameters, but is required if the constrained variable is an output of the ODE system.
- indicestuple, list, ndarray, or None
The indices of the output variable to be constrained at each point in time in the phase. When the variable is multi-dimensional, this should be a list of lists, one for each dimension, containing the indices to be constrained. Note the behavior of indices changes depending on the value of the flat_indices option.
- lowerfloat or ndarray, optional
Lower boundary for the variable.
- upperfloat or ndarray, optional
Upper boundary for the variable.
- equalsfloat or ndarray, optional
Equality constraint value for the variable.
- scalerfloat or ndarray, optional
Value to multiply the model value to get the scaled value. Scaler is second in precedence.
- adderfloat or ndarray, optional
Value to add to the model value to get the scaled value. Adder is first in precedence.
- reffloat or ndarray, optional
Value of response variable that scales to 1.0 in the driver.
- ref0float or ndarray, optional
Value of response variable that scales to 0.0 in the driver.
- linearbool
Set to True if constraint is linear. If set to True and the constrained output is not a linear function of the design variables, the optimization will fail.
- flat_indicesbool
If True, treat indices as flattened C-ordered indices of elements to constrain at each given point in time. Otherwise, indices should be a tuple or list giving the elements to constrain at each point in time.
simulate#
- Phase.simulate(times_per_seg=None, method=unspecified, atol=unspecified, rtol=unspecified, first_step=unspecified, max_step=unspecified, record_file=None, reports=False, interpolant='cubic')[source]
Simulate the Phase 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.
- 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.
duplicate#
- Phase.duplicate(transcription=None, boundary_constraints=False, path_constraints=False, objectives=False, fix_initial_time=False, fix_initial_states=None, fix_final_states=None)[source]
Create a copy of this phase where most options and attributes are deep copies of those in the original.
By default, a deepcopy of the transcription in the original phase is used. Boundary constraints, path constraints, and objectives are _NOT_ copied by default, but the user may opt to do so. By default, initial time is not fixed, nor are the initial or final state values. These also can be overridden with the appropriate arguments.
- Parameters:
- transcriptionTranscriptionBase or None
If given, use the specified transcription for the new phase. If None, use a copy of the transcription of the phase to be copied.
- boundary_constraintsbool
If True, retain all boundary constraints from the phase to be copied.
- path_constraintsbool
If True, retain all path constraints from the phase to be copied.
- objectivesbool
If True, retain all objectives from the phase to be copied.
- fix_initial_timebool
If True, fix the initial time of the returned phase.
- fix_initial_statesSequence of str or None
If given, set fix_initial=True for the given state names. Otherwise, all states will have fix_initial=False.
- fix_final_statesSequence of str or None
If given, set fix_final=True for the given state names. Otherwise, all states will have fix_final=False.
- Returns:
- Phase
The new phase created by duplicating this one.
set_refine_options#
- Phase.set_refine_options(refine=unspecified, tol=unspecified, min_order=unspecified, max_order=unspecified, smoothness_factor=unspecified)[source]
Set the specified option(s) for grid refinement in the phase.
- Parameters:
- refinebool
If True, this Phase will undergo refinement during the grid refinement procedure.
- tolfloat
The error tolerance used by all grid-refinement algorithms.
- min_orderint
The minimum allowable transcription order for segments in the phase. Used in hp and ph refinement methods.
- max_orderint
The maximum allowable transcription order for segments in the phase. Used in hp and ph refinement methods.
- smoothness_factorfloat
The maximum allowable ratio of state second derivatives. If exceeded the segment must be split. Used in hp refinement method.
interp#
- Phase.interp(name=None, ys=None, xs=None, nodes=None, kind='linear', axis=0)[source]
Interpolate values onto the given subset of nodes in the phase.
If specified, name will be used to determine the kind of variable being interpolated.
- Parameters:
- namestr or None
If nodes is None, then use the name argument to determine which kind of variable is being interpolated. If it is a state, assume nodes is ‘state_input’. If it is related to a control, assume nodes is ‘control_input’. If it is a polynomial control, assume the nodes are the input nodes for that polynomial control. Any other type of variable will result in an error.
- ysndarray or Sequence or None
Array of control/state/parameter values.
- xsndarray or Sequence or None
Array of integration variable values.
- nodesstr or Sequence or None
The name of the node subset, a set of nodes in phase tau space ([-1, 1] across the phase), or None (default).
- kindstr
Specifies the kind of interpolation, as per the scipy.interpolate package. One of (‘linear’, ‘quadratic’, ‘cubic’). Any other value will result in linear interpolation and is allowed for backward compatibility. Default is ‘linear’.
- axisint
Specifies the axis along which interpolation should be performed. Default is the first axis (0).
- Returns:
- np.array
The values of y interpolated at nodes of the specified type.