build simulation


The page defines the application programing interface specification for the simulation operation.


The command line interface for the simulation catagory of operations is:

usage: flashkit build simulation PATH NAME [<opt>...] [<flg>...]
Build and compile a FLASH simulation directory.

arguments:  
PATH        STRING  Specify a simulation directory contained in the FLASH source/Simulation/SimulationMain.
NAME        STRING  Specify a build directory basename; will be determined if not provided. 

options:
-D, --ndim       INT     Number of simulation dimensions (i.e., 2 or 3); defaults to 2.
-X, --nxb        INT     Number of grid points per block in the i direction; defaults to 64.
-Y, --nyb        INT     Number of grid points per block in the j direction; defaults to 64.
-Z, --nzb        INT     Number of grid points per block in the k direction; defaults to 64.
-g, --grid       STRING  Type of FLASH simulation grid used by the Grid Package; defaults to regular.
-p, --python     INT     Python version for the setup script; specifically use either 2 (legacy) or 3 (modern); defaults to 2.
-s, --site       STRING  Hostname of the machine on which setup is being run; Makefile should be in sites/SITE; defaults to manwe.ddns.net.
-o, --optimize   STRING  Flag for compilation and linking; using either optimized, debugging, or other; defaults to opt. 
-l, --shortcuts  LIST    Additional setup shortcuts (example: +rg) which begin with a plus symbol.  
-m, --flags      LIST    Additional setup options (example: -auto) which begin with a dash.
-n, --variables  DICT    Additional setup variable pairs (example: -nxb=12) which begin with a dash.
-u, --subspath   STRING  Path to SIMULATION within source/Simulation/SimulationMain; defaults to INavierStokes/zoso.
-b, --source     STRING  Path to the local FLASH source repository; defaults to ~/FLASH.
-j, --jobs       INT     Number of parallel processes to use when executing the make command; defaults to 1.

flags:
-H, --parallelIO  Use the parallel HDF5 Input/Output library.
-C, --compile     Compile the FLASH simulation build directory after it is constructed.
-B, --build       Force the building of the simulation directory, even if the directory exists. 
-F, --force       Force the compilation of the build directory, even if the binary is present. 
-I, --ignore      Ignore configuration file provided arguments, options, and flags.
-O, --options     Show the available options (i.e., defaults and config file format) and exit.
-h, --help        Show this message and exit.

Please consult the discussion on command line syntax for help in formating the above options (e.g., LIST or DICT).


The python interface for the simulation operation is accessed with the following code:

from flashkit import flash
...
flash.build.simulation(options=value, flags=True, ...)

The python interface specification for simulation is as follows:

simulation(**arguments: Any) → None

Python application interface for building and compiling FLASH simulation build directories.

This method creates a FLASH simulation setup command using options and specified defaults executes the build in a subprocess to enable the creation of FLASH simulation build directories. The build directories can also be compiled (even in parallel; e.g., ‘make -j 4’), if desired.

Keyword Arguments

  • path (str) – Specify a simulation directory contained in the FLASH source/Simulation/SimulationMain.

  • name (str) – Specify a build directory basename; will be determined if not provided.

  • ndim (int) – Number of simulation dimensions (i.e., 2 or 3).

  • nxb (int) – Number of grid points per block in the i direction.

  • nyb (int) – Number of grid points per block in the j direction.

  • nzb (int) – Number of grid points per block in the k direction.

  • grid (str) – Type of FLASH simulation grid used by the Grid Package (e.g., ‘regular’).

  • python (int) – Python version for the setup script; specifically use either 2 (legacy) or 3 (modern).

  • site (str) – Hostname of the machine on which setup is being run; Makefile should be in sites/SITE.

  • optimize (str) – Flag (e.g., ‘debug’) for compilation and linking; using either optimized, debugging, or other.

  • shortcuts (list) – Additional setup shortcuts (example: +rg) which begin with a plus symbol.

  • flags (list) – Additional setup options (example: -auto) which begin with a dash.

  • variables (dict) – Additional setup variable pairs (example: -nxb=12) which begin with a dash.

  • subpath (str) – Specify a Simulation directory sub-path to PATH within source/Simulation/SimulationMain.

  • source (str) – Specify a path to the local FLASH source repository.

  • jobs (int) – Number of parallel processes to use when executing the make command.

  • parallelIO (bool) – Use the parallel HDF5 Input/Output library.

  • compile (bool) – Compile the FLASH simulation build directory after it is constructed.

  • build (bool) – Force the building of the simulation directory, even if the directory exists.

  • force (bool) – Force the compilation of the build directory, even if the binary is present.

  • ignore (bool) – Ignore configuration file provided arguments, options, and flags.


The complete specification of library defaults values (as shown above) and mappings is as follows:

The following library defaults are provided for flashkit build simulation:

Options          Default Values
-------          --------------
grid             regular
jobs             1
optimize         opt
python           2
subpath          INavierStokes/zoso
source           ~/FLASH
site             manwe.ddns.net
ndim             2
nxb              64
nyb              64
nzb              64


The following outlines the general section options, which can be mapped
in the configuration file, that are provided for flashkit build simulation:

Options          flash.toml Sections and Options
-------          -------------------------------
source           [general.paths]
                 source = ...

site             [general.paths]
                 site = ...

ndim             [general.space]
                 ndim = ...

nxb              [general.space]
                 nxb = ...

nyb              [general.space]
                 nyb = ...

nzb              [general.space]
                 nzb = ...

Please consult the tutorial discussion on configuration file formating for help in specifying the above options in a flash.toml file and what mapping general options are, as well as the full specification on FlashKit library options.

build scaling flashkit create