Vehicle Input .csv File and Phase_info Dictionary#
Vehicle Input .csv File#
Note
This section is under development.
Aviary uses two main files to define the vehicle and the trajectory – the vehicle .csv definition and a phase_info
dictionary definition that defines the trajectory parameters.
You can think of the first file as describing the vehicle’s physical properties and the second file as describing the trajectory’s properties and optimization parameters.
The vehicle .csv file is structured as multiple rows, each containing a specific vehicle parameter’s name, value, and units. A portion of an example vehicle .csv file is shown below:
aircraft:air_conditioning:mass_scaler,1.0,unitless
aircraft:canard:area,0.0,ft**2
aircraft:crew_and_payload:cargo_container_mass_scaler,1.0,unitless
aircraft:crew_and_payload:non_flight_crew_mass_scaler,1.0,unitless
mission:design:range,3500,NM
mission:summary:fuel_flow_scaler,1.0,unitless
settings:equations_of_motion,height_energy
...
Depending on which analysis options you use with Aviary, you might need to define certain parameters within the vehicle .csv file. The simplest way to get started is to use a provided example vehicle .csv file and modify it as needed for your specific vehicle.
In vehicle .csv files that were created with the fortran_to_aviary converter that were created from GASP files, there is a section with the heading ‘# Initialization Guesses’ that is used to initialize the trajectory. It contains the following keys along with default initialization values:
actual_takeoff_mass,0
rotation_mass,0
operating_empty_mass,0
fuel_burn_per_passenger_mile,0
cruise_mass_final,0
flight_duration,0
time_to_climb,0
climb_range,0
reserves,0
The user can also specify these parameters with the prefix ‘initialization_guesses:’ e.g. ‘initialization_guesses:actual_takeoff_mass,150000’ would set actual_takeoff_mass in the initialization_guesses dictionary to 150000.
When the initialization_guessing() method is called and wherever the initialization_guesses values are equal to 0, they are updated with calculated estimates based off the problem type (sizing, alternate, fallout) and mass, speed, range, thrust, and payload data specified in the vehicle input .csv file.
The initial guess of reserves
is used to define the reserve fuel. Initially, its value can be anything larger than or equal to 0. There are two Aviary variables to control the reserve fuel in the model file (.csv
):
Aircraft.Design.RESERVE_FUEL_ADDITIONAL
: the required fuel reserves: directly in lbm,Aircraft.Design.RESERVE_FUEL_FRACTION
: the required fuel reserves: given as a proportion of mission fuel.
If the value of initial guess of reserves
(also in the model file if any) is 0, the initial guess of reserve fuel comes from the above two Aviary variables. Otherwise, it is determined by the parameter reserves
:
if
reserves > 10
, we assume it is the actual fuel reserves.if
0.0 <= reserves <= 10
, we assume it is the fraction of the mission fuel.
The initial guess of reserves
is always converted to the actual design reserves (instead of reserve factor) and is used to update the initial guesses of fuel_burn_per_passenger_mile
and cruise_mass_final
.
Phase Info Dictionary#
phase_info
is a nested dictionary that Aviary uses for users to define their mission phases - how they are built, the design variables, constraints, connections, etc.
We will now discuss the meaning of the keys within the phase_info
objects.
If a key starts with
min_
ormax_
or ends with_lower
or_upper
, it is a lower or upper bound of a state variable. The following keys are not state variables:required_available_climb_rate
: the minimum rate of climb required from the aircraft at the top of climb (beginning of cruise) point in the mission. You don’t want your available rate-of-climb to be 0 in case you need to gain altitude during cruise.EAS_limit
: the maximum descending EAS in knots.throttle
: the prescribed throttle setting. This is only used forGASP
andsolved
missions.
If a key ends with
_ref
or_ref0
(exceptduration_ref
andinitial_ref
), it is the unit-reference and zero-reference values of the control variable at the nodes. This option is invalid if opt=False. Note that it is a simple usage of ref and ref0. We refer to Dymos for details.Some keys are for phase time only.
duration_ref
is the unit-reference for phase time duration.duration_bounds
are the bounds (lower, upper) for the time duration of the phase.initial_ref
is the unit-reference for the initial value of time.initial_bounds
: the lower and upper bounds of initial time.
If a key starts with
final_
, it is the final value of a state variable.If a key ends with
_constraint_eq
, it is an equality constraint.Keys related to altitude:
We use
final_altitude
to indicate the final altitude of the phase.Meanwhile,
alt
is a key in acceleration phase parameter for altitude inGASP
missions andaltitude
is a key in all other phases of all missions.
Some keys are a boolean flag of True or False:
input_initial
: the flag to indicate whether initial values of of a state (such as: altitude, velocity, mass, etc.) is taken.add_initial_mass_constraint
: the flag to indicate whether to add initial mass constraintclean
: the flag to indicate no flaps or gear are included.connect_initial_mass
: the flag to indicate whether the initial mass is the same as the final mass of previous phase.fix_initial
: the flag to indicate whether the initial state variables is fixed.no_climb
: if True for the descent phase, the aircraft is not allowed to climb during the descent phase.no_descent
: if True for the climb phase, the aircraft is not allowed to descend during the climb phase.include_landing
: the flag to indicate whether there is a landing phase.include_takeoff
: the flag to indicate whether there is a takeoff phase.optimize_mass
: if True, the gross takeoff mass of the aircraft is a design variable.target_mach
: the flag to indicate whether to target mach number.
initial_guesses
: initial guesses of state variables.COLLOCATION
related keys:num_segments
: the number of segments in transcription creation in Dymos. The minimum value is 1. This is needed if ‘AnalysisScheme’ isCOLLOCATION
.order
: the order of polynomials for interpolation in transcription creation in Dymos. The minimum value is 3. This is needed if ‘AnalysisScheme’ isCOLLOCATION
.
Other Aviary keys:
subsystem_options
: Thecore_aerodynamics
key allows two methods:computed
andsolved_alpha
. In case ofsolved_alpha
, it requires an additional keyaero_data
.external_subsystems
: a list of external subsystems.
other keys that are self-explanatory:
clean
: a flag for low speed aero (which includes high-lift devices) or cruise aero (clean, because it does not include high-lift devices).EAS_target
: the target equivalent airspeed.initial_mach
: initial Mach number.linear_solver
: provide an instance of a LinearSolver to the phase.mach_cruise
: the cruise mach number.nonlinear_solver
: provide an instance of a NonlinearSolver to the phase.polynomial_control_order
: default toNone
.fix_duration
: default toFalse
.solve_for_distance
: if True, use a nonlinear solver to converge thedistance
state variable to the desired value. Otherwise use the optimizer to converge thedistance
state.optimize_mach
: if True, the Mach number is a design variable.optimize_altitude
: if True, the altitude is a design variable.constraints
: a dictionary of user-defined constraints. The keys are the names of the constraints and the values are the keyword arguments expected by Dymos.
Note
Not all the keys apply to all phases. The users should select the right keys for each phase of interest. The required keys for each phase are defined in check_phase_info function. Currently, this function does the check only for FLOPS
and GASP
missions.
Using custom phase builders#
For the height_energy
, you can use a user-defined phase builder.
The user-defined phase builder must inherit from PhaseBuilderBase
and provide the from_phase_info
and the build_phase
methods.
The from_phase_info
method is used to convert the phase_info
dictionary into the inputs needed for the phase builder object.
The build_phase
method is used to actually build and output the Phase
object.
For examples of how to create a custom phase builder, see the energy_phase.py
file.
Note
Using custom phase builders is a particularly advanced feature and is not recommended for most users.