Running a simulation

GUST takes one input file and, optionally, extra inputs on the command line:

mpirun -n 2 build-rel/gust inputs_file [key=value ...]

For a first run, follow Tutorial 1: A neutral surface layer.

What a run does

  1. Check the inputs (Input reference). If any check fails, the run lists every error and stops.

  2. Build the mesh and print its quality report (Terrain-following coordinates).

  3. Build the initial field (Initial conditions), or read it from a checkpoint (io.restart).

  4. Solve with the SIMPLEC stage when steady.stage = simplec (Solution algorithm), until the convergence criteria are met or steady.max_iterations is reached. One row of the iteration log is printed per iteration for the first ten, then every tenth (Output files).

  5. Write the output: a plotfile, the turbulence plotfile if io.turb_plot_file is set, and a checkpoint (Output files).

With the default steady.stage = none the run skips step 4: it writes the mesh and initial field and stops. This is useful for checking a new mesh or initial field.

Command-line inputs

Inputs after the file name are added to the file’s inputs. A key that the file already sets cannot be given again on the command line: a repeated key is refused.

Restarting

Set io.restart to a checkpoint directory (How-to guides has a step-by-step recipe).

  • The mesh and terrain inputs and the floating-point precision must match the checkpoint exactly. The box layout (mesh.max_grid_size) and the number of ranks may differ. The node heights may differ from this build’s by up to 64 ulp of the top level’s height (a checkpoint from another compiler; about 1.7e-11 m on a 1000 m deep mesh in double precision, 8 mm in single); the log says so.

  • init.* keys cannot be combined with io.restart: the checkpoint holds the state.

  • With grid sequencing, a restart continues level 0 only.

  • A restart with the SIMPLEC stage needs a checkpoint written by the stage. The checkpoint holds the solver history and the turbulence model’s state, so the continued run reproduces an uninterrupted one on the same ranks and box layout, bit for bit, over flat ground and over terrain.

  • The run stops if it would write a checkpoint with the name of the one it read.

AMReX runtime flags

AMReX reads its own amrex.* flags. The tests use these, which match the GPU CI settings:

amrex.the_arena_init_size=0 amrex.init_snan=1 amrex.fpe_trap_invalid=1 amrex.abort_on_unused_inputs=1

amrex.abort_on_unused_inputs=1 makes a misspelled amrex.* flag fail the run when it finishes (after the output is written). AppleClang builds do not trap floating-point exceptions; use a Linux GCC build for that check.