Mission Definition

# Testing Cell
from aviary.mission.flight_phase_builder import FlightPhaseOptions
from aviary.mission.solved_two_dof.phases.groundroll_phase import GroundrollPhaseOptions as FGopt
from aviary.mission.solved_two_dof.phases.groundroll_phase import GroundrollPhaseOptions as FGopt
from aviary.mission.two_dof.phases.accel_phase import AccelPhaseOptions
from aviary.mission.two_dof.phases.flight_phase import FlightPhaseOptions as GFlightPhaseOptions
from aviary.mission.two_dof.phases.flight_phase import FlightPhaseOptions as GFlightPhaseOptions
from aviary.mission.two_dof.phases.simple_cruise_phase import SimpleCruisePhaseOptions
from aviary.mission.two_dof.phases.takeoff_phase import TakeoffPhaseOptions
from aviary.mission.two_dof.phases.takeoff_phase import TakeoffPhaseOptions
from aviary.mission.solved_two_dof.phases.solved_twodof_phase import SolvedTwoDOFPhaseOptions
from aviary.utils.doctape import glue_keys

dummy_phase_info = {}
dummy_phase_info.update(AccelPhaseOptions().items())
dummy_phase_info.update(FlightPhaseOptions().items())
dummy_phase_info.update(FGopt().items())
dummy_phase_info.update(FlightPhaseOptions().items())
dummy_phase_info.update(GFlightPhaseOptions().items())
dummy_phase_info.update(GFlightPhaseOptions().items())
dummy_phase_info.update(SimpleCruisePhaseOptions().items())
dummy_phase_info.update(TakeoffPhaseOptions().items())
dummy_phase_info.update(TakeoffPhaseOptions().items())
dummy_phase_info.update(SolvedTwoDOFPhaseOptions().items())
glue_keys(dummy_phase_info)

phase_type

_value_

_name_

_sort_order_

num_segments

order

mass_initial

mass_final

mass_bounds

mass_ref

mass_ref0

mass_defect_ref

mass_solve_segments

mass_constraint_ref

distance_initial

distance_final

distance_bounds

distance_ref

distance_ref0

distance_defect_ref

distance_solve_segments

distance_constraint_ref

velocity_initial

velocity_final

velocity_bounds

velocity_ref

velocity_ref0

velocity_defect_ref

velocity_solve_segments

velocity_constraint_ref

time_initial

time_initial_bounds

time_initial_ref

time_duration

time_duration_bounds

time_duration_ref

reserve

target_distance

EAS_constraint_eq

alt

altitude_optimize

altitude_initial

altitude_final

altitude_bounds

altitude_ref

altitude_ref0

altitude_polynomial_order

mach_optimize

mach_initial

mach_final

mach_bounds

mach_ref

mach_ref0

mach_polynomial_order

throttle_enforcement

throttle_optimize

throttle_initial

throttle_final

throttle_bounds

throttle_ref

throttle_ref0

throttle_polynomial_order

throttle_allocation

required_available_climb_rate

ground_roll

constraints

no_climb

no_descent

transcription

altitude_defect_ref

altitude_solve_segments

altitude_constraint_ref

EAS_target

mach_target

input_speed_type

alt_cruise

mach_cruise

flight_path_angle_initial

flight_path_angle_final

flight_path_angle_bounds

flight_path_angle_ref

flight_path_angle_ref0

flight_path_angle_defect_ref

flight_path_angle_solve_segments

flight_path_angle_constraint_ref

angle_of_attack_initial

angle_of_attack_final

angle_of_attack_bounds

angle_of_attack_ref

angle_of_attack_ref0

angle_of_attack_defect_ref

angle_of_attack_solve_segments

angle_of_attack_constraint_ref

angle_of_attack_optimize

angle_of_attack_polynomial_order

rotation

normal_ref

normal_ref0

pitch_constraint_bounds

pitch_constraint_ref

clean

['phase_type',
 '_value_',
 '_name_',
 '_sort_order_',
 'num_segments',
 'order',
 'mass_initial',
 'mass_final',
 'mass_bounds',
 'mass_ref',
 'mass_ref0',
 'mass_defect_ref',
 'mass_solve_segments',
 'mass_constraint_ref',
 'distance_initial',
 'distance_final',
 'distance_bounds',
 'distance_ref',
 'distance_ref0',
 'distance_defect_ref',
 'distance_solve_segments',
 'distance_constraint_ref',
 'velocity_initial',
 'velocity_final',
 'velocity_bounds',
 'velocity_ref',
 'velocity_ref0',
 'velocity_defect_ref',
 'velocity_solve_segments',
 'velocity_constraint_ref',
 'time_initial',
 'time_initial_bounds',
 'time_initial_ref',
 'time_duration',
 'time_duration_bounds',
 'time_duration_ref',
 'reserve',
 'target_distance',
 'EAS_constraint_eq',
 'alt',
 'altitude_optimize',
 'altitude_initial',
 'altitude_final',
 'altitude_bounds',
 'altitude_ref',
 'altitude_ref0',
 'altitude_polynomial_order',
 'mach_optimize',
 'mach_initial',
 'mach_final',
 'mach_bounds',
 'mach_ref',
 'mach_ref0',
 'mach_polynomial_order',
 'throttle_enforcement',
 'throttle_optimize',
 'throttle_initial',
 'throttle_final',
 'throttle_bounds',
 'throttle_ref',
 'throttle_ref0',
 'throttle_polynomial_order',
 'throttle_allocation',
 'required_available_climb_rate',
 'ground_roll',
 'constraints',
 'no_climb',
 'no_descent',
 'transcription',
 'altitude_defect_ref',
 'altitude_solve_segments',
 'altitude_constraint_ref',
 'EAS_target',
 'mach_target',
 'input_speed_type',
 'alt_cruise',
 'mach_cruise',
 'flight_path_angle_initial',
 'flight_path_angle_final',
 'flight_path_angle_bounds',
 'flight_path_angle_ref',
 'flight_path_angle_ref0',
 'flight_path_angle_defect_ref',
 'flight_path_angle_solve_segments',
 'flight_path_angle_constraint_ref',
 'angle_of_attack_initial',
 'angle_of_attack_final',
 'angle_of_attack_bounds',
 'angle_of_attack_ref',
 'angle_of_attack_ref0',
 'angle_of_attack_defect_ref',
 'angle_of_attack_solve_segments',
 'angle_of_attack_constraint_ref',
 'angle_of_attack_optimize',
 'angle_of_attack_polynomial_order',
 'rotation',
 'normal_ref',
 'normal_ref0',
 'pitch_constraint_bounds',
 'pitch_constraint_ref',
 'clean']

Mission Definition#

“Mission definition” is all of the information needed for Aviary to create a Dymos trajectory that flies the vehicle through the desired mission profile. Specifically, it defines all of the information needed to define Dymos phases (a list of that information can be found in the Dymos docs). This is a vast list, and is much more detailed than the majority of Aviary users need to know. Aviary only needs a select amount of information about each mission from the user, which is conveyed in the mission definition. This takes the form of a Python dictionary commonly referred to as the phase_info in Aviary.

Phase Info Overview#

Aviary uses a nested Python dictionary to define and control all aspects of the mission and its phases. The dictionary must have a very specific structure, and all valid keys Aviary recognizes are detailed later in this section. Understanding this format is necessary if you want to modify existing missions or design your own.

The top level of the phase_info contains a name string and a sub-dictionary for each phase in the mission. Users are free to choose any valid python name for their phases (valid characters are upper/lower case letters, numbers, and underscores.) In addition, there are two default categories “pre_mission” and “post_mission”. These contain any settings that pertain to the pre_mission, which is any calculation that occurs before the mission runs, and the post_mission, which is any calculation that occurs after the mission runs. The sub-dictionaries for “pre_mission” and “post_mission” must be named exactly as shown, and cannot have custom names.

phase_info = {
    'pre_mission': {},
    'climb1': {},
    'climb2': {},
    'cruise': {},
    'descent': {},
    'post_mission': {},
}

Note that the order is important, so “pre_mission” should be first, followed by phases in chronological order, terminated by “post_mission”. All of the sections shown in this example are optional, including “pre_mission”, and “post_mission” - the options that can be configured in those sections are not required.

Note

When using the Python API, the variable name for the dictionary is not important, since you will just be passing it as an argument to the function that runs Aviary. If you are providing your phase_info as a file, such as when running Aviary from the command line, the dictionary must be named “phase_info” so it can be found and loaded successfully.

Phase Options#

Each phase has its own unique set of options, which are further organized inside additional sub-dictionaries. Here is an example of a phase-specific dictionary with the 3 possible sub-categories already defined:

phase_info['climb1'] = {
    'subsystem_options': {},
    'user_options': {},
    'initial_conditions': {},
}

The ‘subsystem_options’ dictionary contains options for all subsystems. The ‘user_options’ dictionary includes all options that define the phase and its boundary conditions. The ‘initial_conditions’ dictionary allows you to set initial values for any variables that are under control of the optimizer, including states, optimized controls, and time.

The following sections outline important options available for each of these categories. A full description of every user option in the phase_info for each of Aviary’s phase builders is given in the Complete phase_info Reference..

If you have a phase_info that was built in an version of Aviary prior to version 1.0, check the legacy phase_info conversion guide to learn what has changed.

Subsystem Options#

Here subsystem-specific options can be defined, which only apply to the specific phase they are present in. What options are available depends on which specific subsystems you are including with your model. Available options for the core Aviary subsystems are defined in their respective documentation pages in the User Guide.

User Options#

The user options format supports (and enforces) the inclusion of an OpenMDAO unit string when specifying any quantity that has a unit. These take the format of a tuple, such as “(500, ‘s’)” to represent “500 seconds”. If an option requires multiple value, a nested tuple is used, with the list of values stored in their own tuple: “((300.0, 900.0), ‘s’)”. For options whose values do not have a unit, you can either skip the units definition entirely, just directly providing the desired value, or you can specify units of “unitless” for clarity.

Aviary includes several sets of equations of motion to define flight physics, each with their own additional set of available options. Thus, the full set of valid options that can be specified in phase_info can differ based on your problem setup. The following section describes the general patterns that globally apply to all Aviary models.

General phase settings#

These options can be specified for any mission phase.

  • num_segments: The number of segments in the dymos transcription.

  • order: The order of polynomials for the dymos transcription.

  • throttle_enforcement: Enforce throttle as a “path_constraint” (default), “boundary_constraint”, a “control” (which can be optimized or set to a fixed value), or “bounded” via a solver upper and lower bounds (not recommended).

  • throttle_allocation: How to allocate throttles for multi-engine, can be “fixed” for user-specified allocations, “static” where the optimizer picks a single allocation for the whole phase, or “dynamic” where the optimizer chooses an allocation at each trajectory point.

  • no_climb: Set to True to prevent the aircraft from climbing during the phase. This option can be used to prevent unexpected climb during a descent phase. This is only available when using the energy_state equations of motion.

  • no_descent: Set to True to prevent the aircraft from descending during the phase. This can be used to prevent unexpected descent during a climb phase. This is only available when using the energy_state equations of motion.

  • transcription: Set the Dymos transcription to use for the phase. Aviary supports ‘Collocation’ or ‘PicardShooting’. See Dymos documentation for more details

  • transcription: Set the Dymos transcription to use for the phase. Aviary supports ‘Collocation’ or ‘PicardShooting’. See Dymos documentation for more details

Specialized phase settings#

These options are unique to specific types of phases, or have other limitations on their use.

  • reserve: When True, this is a reserve phase. These phases should appear after your final flight phase in the phase_info.

  • ground_roll: When True, restrict the problem to the ground plane. This will remove certain states/controls, and is only used in takeoff and landing phases when using the 2DOF equations of motion.

  • required_available_climb_rate: Adds a lower bound path constraint on altitude_rate_max, which is the maximum rate that the aircraft could climb at any point in the phase.

  • target_distance: Total mission distance constraint. This should be set in the final flight phase only.

  • constraints: Dictionary of custom constraints applied to dynamic variables in the phase.

State variables#

These options provide information about state variables, or variables that are summed over the course of a phase by Dymos. Which state variables exist in a phase is dependent on what kind of phase it is and which equations of motion are being used. Here, the options for the “mass” state are described. When defining options for a different state variable, the same set of options are available, but the variable name at the beginning of the option must be swapped out for the state variable of interest (such as mass_initial becoming altitude_initial).

  • mass_initial: Mass at the start of the phase. When unspecified, the optimizer controls the value. When specified, a constraint is created on the initial mass.

  • mass_final: Mass at the end of the phase. When unspecified, the optimizer controls the value. When specified, a constraint is created on the final mass.

  • mass_bounds: Tuple of upper and lower bounds for all values of mass in the phase. The default of None for either means that bound will not be declared.

  • mass_ref: Multiplicative scale factor “ref” for mass. Default is 1.0

  • mass_ref0: Additive scale factor “ref0” for mass. Default is None.

  • mass_defect_ref: Multiplicative scale factor “ref” for defect constraint. Deafult is None, which means the ref and defect_ref are the same.

  • mass_constraint_ref: Multiplicative scale factor “ref” for boundary constraint. If unspecified, then the value in mass_final will be used.

  • mass_solve_segments: When True, a solver will be used to converge the mass collocation defects within a segment. Note that the state continuity defects between segments will still be handled by the optimizer.

Controls#

These options provide information about control variables, or variables that are directly controlled by the optimizer. Like state variables, control variables for a given phase is also dependent on what kind of phase it is and which equations of motion are being used. The naming scheme is also similar, with the control variable of interest forming the first part of the option’s name.

  • altitude_optimize: When True, the optimizer will set this value. When False, the initial value for all nodes can be set in the initial_conditions section of the phase.

  • altitude_initial: Altitude at the start of the phase. If altitude_optimize is True, specifying this will create a constraint. Otherwise, it serves as an initial value for the first point. When unspecified, the linkage constraint with the upstream phase will drive this value if altitude_optimize is True.

  • altitude_final: Altitude at the end of the phase. If altitude_optimize is True, specifying this will create a constraint. Otherwise, it serves as an initial value for the first point. When unspecified, the linkage constraint with the downstream phase will drive this value if altitude_optimize is True.

  • altitude_bounds: Tuple of upper and lower bounds for all values of altitude in the phase. The default of None for either means that bound will not be declared.

  • altitude_ref: Multiplicative scale factor “ref” for altitude. Default is 1.0

  • altitude_ref0: Additive scale factor “ref0” for altitude. Default is None.

  • altitude_polynomial_order: The order of polynomials for interpolation in the transcription. Default is None, which does not use a polynomial.

Time#

  • time_initial: Value of “time” at the start of the phase. When unspecified, the value is determined by the optimizer.

  • time_duration: Duration of the phase. When unspecified, the value is determined by the optimizer.

  • time_initial_bounds: Upper and lower bounds for time_initial. Ignored if “time_initial” is specified.

  • time_duration_bounds: Upper and lower bounds for time_duration.

  • time_initial_ref: Multiplicative scale factor “ref” for time_initial. Default is 1.0

  • time_duration_ref: Additive scale factor “ref” for time_duration. Default is None.

Specialized 2DOF phase settings#

When using the 2DOF equations of motion, there are several phase options that are only available in specific phases. Future refactor may change some of these to be more consistent with the phase_options listed above in naming and function.

  • alt: Constant altitude for this phase. Only available in accel phases (i.e, phases with “accel” in their name).

  • EAS_target: Target airspeed for the balance in this phase. This is a maximum value that is enforced by a KS constraint. If the optimization objective prioritizes a quick climb or descent, the aircraft will fly at this velocity unless that exceeeds the mach_target, which it may at higher altitudes. Only available in flight phases.

  • mach_target: The maximum Mach during the phase. Only available in flight phases.

  • normal_ref: Multiplicative scale factor “ref” for the normal force constraint. Only available in rotation phases (i.e, phases with “rotation” in their name).

  • normal_ref0: Additive scale factor “ref0” for the normal force constraint. Only available in rotation phases (i.e, phases with “rotation” in their name).

  • pitch_constraint_bounds: Lower and upper bounds of the pitch constraint. Only available in takeoff phases.

  • pitch_constraint_bounds: Lower and upper bounds of the pitch constraint. Only available in takeoff phases.

  • pitch_constraint_ref: Multiplicative scale factor “ref” for the pitch constraint. Only available in takeoff phases.