Usage

FAST-OAD uses a configuration file for defining your OAD problem. You can interact with this problem using command line or Python directly.

You may also use some lower-level features of FAST-OAD to interact with OpenMDAO systems. This part is addressed in the API documentation.

FAST-OAD configuration file

FAST-OAD configuration files are in YAML format. A quick tutorial for YAML (among many ones) is available here

title: Sample OAD Process

# List of folder paths where user added custom registered OpenMDAO components
module_folders:

# Input and output files
input_file: ./problem_inputs.xml
output_file: ./problem_outputs.xml

# Definition of problem driver assuming the OpenMDAO convention "import openmdao.api as om"
driver: om.ScipyOptimizeDriver(tol=1e-2, optimizer='COBYLA')

# Definition of OpenMDAO model
# Although "model" is a mandatory name for the top level of the model, its
# sub-components can be freely named by user
model:

  #  Solvers are defined assuming the OpenMDAO convention "import openmdao.api as om"
  nonlinear_solver: om.NonlinearBlockGS(maxiter=100, atol=1e-2)
  linear_solver: om.DirectSolver()


  # Components can be put in sub-groups
  subgroup:

    # A group can be set with its own solvers.

    nonlinear_solver: om.NonlinearBlockGS(maxiter=100, atol=1e-2, iprint=0)
    linear_solver: om.DirectSolver()

    geometry:
      # An OpenMDAO component is identified by its "id"
      id: fastoad.geometry.legacy
    weight:
      id: fastoad.weight.legacy
    mtow:
      id: fastoad.mass_performances.compute_MTOW
    hq_tail_sizing:
      id: fastoad.handling_qualities.tail_sizing
    hq_static_margin:
      id: fastoad.handling_qualities.static_margin
    wing_position:
      id: fastoad.loop.wing_position
    aerodynamics_highspeed:
      id: fastoad.aerodynamics.highspeed.legacy
    aerodynamics_lowspeed:
      id: fastoad.aerodynamics.lowspeed.legacy
    aerodynamics_takeoff:
      id: fastoad.aerodynamics.takeoff.legacy
    aerodynamics_landing:
      id: fastoad.aerodynamics.landing.legacy
      use_xfoil: false
  performance:
    id: fastoad.performances.mission
    propulsion_id: fastoad.wrapper.propulsion.rubber_engine
    # mission_file_path: ::sizing_breguet
    mission_file_path: ::sizing_mission
    out_file: ./flight_points.csv
    adjust_fuel: true
    is_sizing: true
  wing_area:
    id: fastoad.loop.wing_area

optimization: # This section is needed only if optimization process is run
  design_variables:
    - name: data:geometry:wing:aspect_ratio
      lower: 9.0
      upper: 18.0
  constraints:
    - name: data:geometry:wing:span
      upper: 60.0
  objective:
    - name: data:mission:sizing:needed_block_fuel
      scaler: 1.e-4

Now in details:

Custom module path

module_folders:

Provides the path where user can have his custom OpenMDAO modules. See section How to add custom OpenMDAO modules to FAST-OAD.

Input and output files

input_file: ./problem_inputs.xml
output_file: ./problem_outputs.xml

Specifies the input and output files of the problem. They are defined in the configuration file and DO NOT APPEAR in the command line interface.

Problem driver

driver: om.ScipyOptimizeDriver(tol=1e-2, optimizer='COBYLA')

This belongs the domain of the OpenMDAO framework and its utilization. This setting is needed for optimization problems. It is defined as in Python when assuming the OpenMDAO convention import openmdao.api as om.

For more details, please see the OpenMDAO documentation on drivers.

Solvers

model:
  nonlinear_solver: om.NonlinearBlockGS(maxiter=100, atol=1e-2)
  linear_solver: om.DirectSolver()

This is the starting point for defining the model of the problem. The model is a group of components. If the model involves cycles, which happens for instance when some outputs of A are inputs of B, and vice-versa, it is necessary to specify solvers as done above.

For more details, please see the OpenMDAO documentation on nonlinear solvers and linear solvers.

Problem definition

# Components can be put in sub-groups
subgroup:

  # A group can be set with its own solvers.

  nonlinear_solver: om.NonlinearBlockGS(maxiter=100, atol=1e-2, iprint=0)
  linear_solver: om.DirectSolver()

  geometry:
    # An OpenMDAO component is identified by its "id"
    id: fastoad.geometry.legacy
  weight:
    id: fastoad.weight.legacy
  mtow:
    id: fastoad.mass_performances.compute_MTOW
  hq_tail_sizing:
    id: fastoad.handling_qualities.tail_sizing
  hq_static_margin:
    id: fastoad.handling_qualities.static_margin
  wing_position:
    id: fastoad.loop.wing_position
  aerodynamics_highspeed:
    id: fastoad.aerodynamics.highspeed.legacy
  aerodynamics_lowspeed:
    id: fastoad.aerodynamics.lowspeed.legacy
  aerodynamics_takeoff:
    id: fastoad.aerodynamics.takeoff.legacy
  aerodynamics_landing:
    id: fastoad.aerodynamics.landing.legacy
    use_xfoil: false
performance:
  id: fastoad.performances.mission
  propulsion_id: fastoad.wrapper.propulsion.rubber_engine
  # mission_file_path: ::sizing_breguet
  mission_file_path: ::sizing_mission
  out_file: ./flight_points.csv
  adjust_fuel: true
  is_sizing: true
wing_area:
  id: fastoad.loop.wing_area

Components of the model can be modules, or sub-groups. They are defined as a sub-section of model:. Sub-sections and sub-components can be freely named by user.

A sub-group gathers several modules and can be set with its own solvers to resolve cycles it may contains.

Here above, a sub-group with geometric, weight, handling-qualities and aerodynamic modules is defined and internal solvers are activated. Performance and wing area computation modules are set apart.

A module is defined by its id: key that refers to the module registered name, but additional keys can be used, depending on the options of the module. The list of available options of a module is available through the list_modules sub-command (see How to get list of registered modules).

Optimization settings

This settings are used only when using optimization (see Run Multi-Disciplinary Optimization). They are ignored when doing analysis (see Run Multi-Disciplinary Analysis).

The section is identified by:

optimization:

Design variables

design_var:
  - name: data:geometry:wing:MAC:at25percent:x
    lower: 16.0
    upper: 18.0

Here are defined design variables (relevant only for optimization). Keys of this section are named after parameters of the OpenMDAO System.add_design_var() method

Several design variables can be defined.

Also, see How to get list of variables.

Objective function

objective:
  - name: data:mission:sizing:fuel

Here is defined the objective function (relevant only for optimization). Keys of this section are named after parameters of the OpenMDAO System.add_objective() method

Only one objective variable can be defined.

Also, see How to get list of variables.

Constraints

constraint:
  - name: data:handling_qualities:static_margin
    lower: 0.05
    upper: 0.1

Here are defined constraint variables (relevant only for optimization). Keys of this section are named after parameters of the OpenMDAO System.add_constraint() method

Several constraint variables can be defined.

Also, see How to get list of variables.

Using FAST-OAD through Command line

FAST-OAD can be used through shell command line or Python. This section deals with the shell command line, but if you prefer using Python, you can skip this part and go to Using FAST-OAD through Python.

The FAST-OAD command is fastoad. Inline help is available with:

$ fastoad -h

fastoad works through sub-commands. Each sub-command provides its own inline help using

$ fastoad <sub-command> -h

How to generate a configuration file

FAST-OAD can provide a ready-to use configuration file with:

$ fastoad gen_conf my_conf.yml

This generates the file my_conf.yml

How to get list of registered modules

If you want to change the list of components in the model in the configuration file, you need the list of available modules.

List of FAST-OAD modules can be obtained with:

$ fastoad list_modules

If you added custom modules in your configuration file my_conf.yml (see how to add custom OpenMDAO modules to FAST-OAD), they can be listed along FAST-OAD modules with:

$ fastoad list_modules my_conf.yml

You may also use the --verbose option to get detailed information on each module, including the available options, if any.

How to get list of variables

Once your problem is defined in my_conf.yml, you can get a list of the variables of your problem with:

$ fastoad list_variables my_conf.yml

How to generate an input file

The name of the input file is defined in your configuration file my_conf.yml. This input file can be generated with:

$ fastoad gen_inputs my_conf.yml

The generated file will be an XML file that contains needed inputs for your problem. Values will be the default values from module definitions, which means several ones will be “nan”. Actual value must be filled before the process is run.

If you already have a file that contains these values, you can use it to populate your new input files with:

$ fastoad gen_inputs my_conf.yml my_ref_values.xml

If you are using the configuration file provided by the gen_conf sub-command (see :ref`Generate conf file`), you may download our CeRAS01_baseline.xml and use it as source for generating your input file.

How to view the problem process

FAST-OAD proposes two graphical ways to look at the problem defined in configuration file. This is especially useful to see how models and variables are connected.

N2 diagram

FAST-OAD can use OpenMDAO to create a N2 diagram. It provides in-depth information about the whole process.

You can create a n2.html file with:

$ fastoad n2 my_conf.yml

XDSM

Using WhatsOpt as web service, FAST-OAD can provide a XDSM.

XDSM offers a more synthetic view than N2 diagram.

As it uses a web service, you need an internet access for this command, but you do not need to be a registered user on the WhatsOpt server.

You can create a xdsm.html file with:

$ fastoad xdsm my_conf.yml

Note: it may take a couple of minutes

Also, you may see WhatsOpt developer documentation to run your own server. In such case, you will address your server by using the --server option:

$ fastoad xdsm my_conf.yml --server https://the/address/of/my/WhatsOpt/server

How to run the problem

Run Multi-Disciplinary Analysis

Once your problem is defined in my_conf.yml, you can simply run it with:

$ fastoad eval my_conf.yml

Note: this is equivalent to OpenMDAO’s run_model()

Run Multi-Disciplinary Optimization

You can also run the defined optimization with:

$ fastoad optim my_conf.yml

Note: this is equivalent to OpenMDAO’s run_driver()

Using FAST-OAD through Python

The command line interface can generate Jupyter notebooks that show how to use the high-level interface of FAST-OAD.

To do so, type this command in your terminal:

$ fastoad notebooks

Then run the Jupyter server as indicated in the obtained message.