Reading time 5min


Photo Maxwell Hunt. High performance computations usually comes with high fidelity setups, i.e. literally hundreds of control parameters. One can rely on training highly skilled end-users … or can provide some helper tools.

Lost in translation?

An engineer expresses his problems with his own jargon, different from the jargon of the physicist who provides the software to do the simulation. Both need long discussions and some trial-and-error to agree on the correct setup.

When the number of end-users is rising, the translation and setup generation process must be automated. We will see the strategy used in pyAVBP, the Python helper tool of AVBP to provide Graphical User Interfaces (GUIs) to engineers, while keeping open expert controls on the setups.

Translate, then generate

Before jumping into GUIs and expert mode control, we need to define three levels of informations:

  1. The Short d.o.f is the original definition of the problem. This data is expressed in the jargon of the end-used. For example, the operating pressure of a combustion chamber, in propulsion, will be the P40, (to avoid confusion with P30 or P41, which are also operating pressures, but for other parts of the device.). The format to store this is not important.

  2. The Extended d.o.f. is the translation of the problems in the jargon of the software. Often, one element of the Short d.o.f influences several elements of the Extended d.o.f. . For example the operating pressure is used for the initial field pressure init_press, the outlet pressure target press_outlet, the combustion modeling setup press_comb. It also can set indirectly other aspects, such as an inlet injection density rho_inj where only temperature was specified. Again the storing format is not important

  3. The full setup is the actual input files expected by the software. For AVBP, there is the main input file run_params, the initial solution init.h5, the boundaries parameters asciiBound and binary targets solutBounds, several databases mixture_databasesand species_database, plus other additional files depending on the case.

We will use a Translator process to go from Short d.o.f to Extended d.o.f., then a Generator process to go from Extended d.o.f. to full setup. Keep the following schema in mind.

            ┌──────────┐                  ┌─────────┐
  Short  ───┤Translator├────► Extended ───┤Generator├───► Full
  d.o.f     └──────────┘       d.o.f      └─────────┘     Setup
(Engineer)                  (AVBP jargon)          (AVBP Input Files)
GUI, GUI-Batch, and Scenario

pyAVBP provides several command lines:

> pyavbp gui combu -f myproject.yml

This is to launch one of the Graphical user Interfaces , here combu, on a project myproject.yml. This project is a short d.o.f. Finishing the GUI will trigger both translation and generation.

> pyavbp gui combu --file myproject.yml -batch RUN_007

This “replay” the GUI in batch mode. Using a GUI in batch mode will trigger both translation and generation with a user defined target folder. With batch, you can go from the short d.o.f directly to the full setup.

> pyavbp scenario combu  myproject_extended.yml RUN_007

This command starts with the extended d.o.f , generated by the GUI. Using the scenario trigger only the generation step. One can use this command to change experts parameters in the extended d.o.f and replay the full setup.

A small sketch sums this up:

            ┌──────────┐                  ┌─────────┐
  Short  ───┤Translator├────► Extended ───┤Generator├───► Full
  d.o.f     └──────────┘       d.o.f      └─────────┘     Setup

                          GUI (Batch mode)


Worked example : a combustion case

An illustration of the previous concepts with a real-life example. We start with the setup of a simple combustion case. The full setup can be read here. The end-user can perform this task with the GUI spawned by >pyavbp gui combu.


The GUI spawned by >pyavbp gui combu

An example of the short d.o.f.

The memory of this GUI is the short d.o.f. of the problem. A glance at the actual content, focusing at the beginning of the boundaries section looks like this :

    - bnd_gas:
          mass_flow: 0.1
            relax_coeff_inlet_relax: 200.0
      name: _Inlet
    - bnd_gas:
          pressure: 101325.0
          relax_coeff_p: 50.0
      name: _Outlet
    - bnd_gas:
          perio_axi_sign: negative
      name: _PerioLeft
    - bnd_gas:
          perio_axi_sign: positive
      name: _PerioRight
    - bnd_gas:
        wall_law_adiab: null
      name: _WallIn1

We can also look this setup using a circular packing to grasp the nesting of the data:


Circular packing of the d.o.f. short. The main groups map perfectly the tabs of the GUI

An example of the extended d.o.f.

When the user hit the process finish of the last tab, the d.o.f. extended is dumped on the disk, and the setup is generated. We can again look at the content of the extended d.o.f for a similar section:

- bnd_gas:
        mass_flow: 0.1
          N2: 0.7669
          O2: 0.2331
        temperature: 300.0
      relax_coeff_rhoun: 200.0
      relax_coeff_t: 200.0
      relax_coeff_ut: 200.0
      relax_coeff_y: 200.0
  name: Inlet
- bnd_gas:
        pressure: 101325.0
      relax_coeff_p: 50.0
  name: Outlet
- bnd_gas:
      periodic_axi_angle: null
      periodic_axi_sign: negative
  name: PerioLeft
- bnd_gas:
      periodic_axi_angle: null
      periodic_axi_sign: positive
  name: PerioRight
- bnd_gas:
    wall_law_adiab: {}
  name: WallIn1

The experienced AVBP user will recognize a mapping of the asciiBound and gensolutbound input file, expressed in a YAML format.

A bit further, there are also these informations

  active: false
  delta: 0.001
  - 0.0
  - 0.0
  - 0.0
  radius: 0.01
  type_gasout: spherical
- exponent: 8
  name: Inlet

The experienced AVBP user will recognize some inputs for the gasout step, as well as expert parameters for the genprofile step, which are both pre-processing tools.

Finally the content of main control file of AVBP, run.params is available:

    ncell_group: 100
  ignition-energy-deposition: null
  ignition-soft: null
    artificial_viscosity_2nd_order: 0.4
    artificial_viscosity_4th_order: 0.005
    artificial_viscosity_model: jameson_species
    cfl: 0.7
    combustion_model: tf
    convection_scheme: lw
    fourier: 0.1
    les_model: sigma
    prandtl_turb: 0.65
    schmidt_turb: 0.65

Getting back to the big picture, the circular packing of the *d.o.f. extended looks like this :


Circular packing of the d.o.f. extended. Unsurprisingly, the run_params and bounds groups gather most of the data

Using translation and generation in a script.

If you look at the callback of the combu last tab , you will find the following structure :

            ┌──────────┐                  ┌─────────┐
  Short  ───┤Translator├────► Extended ───┤Generator├───► Full
  d.o.f     └──────────┘       d.o.f      └─────────┘     Setup




You can see in the following code snippet how the functions are articulated:

def batch_process_finish(
    """Create an AVBP combu setup from the short dof version.

    The short dof from GUI is expanded with combu_avbp_setup_data().
    The extended dof is passed to the scenario  complex_combu().

    :param folder_name: str, the folder to store the new setup.
    :param overwrite: boolean, allow overwrite of a project.
    :param copy_mesh: boolean, make a copy of the mesh near the project.
    :param dump_extented_yaml: boolean, save a copy of the extended dof.
    :param print_tree: boolean, print the directory tree generated in the STDOUT.

    dof_extended = combu_avbp_setup_data(dof_in)


    dir_tree = scenario_combu(



The content of d.o.f. shorts and extended will both change in the future. The customers will add more precise controls on their setups, and remove seldom used options (still available in expert mode). With time, more and more explicit parameters will be added to the d.o.f extended.

Like this post? Share on: TwitterFacebookEmail

Antoine Dauptain is a research scientist focused on computer science and engineering topics for HPC.

Keep Reading





Stay in Touch