Command Line Tools

Command Line Tools#

Aviary has a number of command line tools that are available via the aviary command.

Note

When using a command line tool on a script that takes its own command line arguments, those arguments must be placed after a -- on the command line. Anything to the right of the -- will be ignored by the Aviary command line parser and passed on to the user script. For example: Aviary sub_command -o foo.html myscript.py -- -x --myarg=bar would pass -x and --myarg=bar as args to myscript.py.

All available aviary sub-commands can be shown using the following command:

aviary -h

usage: aviary [-h] [--version]  ...

aviary Command Line Tools

options:
  -h, --help         show this help message and exit
  --version          show version and exit

Tools:
  
    check            Verify Aviary installation
    convert          Convert legacy formatted data files (aero_table,
                     engine_deck, fortran_to_aviary, propeller_table) to
                     Aviary format.
    dashboard        Open the results dashboard for a provided Aviary run.
    draw_mission     Open the mission profile drawing GUI.
    plot_drag_polar  Plot a Drag Polar Graph using a provided polar data csv
                     input.
    rtplot           Run a script and show a real-time plot of the
                     optimization progress.
    run_mission      Run Aviary using a provided input deck.

To get further info on any sub-command, follow the command with a -h. For example:

aviary run_mission -h

usage: aviary run_mission [-h] [--optimizer {SNOPT,IPOPT,SLSQP,None}]
                          [--phase_info PHASE_INFO] [--max_iter MAX_ITER]
                          [--verbosity {0,1,2,3}] [--rtplot]
                          indeck

positional arguments:
  indeck                Name of vehicle input deck file

options:
  -h, --help            show this help message and exit
  --optimizer {SNOPT,IPOPT,SLSQP,None}
                        Name of optimizer
  --phase_info PHASE_INFO
                        Path to phase info file
  --max_iter MAX_ITER   maximum number of iterations
  --verbosity {0,1,2,3}
                        verbosity settings: 0=quiet, 1=brief, 2=verbose,
                        3=debug
  --rtplot              Enable realtime plotting option

Available Commands and Their Usage#

aviary run_mission#

run_mission is a command line interface that will run an analysis on a given csv input file.

aviary run_mission -h

usage: aviary run_mission [-h] [--optimizer {SNOPT,IPOPT,SLSQP,None}]
                          [--phase_info PHASE_INFO] [--max_iter MAX_ITER]
                          [--verbosity {0,1,2,3}] [--rtplot]
                          indeck

positional arguments:
  indeck                Name of vehicle input deck file

options:
  -h, --help            show this help message and exit
  --optimizer {SNOPT,IPOPT,SLSQP,None}
                        Name of optimizer
  --phase_info PHASE_INFO
                        Path to phase info file
  --max_iter MAX_ITER   maximum number of iterations
  --verbosity {0,1,2,3}
                        verbosity settings: 0=quiet, 1=brief, 2=verbose,
                        3=debug
  --rtplot              Enable realtime plotting option

To use small_single_aisle_GASP.csv, run the command aviary run_mission models/aircraft/small_single_aisle/small_single_aisle_GASP.csv in aviary/models/aircraft/small_single_aisle

SNOPT is the default optimizer, but IPOPT is available as well.

input_deck is the path to vehicle input deck .csv file. --optimizer is the name of the optimizer. The default is IPOPT. --phase_info is the path to phase info file. If it is missing, it depends on the mission method (equations_of_motion with value of 2DOF or energy_state) which is defined in the .csv input file. --max_iter is the maximum number of iterations. The default is max_iter.

aviary convert fortran_to_aviary#

The aviary convert fortran_to_aviary command will convert a Fortran input deck to an Aviary csv.

aviary convert fortran_to_aviary -h

usage: aviary convert fortran_to_aviary [-h] -f {GASP,FLOPS} [--force]
                                        [-v {0,1,2,3}]
                                        input_deck [output_file]

positional arguments:
  input_deck            Filename of vehicle input deck, including partial or
                        complete path.
  output_file           Filename for converted input deck, including partial
                        or complete path.

options:
  -h, --help            show this help message and exit
  -f, --format {GASP,FLOPS}
                        Name of the legacy code the deck originated from
  --force               Allow overwriting existing output files
  -v, --verbosity {0,1,2,3}
                        Set level of print statements

The only two required inputs are the filepath to the input deck and -f (for --format with options FLOPS and GASP). When this command is run, a brief message is printed. To print more messages, one can set verbosity level higher. For example, -v 3 will result in debug messages being printed. See Controlling Display Levels for more details. If an invalid filepath is given, pre-packaged resources will be checked for input decks with a matching name. If the output file name is not specified, a detault name is assumed to be the trunk of the input file name with csv as file extension. For example, an input file sample.dat will result in sample_converted.csv. If the output file exists, the command will not run unless the user specifies --force to force the overwritten action.

Here, pre-packaged resources are absolute path, relative path, Aviary based path, and relative path relative to the Aviary models folder.

Notes for input decks:

When specifying variables from FORTRAN, they should be in the appropriate NAMELIST
Names are not case-sensitive
Comments can be added using “!”
Lists can be entered by separating values with commas on the same line
For GASP variables where required, individual list elements can be specified by adding an index after the variable name
- (NOTE: 1 indexing is used inside NAMELISTS, while 0 indexing is used outside NAMELISTS)

Example inputs (GASP-style file):

$INGASP
DELP = 7.34797 ! typical GASP input
ARNGE(1) = 3600 ! variable with specified index
ACLS = 0.0,0.40,0.60,0.80,1.00,1.20, 1.40,1.60,1.80, ! values given as array

Example usage: aviary convert fortran_to_aviary --format GASP --force GASP_test.dat Converts the GASP input deck to Aviary (even if a file with the name GASP_test.dat already exists).

aviary convert engine_deck#

The aviary convert engine_deck command will convert a legacy formatted (FLOPS or GASP) engine deck into an Aviary formatted engine deck.

aviary convert engine_deck -h

usage: aviary convert engine_deck [-h] [-f {FLOPS,GASP,GASP_TS}] [--round]
                                  input_file [output_file]

positional arguments:
  input_file            path to engine deck file to be converted
  output_file           path to file where new converted data will be written

options:
  -h, --help            show this help message and exit
  -f, --format {FLOPS,GASP,GASP_TS}
                        data format used by input_file
  --round               round data to improve readability

Users must provide the path or name of an input deck, and the engine format being converted. If an invalid filepath is given for the input file, pre-packaged resources will be checked for input decks with a matching name.

The path to the output file name is optional. If it is missing, the output file name takes the trunk of the input file name with deck as default file extension. For example, an input file sample.eng will result in sample.csv unless the user specifies the output file name.

If the output file exists, it will be overwritten.

The engine format is specified by -f or --format with one of FLOPS, GASP, and GASP_TS string (TS stands for turboshaft). If multiple are specified, the last one will be used.

Notes for input decks:

Turbofan decks for both FLOPS and GASP can be converted
Turboshaft decks for GASP can also be converted
Comments can be added using #

Example usage:

# Convert a GASP based turbofan
aviary convert engine_deck turbofan_23k_1.eng turbofan_23k_1.csv -f GASP 
# Convert a FLOPS based turbofan
aviary convert engine_deck turbofan_22k.eng turbofan_22k.csv -f FLOPS 
# Convert a GASP based turboshaft
aviary convert engine_deck turboshaft_4465hp.eng turboshaft_4465hp.csv --format GASP_TS

aviary convert aero_table#

The aviary convert aero_table command will convert a legacy formatted (FLOPS or GASP) aero table into an Aviary formatted aero table.

aviary convert aero_table -h

usage: aviary convert aero_table [-h] [-f {FLOPS,GASP,GASP_ALT}]
                                 input_file [output_file]

positional arguments:
  input_file            path to aero data file to be converted
  output_file           path to file where new converted data will be written

options:
  -h, --help            show this help message and exit
  -f, --format {FLOPS,GASP,GASP_ALT}
                        data format used by input_file

Users must provide the path or name of an input deck and the data format being converted. Optionally, the path to the output file can also be specified, otherwise the default output file will be in the same location and have the same name as input file, but with ‘_aviary’ appended to the end of filename trunk while the file extension is preserved. For example, an input file sample.txt will result in sample_aviary.txt unless the user specifies the output file name. If both -f and --format are specified, the later one is taken. If an existing file has the same name as output file name, the existing file will be overwritten. If an invalid filepath is given for the input file, pre-packaged resources will be checked for input decks with a matching name.

Notes for input decks:

Aero tables for both FLOPS and GASP can be converted
GASP tables will create a single file containing all the lift and drag information
There are two types of GASP tables. The first one combines CL and CD into one single table. The second one has them separated with a possible CD0 table. We name the first one as GASP_ALT and the second one as GASP. The second one is usually obtained by high fidelity CFD tools.
FLOPS tables will create two files, one containing the lift-dependent drag and the other containing the lift-independent drag.
Comments can be added using #

Example usage:

# Converts a GASP based aero table 
aviary convert aero_table -f GASP_ALT validation_cases/validation_data/legacy_files/aero_free_GASP.txt large_single_aisle_1_aero_flaps.csv
# Converts a GASP based alternative aero table 
aviary convert aero_table -f GASP validation_cases/validation_data/legacy_files/aero_BWB_modified_GASP.txt generic_BWB_GASP_aero.csv
# Converts a FLOPS based aero table
aviary convert aero_table -f FLOPS validation_cases/validation_data/legacy_files/flops_test_polar.txt aviary_flops_polar.txt

aviary convert propeller_table#

The aviary convert propeller_table command converts a legacy formatted (GASP) propeller map into an Aviary formatted propeller map. Currently, GASP is the only format supported.

aviary convert propeller_table -h

usage: aviary convert propeller_table [-h] [--round] input_file [output_file]

positional arguments:
  input_file   path to propeller map file to be converted
  output_file  path to file where new converted data will be written
               (optional)

options:
  -h, --help   show this help message and exit
  --round      round data to improve readability

Users must provide the path or name of an input deck, and optionally the path to the desired output file. If not provided, the output file will have the same filename as the input file but with the exension .prop. This is arbitrary, and .prop is not a required file extension for propeller data files, but it is designed to help users recognize the purpose of the data table without needing to open it. If an invalid filepath is given for the input file, Aviary’s files will be checked for input decks with a matching name.

Notes for input decks:

There are two options for Mach number: Mach number and helical Mach number at 75% radius. We provide one example for each. This is the first integer on the first line of the input file. (1 = Mach, 2 = helical Mach)
Comments can be added using #

Example usage:

# Convert GASP based propeller map PropFan.map to Aviary data table PropFan.csv
aviary convert propeller_table PropFan.map PropFan.csv
# Convert GASP based propeller map general_aviation.map to Aviary data table general_aviation.csv
aviary convert propeller_table general_aviation.map general_aviation.csv
# Convert GASP based propeller map general_aviation.map to Aviary data table general_aviation.csv
aviary convert propeller_table general_aviation.map

The first example uses Mach number and the second example uses helical Mach number. Note that the output file name was not specified in the third example.

aviary draw_mission#

The aviary draw_mission command will bring up a new graphical interface for users to create a mission. This command does not have an input. More details can be found at Drawing and running simple missions.

aviary plot_drag_polar#

The aviary plot_drag_polar command will bring up a new graphical interface for users to draw drag polar. No options are needed on the command line but a file explorer window will pop-up to allow the user to select a drag polar file (a .csv file).

aviary plot_drag_polar -h

usage: aviary plot_drag_polar [-h]

options:
  -h, --help  show this help message and exit

aviary dashboard#

The aviary dashboard command will bring up a dashboard that lets the user easily browse between the reports and files that are generated during an Aviary run.

aviary dashboard -h

usage: aviary dashboard [-h] [--port PORT] [-b] [-d] [--save [SAVE]] [--force]
                        [script_name ...]

positional arguments:
  script_name       Name of aviary script that was run (not including .py).

options:
  -h, --help        show this help message and exit
  --port PORT       dashboard server port ID (default is 0, which indicates
                    get any free port)
  -b, --background  Run the server in the background (don't automatically open
                    the browser)
  -d, --debug       show debugging output
  --save [SAVE]     Name of zip file in which dashboard files are saved. If no
                    argument given, use the script name to name the zip file
  --force           When displaying data from a shared zip file, if the
                    directory in the reports directory exists, overrite if
                    this is True

To use this utility, either a problem has been run or a run script is provided.

--port is the dashboard server port ID. The default is 0 meaning any free port. -b or --background indicates to run in background. Default is False. -d or --debug indicates to show debugging output. Default is False. --save is the name of zip file in which dashboard files are saved. If no argument given, use the script name to name the zip file. --force indicates to overwrite the saved zip file. The default is False. script_name is the name of aviary script that was run (not including .py), or the csv input filename if the user runs a Level 1 script.

More discussion on aviary dashboard command can be found in Visualizing Results from Aviary.

aviary rtplot#

The aviary rtplot command runs an Aviary script and also displays a real-time plot of the variables as an optimization progresses. It makes use of the data being written to a case recorder file, the script must add a recorder to the Driver.

aviary rtplot -h

usage: aviary rtplot [-h] file

positional arguments:
  file        Python file containing the model.

options:
  -h, --help  show this help message and exit

An example of using this command would be

aviary rtplot aviary_script.py

Command Line Tools

Contents

Command Line Tools#

Available Commands and Their Usage#

aviary run_mission#

aviary convert fortran_to_aviary#

aviary convert engine_deck#

aviary convert aero_table#

aviary convert propeller_table#

aviary draw_mission#

aviary plot_drag_polar#

aviary dashboard#

aviary rtplot#