How Aviary Defines Variables

Aircraft models in Aviary usually consist of hundreds of different variables representing different aspects of the physical aircraft, behavior of the model, behavior of the mission, and more. Aviary has a standardized scheme for organizing and naming variables. The primary goal of Aviary’s variable naming scheme are to promote human readability/comprehension.

Additional Reading

The following pages have more information on how Aviary uses variables.

Definition of all Aviary variables

Define your own variable hierarchy

Variable Hierarchy

Aviary organizes all of its variables in a hierarchical fashion, organizing individual variables under several layers. At the top level, there are four variable categories:

Aircraft: Variables that describe the physical properties of the vehicle. Aircraft variables are further broken down using a functional decomposition, dividing the aircraft into its physical pieces and defining the variables that describe them.

Mission: Variables that define constraints and some high-level information about the mission to be flown, as well as variables that summarize mission results.

Dynamic: Properties which change with time over the course of the mission (all other variables in the hierarchy are assumed to remain constant with time).

Settings: Various settings for running Aviary that do not directly describe the aircraft or its mission.

Each of these main categories is broken down into various subcategories, and eventually down to a specific variable. Variable names in Aviary always include the full hierarchy path to prevent confusion and duplicate names. For example, a wing and a tail both have a span property, so a variable cannot simply be named “span” or it will be confusing for the user (and Aviary’s code) which span is being referred to at any given time. So wingspan in Aviary is instead named aircraft:wing:span. Note how each hierarchy level is separated by a colon, giving the full “path” and making it clear that span is a property of the wing, which is part of the aircraft.

When working in Python, Aviary provides the variable hierarchy in the form of a nested class structure. This allows users to use features of their IDE such as autocomplete and highlighting. The following code snippet is an example of how the variable hierarchy is defined:

class Aircraft:
    class Fuselage:
        DIAMETER = 'aircraft:fuselage:avg_diameter'
        LENGTH = 'aircraft:fuselage:length'

    class HorizontalTail:
        ROOT_CHORD = 'aircraft:horizontal_tail:root_chord'
        SPAN = 'aircraft:horizontal_tail:span'

    class LandingGear:
        CONFIGURATION = 'aircraft:landing_gear:configuration'
        TOTAL_MASS = 'aircraft:landing_gear:total_mass'

    class VerticalTail:
        ROOT_CHORD = 'aircraft:vertical_tail:root_chord'
        SPAN = 'aircraft:vertical_tail:span'

    class Wing:
        ROOT_CHORD = 'aircraft:wing:root_chord'
        SPAN = 'aircraft:wing:span'

In this example, we are looking at a subset of the Aircraft category, showing a few subgroups such as Fuselage, Wing, etc., and finally individual variables under each of those subgroups.

Each variable is ultimately represented by a string following the naming convention described earlier (hierarchical levels separated by colons). The Python variable Aircraft.Wing.SPAN contains the actual variable name, the string aircraft:wing:span. The Python definition essentially matches the variable name, except in all lowercase and with colons instead of periods to separate the levels. In the example hierarchy, we can see that sometimes the Pythonic name does not perfectly match the full variable name, such as Aircraft.LandingGear.TOTAL_MASS vs aircraft:landing_gear:total_mass. We want Aviary variables to be easily readable, so underscores are used as spaces between individual words, but this is not considered good practice for naming Python classes. So the single word “LandingGear” is used instead.

When using an IDE, autocomplete will show you all existing options for each layer of the variable hierarchy, so in practice you do not need to be aware of these small discrepancies. If can’t remember the exact name of the variable or variable category you want, just start typing and see the list your IDE autocomplete suggests.

Here the variables are all in the third layer, but this isn’t a universal rule. The variable hierarchy contains variables at a depth of as few as two, or as many as four, and a user can define new variables using whatever number of layers they deem necessary.

To use the actual Aviary variable hierarchy, you can import it using the Python API.

from aviary.api import Aircraft, Dynamic, Mission, Settings

The variable hierarchy is defined here in the source code.

Variable Metadata

The variable hierarchy simply defines the name and organizational structure of each variable, which is insufficient for aircraft modeling. Aviary also separately defines “metadata” for each variable, which contains information such as a description of what the variable is, its default value, and the expected Python data type (a string, float, list, etc.) This is not simply documentation, but directly defines how Aviary handles each variable. Changing the default value for a variable in the metadata actually changes what value Aviary will use during code execution.

The Aviary metadata is documented here, and is actually defined in the source code here.