5.5 Config Files

5.5.1 Configuration file syntax

Configuration files come in two syntactic flavors: static text and python. In static mode, configuration directives are listed as lines in a plain text file. This mode is the most readable and intuitive of the two, but it lacks flexibility. The python mode has been introduced to circumvent this inflexibility by allowing the configuration file author to specify the configuration directives as a function of the setup variables with a python procedure. This allows the content of each directive and the number of directives in total to be amenable to general programming.

The rule the setup script uses for deciding which flavor of configuration file it's dealing with is simple. Python configuration files have as their first line ##python:genLines. If the first line does not match this string, then static mode is assumed and each line of the file is interpreted verbatim as a directive.

If python mode is triggered, then the entire file is considered as valid python source code (as if it were a .py). From this python code, a function of the form def genLines(setupvars) is located and executed to generate the configuration directives as an array (or any iterable collection) of strings. The sole argument to genLines is a dictionary that maps setup variable names to their corresponding string values.

As an example, here is a configuration file in python mode that registers runtime parameters named indexed_parameter_x where x ranges from 1 to NP and NP is a setup line variable.

##python:genLines


# We define genLines as a generator with the very friendly "yield" syntax.
# Alternatively, we could have genLines return an array of strings or even
# one huge multiline string.
def genLines(setupvars):
    # emit some directives that dont depend on any setup variables
    yield """
REQUIRES Driver
REQUIRES physics/Hydro
REQUIRES physics/Eos
"""
    # read a setup variable value from the dictionary
    np = int(setupvars("NP")) # must be converted from a string
    # loop from 0 to np-1
    for x in xrange(np):
        yield "PARAMETER indexed_parameter_%d REAL 0." % (x+1)

When setting up a problem with NP=5 on the setup command line, the following directives will be processed:

REQUIRES Driver
REQUIRES physics/Hydro
REQUIRES physics/Eos
PARAMETER indexed_parameter_1 REAL 0.
PARAMETER indexed_parameter_2 REAL 0.
PARAMETER indexed_parameter_3 REAL 0.
PARAMETER indexed_parameter_4 REAL 0.
PARAMETER indexed_parameter_5 REAL 0.

5.5.2 Configuration directives

# comment
A comment. Can appear as a separate line or at the end of a line.

DEFAULT sub-unit
Every unit and sub-unit designates one implementation to be the “default”, as defined by the keyword DEFAULT in its Config file. If no specific implementation of the unit or its sub-units is selected by the application, the designated default implementation gets included. For example, the Config file for the EosMain specifies Gamma as the default. If no specific implementation is explicitly included (i.e., INCLUDE physics/Eos/EosMain/Multigamma), then this command instructs setup to include the Gamma implementation, as though INCLUDE physics/Eos/EosMain/Gamma had been placed in the Units file.

EXCLUSIVE implementation...
Specifies a list of implementations that cannot be included together. If no EXCLUSIVE instruction is given, it is perfectly legal to simultaneously include more than one implementation in the code. Using “EXCLUSIVE *” means that at most one implementation can be included.

CONFLICTS unit1[/sub-unit[/implementation...]] ...
Specifies that the current unit, sub-unit, or specific implementation is not compatible with the list of units, sub-units or other implementations that follows. setup issues an error if the user attempts a conflicting unit configuration.

REQUIRES unit[/sub-unit[/implementation...]] [ OR unit[/sub-unit...]]...
Specifies a unit requirement. Unit requirements can be general, without asking for a specific implementation, so that unit dependencies are not tied to particular algorithms. For example, the statement REQUIRES physics/Eos in a unit's Config file indicates to setup that the physics/Eos unit is needed, but no particular equation of state is specified. As long as an Eos implementation is included, the dependency will be satisfied. More specific dependencies can be indicated by explicitly asking for an implementation. For example, if there are multiple species in a simulation, the Multigamma equation of state is the only valid option. To ask for it explicitly, use REQUIRES physics/Eos/EosMain/Multigamma. Giving a complete set of unit requirements is helpful, because setup uses them to generate the units file when invoked with the -auto option.

REQUESTS unit[/sub-unit[/implementation...]]
Requests that a unit be added to the Simulation. All requests are upgraded to a “REQUIRES” if they are not negated by a "-without-unit" option from the command line. If negated, the REQUEST is ignored. This can be used to turn off profilers and other “optional” units which are included by default.

SUGGEST unitname unitname ...
Unlike REQUIRES, this keyword suggests that the current unit be used along with one of the specified units. The setup script will print details of the suggestions which have been ignored. This is useful in catching inadvertently omitted units before the run starts, thus avoiding a waste of computing resources.

PARAMETER name type [CONSTANT] default [range-spec]
Specifies a runtime parameter. Parameter names are unique up to 20 characters and may not contain spaces. Admissible types include REAL, INTEGER, STRING, and BOOLEAN. Default values for REAL and INTEGER parameters must be valid numbers, or the compilation will fail. Default STRING values must be enclosed in double quotes ("). Default BOOLEAN values must be .true. or .false. to avoid compilation errors. Once defined, runtime parameters are available to the entire code. Optionally, any parameter may be specified with the CONSTANT attribute (e.g., PARAMETER foo REAL CONSTANT 2.2). If a user attempts to set a constant parameter via the runtime parameter file, an error will occur.

The range specification is optional and can be used to specify valid ranges for the parameters. The range specification is allowed only for REAL, INTEGER, STRING variables and must be enclosed in '[]'.

For a STRING variable, the range specification is a comma-separated list of strings (enclosed in quotes). For a INTEGER, REAL variable, the range specification is a comma-separated list of (closed) intervals specified by min ... max, where min and max are the end points of the interval. If min or max is omitted, it is assumed to be $-\infty$ and $+\infty$ respectively. Finally val is a shortcut for val ... val. For example

PARAMETER pres REAL 1.0 [ 0.1 ... 9.9, 25.0 ... ]
PARAMETER coords STRING "polar" ["polar","cylindrical","2d","3d"]

indicates that pres is a REAL variable which is allowed to take values between 0.1 and 9.9 or above 25.0. Similarly coords is a string variable which can take one of the four specified values.

D parameter-name comment
Any line in a Config file is considered a parameter comment line if it begins with the token D. The first token after the comment line is taken to be the parameter name. The remaining tokens are taken to be a description of the parameter's purpose. A token is delineated by one or more white spaces. For example,

D SOME_PARAMETER The purpose of this parameter is whatever

If the parameter comment requires additional lines, the & is used to indicate continuation lines. For example,

D SOME_PARAMETER The purpose of this parameter is whatever
D &              This is a second line of description

You can also use this to describe other variables, fluxes, species, etc. For example, to describe a species called "xyz", create a comment for the parameter “xyz_species”. In general the name should be followed by an underscore and then by the lower case name of the keyword used to define the name.

Parameter comment lines are special because they are used by setup to build a formatted list of commented runtime parameters for a particular problem. This information is generated in the file setup_params in the object directory.

VARIABLE name [TYPE: vartype] [eosmap-spec]
Registers variable with the framework with name name and a variable type defined by vartype. The setup script collects variables from all the included units, and creates a comprehensive list with no duplications. It then assigns defined constants to each variable and calculates the amount of storage required in the data structures for storing these variables. The defined constants and the calculated sizes are written to the file Flash.h.

The possible types for vartype are as follows:

PER_VOLUME
This solution variable is represented in conserved form, i.e., it represents the density of a conserved extensive quantity. The prime example is a variable directly representing mass density. Energy densities, momentum densities, and partial mass densities would be other examples (but these quantities are usually represented in PER_MASS form instead).
PER_MASS
This solution variable is represented in mass-specific form, i.e., it represents quantities whose nature is $\hbox{extensive quantity} \mathop{\mathrm{per}} \hbox{mass unit}$ . Examples are specific energies, velocities of material (since they are equal to momentum per mass unit), and abundances or mass fractions (partial density divided by density).
GENERIC
This is the default vartype and need not be specified. This type should be used for any variables that do not clearly belong to one of the previous two categories.

In the current version of the code, the TYPE attribute is only used to determine which variables should be converted to conservative form for certain Grid operations that may require interpolation (i.e., prolongation, guardcell filling, and restriction) when one of the runtime parameters
convertToConsvdForMeshCalls or convertToConsvdInMeshInterp is set true. Only variables of type PER_MASS are converted: values are multiplied cell-by-cell with the value of the "dens" variable, and potential interpolation results are converted back by cell-by-cell division by "dens" values after interpolation.

Note that therefore

variable types are irrelevant for uniform grids,
variable types are irrelevant if neither convertToConsvdForMeshCalls nor
convertToConsvdInMeshInterp is true, and
variable types (and conversion to and from conserved form) only take effect if a
```
VARIABLE dens ...
```
exists.

An eosmap-spec has the syntax EOSMAP: eos-role $\vert$ ( [EOSMAPIN: eos-role] [EOSMAPOUT: eos-role ]), where eos-role stands for a role as defined in Eos_map.h. These roles are used within implementations of the Eos_wrapped interface, via the subroutines Eos_getData and Eos_putData, to map variables from Grid data structures to the eosData array that Eos understands, and back. For example,

VARIABLE eint TYPE: PER_MASS EOSMAPIN: EINT

means that within Eos_wrapped, the EINT_VAR component of unk will be treated as the grid variable in the “internal energy” role for the purpose of constructing input to Eos, and

VARIABLE gamc EOSMAPOUT: GAMC

means that within Eos_wrapped, the GAMC_VAR component of unk will be treated as the grid variable in the EOSMAP_GAMC role for the purpose of returning results from calling Eos to the grid. The specification

VARIABLE pres EOSMAP: PRES

has the same effect as

VARIABLE pres EOSMAPIN: PRES EOSMAPOUT: PRES

Note that not all roles defined in Eos_map.h are necessarily meaningful or actually used in a given Eos implementation. An eosmap-spec for a VARIABLE is only used in an Eos_wrapped invocation when the optional gridDataStruct argument is absent or has a value of CENTER.

MULTIFLUID name Registers pairs of variables with names MFA_name and MFB_name in the framework, intended to be used with the volume-of-fluid interface capturing scheme. The setup script collects multifluid variables from all the included units, and creates a comprehensive list with no duplications. It then assigns defined constants to each variable and calculates the amount of storage required in the data structures for storing these variables. The defined constants and the calculated sizes are written to the file Flash.h.

FACEVAR name [eosmap-spec]
This keyword has the same meaning for face-centered variables, that VARIABLE does for cell-centered variables. It allocates space in the grid data structure that contains face-centered physical variables for “name”. See Sec:FlashHdimensions for more information

For eosmap-spec, see above under VARIABLE. An eosmap-spec for FACEVAR is only used when Eos_wrapped is called with an optional gridDataStruct argument of FACEX, FACEY, or FACEZ.

FLUX name
Registers flux variable name with the framework. When using an adaptive mesh, flux conservation is needed at fine-coarse boundaries. PARAMESH uses a data structure for this purpose, the flux variables provide indices into that data structure. See Sec:FlashHfluxes for more information.

EDGE name
Registers an edge variable for use in the unit that declarse it. This maps the the paramesh nvaredge variable through the preprocessor variable FLASH_NEDGE_VAR in Flash.h. The total number of edge variables is taken as the max over all units the total number of requested edge variables from each individual unit.

SCRATCHCENTERVAR name [eosmap-spec]
This keyword is used in connection with the grid scope scratch space for cell-centered data supported by FLASH. It allows the user to ask for scratch space with “name”. The scratch variables do not participate in the process of guardcell filling, and their values become invalid after a grid refinement step. While users can define scratch variables to be written to the plotfiles, they are not by default written to checkpoint files. Note this feature wasn't available in FLASH2. See Sec:FlashHscratch for more information.

SCRATCHFACEVAR name [eosmap-spec]
This keyword is used in connection with the grid scope scratch space for face-centered data, it is identical in every other respect to SCRATCHCENTERVAR.

SCRATCHVAR name [eosmap-spec]
This keyword is used for specifying instances of general purpose grid scope scratch space. The same space can support cell-centered as well as face-centered data. Like other scratch data structures, the variables in this data structure can also be asked with “name” and do not participate in guardcell filling.

For eosmap-spec, see above under VARIABLE. An eosmap-spec for SCRATCHVAR is only used when Eos_wrapped is called with an optional gridDataStruct argument of SCRATCH.

MASS_SCALAR name [RENORM: group-name] [eosmap-spec]
If a quantity is defined with keyword MASS_SCALAR, space is created for it in the grid “unk” data structure. It is treated like any other variable by PARAMESH, but the hydrodynamic unit treats it differently. It is advected, but other physical characteristics don't apply to it. If the optional “RENORM” is given, this mass-scalar will be added to the renormalization group of the accompanying group name. The hydrodynamic solver will renormalize all mass-scalars in a given group, ensuring that all variables in that group will sum to 1 within an individual cell. See Sec:FlashHvariables

For eosmap-spec, see above under VARIABLE. An eosmap-spec for a MASS_SCALAR may be used in an Eos_wrapped invocation when the optional gridDataStruct argument is absent or has a value of CENTER.

Avoid Confusion!: It is inadvisable to name variables, species, and mass scalars with the same prefix, as post-processing routines have difficulty deciphering the type of data from the output files. For example, don't create a variable “temp” to hold temperature and a mass scalar “temp” indicating a temporary variable. Although the Flash.h file can distinguish between these two types of variables, many plotting routines cannot.

PARTICLETYPE particle-type INITMETHOD initialization-method MAPMETHOD map-method ADVMETHOD time-advance-method
This keyword associates a particle type with mapping and initialization sub-units of Particles unit to operate on this particle type during the simulation. Here, map-method describes the method used to map the particle properties to and from the mesh (see Sec:Particles Mapping), initialization-method describes the method used to distribute the particles at initialization, and time-advance-method describes the method used to advance the associated particle type in time (see Sec:Particles Integration, and in general Sec:ParticlesUsing). This keyword has been introduced to facilitate inclusion of multiple particle types in the same simulation. It imposes certain requirements on the use of the ParticlesMapping and ParticlesInitialization subunits. Particles (of any type, whether called passive or anything else) do not have default methods for initialization, mapping, or time integration, so a PARTICLETYPE directive in a Config file (or an equivalent -particlemethods= setup option, see setupclf:particlemethods) is the only way to specify the appropriate implementations of the Particles subunits to be used. The declaration should be accompanied by appropriate “REQUESTS” or “REQUIRES” directives to specify the paths of the appropriate subunit implementation directories to be included. For clarity, our technique has been to include this information in the simulation directory Config files only. All the currently available mapping and initialization methods have a corresponding identifier in the form of preprocessor definition in Particles.h. The user may select any particle-type name, but the map-method, initialization-method and time-advance-method must correspond to existing identifiers defined in Particles.h. This is necessary to navigate the data structure that stores the particle type and its associated mapping and initialization methods. Users desirous of adding new methods for mapping or initialization should also update the Particles.h file with additional identifiers and their preprocessor definitions. Note, it is possible to use the same methods for different particle types, but each particle type name must only appear once. Finally, the Simulations Config file is also expected to request appropriate implementations of mapping and initialization subunits using the keyword REQUESTS, since the corresponding Config files do not specify a default implementation to include. For example, to include passive particle types with Quadratic mapping, Lattice initialization,and Euler for advancing in time the following code segment should appear in the Config file of the Simulations directory.

PARTICLETYPE passive INITMETHOD lattice MAPMETHOD quadratic ADVMETHOD Euler
REQUIRES Particles/ParticlesMain
REQUESTS Particles/ParticlesMain/passive/Euler
REQUESTS Particles/ParticlesMapping/Quadratic
REQUESTS Particles/ParticlesInitialization/Lattice

PARTICLEPROP name type
This keyword indicates that the particles data structure will allocate space for a sub-variable “NAME_PART_PROP.” For example if the Config file contains

PARTICLEPROP dens

then the code can directly access this property as

particles(DENS_PART_PROP,1:localNumParticles) = densInitial

type may be REAL or INT, however INT is presently unused. See Sec:FlashHparticles for more information and examples.

PARTICLEMAP TO partname FROM vartype varname
This keyword maps the value of the particle property partname to the variable varname. vartype can take the values VARIABLE, MASS_SCALAR, SPECIES, FACEX, FACEY, FACEZ, or one of SCRATCH types (SCRATCHVAR/ SCRATCHCENTERVAR, SCRATCHFACEXVAR. SCRATCHFACEYVAR, SCRATCHFACEZVAR) These maps are used to generate Simulation_mapParticlesVar, which takes the particle property partname and returns varname and vartype. For example, to have a particle property tracing density:

PARTICLEPROP dens REAL
PARTICLEMAP TO dens FROM VARIABLE dens

or, in a more advanced case, particle properties tracing some face-valued function Mag:

PARTICLEPROP Mag_x REAL
PARTICLEPROP Mag_y REAL
PARTICLEPROP Mag_z REAL
PARTICLEMAP TO Mag_x FROM FACEX Mag
PARTICLEMAP TO Mag_y FROM FACEY Mag
PARTICLEMAP TO Mag_z FROM FACEZ Mag

Additional information on creating Config files for particles is obtained in Sec:Particle Properties.

SPECIES name [TO number of ions]
An application that uses multiple species uses this keyword to define them. See Sec:FlashHvariables for more information. The user may also specify an optional number of ions for each element, name. For example, SPECIES o TO 8 creates 9 spaces in unk for Oxygen, that is, a single space for Oxygen and 8 spaces for each of its ions. This is relevant to simulations using the ionize unit. (Omitting the optional TO specifier is equivalent to specifying TO 0).

DATAFILES wildcard
Declares that all files matching the given wildcard in the unit directory should be copied over to the object directory. For example,

DATAFILES *.dat

will copy all the “.dat” files to the object directory.

KERNEL [subdir]
Declares that all subdirectories must be recursively included. This usually marks the end of the high level architecture of a unit. Directories below it may be third party software or a highly optimized solver, and are therefore not required to conform to FLASH architecture.

Without a subdir, the current directory (i.e., the one containing the Config file with the KERNEL keyword) is marked as a kernel directory, so code from all its subdirectories (with the exception of subdirectories whose name begins with a dot) is included. When a subdir is given, then that subdirectory must exist, and it is treated as a kernel directory in the same way.

Note that currently the setup script can process only one KERNEL directive per Config file.

LIBRARY name [target]
Specifies a library requirement. Different FLASH units require different libraries, and they must inform setup so it can link the libraries into the executable. Some valid library names are HDF5, MPI. Support for external libraries can be added by modifying the site-specific Makefile.h files to include appropriate Makefile macros. It is possible to use internal libraries, as well as switch libraries at setup time. To use these features, see
Library-HOWTO.
target is used when building with cmake to specify a target that will be linked to the FLASH executable.

LINKIF filename unitname
Specifies that the file filename should be used only when the unit unitname is included. This keyword allows a unit to have multiple implementations of any part of its functionality, even down to the kernel level, without the necessity of creating children for every alternative. This is especially useful in Simulation setups where users may want to use different implementations of specific functions based upon the units included. For instance, a user may wish to supply his/her own implementation of Grid_markRefineDerefine.F90, instead of using the default one provided by FLASH. However, this function is aware of the internal workings of Grid, and has different implementations for different grid packages. The user could therefore specify different versions of his/her own file that are intended for use with the different grids. For example, adding

LINKIF Grid_markRefineDerefine.F90.ug Grid/GridMain/UG
 LINKIF Grid_markRefineDerefine.F90.pmesh Grid/GridMain/paramesh

to the Config file ensures that if the application is built with UG, the file
Grid_markRefineDerefine.F90.ug will be linked in as Grid_markRefineDerefine.F90, whereas if it is built with Paramesh2 or Paramesh4.0 or Paramesh4dev, then the file Grid_markRefineDerefine.F90.pmesh will be linked in as Grid_markRefineDerefine.F90. Alternatively, the user may want to provide only one implementation specific to, say, PARAMESH. In this case, adding

LINKIF Grid_markRefineDerefine.F90 Grid/GridMain/paramesh

to the Config file ensures that the user-supplied file is included when using PARAMESH (either version), while the default FLASH file is included when using UG.

PPDEFINE sym1 sym2 ...
Instructs setup to add the PreProcessor symbols SYM1 and SYM2 to the generated Flash.h. Here SYM1 is sym1 converted to uppercase. These pre-process symbols can be used in the code to distinguish between which units have been used in an application. For example, a Fortran subroutine could include

#ifdef FLASH_GRID_UG
  ug specific code
#endif


#ifdef FLASH_GRID_PARAMESH3OR4
  pm3+ specific code
#endif

By convention, many preprocessor symbols defined in Config files included in the FLASH code distribution start with the prefix “FLASH_”.

USESETUPVARS var1, var2, ...
This tells setup that the specified “Setup Variables” are being used in this Config file. The variables initialize to an empty string if no values are specified for them. Note that commas are required if listing several variables.

CHILDORDER child1 child2 ...
When setup links several implementations of the same function, it ensures that implementations of children override that of the parent. Its method is to lexicographically sort all the names and allow implementations occurring later to override those occurring earlier. This means that if two siblings implement the same code, the names of the siblings determine which implementation wins. Although it is very rare for two siblings to implement the same function, it does occur. This keyword permits the Config file to override the lexicographic order by one preferred by the user. Lexicographic ordering will prevail as usual when deciding among implementations that are not explicitly listed.

GUARDCELLS num
Allows an application to choose the stencil size for updating grid points. The stencil determines the number of guardcells needed. The PPM algorithm requires

guardcells, hence that is the default value. If an application specifies a smaller value, it will probably not be able to use the default monotonic AMR Grid interpolation; see the -gridinterpolation setup flag for additional information.

SETUPERROR error message
This causes setup to abort with the specified error message. This is usually used only inside a conditional IF/ENDIF block (see below).

IF, ELSEIF, ELSE, ENDIF
A conditional block is of the following form:

IF cond
   ...
ELSEIF cond
   ...
ELSE
   ...
ENDIF

where the ELSEIF and ELSE blocks are optional. There is no limit on the number of ELSEIF blocks. “...” is any sequence of valid Config file syntax. The conditional blocks may be nested. “cond” is any boolean valued Python expression using the setup variables specified in the USESETUPVARS.

NONREP unktype name localmax globalparam ioformat
Declares an array of UNK variables that will be partitioned across the replicated meshes. Using various preprocessor macros in Flash.h each copy of the mesh can determine at runtime its own subset of indexes into this global array. This allows an easy form of parallelism where regular "replicated" mesh variables are computed redundantly across processors, but the variables in the "non-replicated" array are computed in parallel.

unktype: must be either MASS_SCALAR or VARIABLE
name: the name of this variable array. It is suggested that it be all capital letters, and must conform to what the C preprocessor will consider as a valid symbol for use in a #define statement.
localmax: a positive integer specifying the maximum number of elements from the global variable array a mesh can hold. This is the actual number of UNK variables that are allocated on each processor, though not all of them will necessarily be used.
globalparam: the name of a runtime parameter which dictates the size of this global array of variables.
ioformat: a string representing how the elements of the array will be named when written to the output files. The question mark character ? is used as a placeholder for the digits of the array index. As an example, the format string x??? will generate the dataset names x001, x002, x003, etc. This string must be no more than four characters in length.

The number of meshes is dictated by the runtime parameter meshCopyCount. The following constraint must be satisfied or FLASH will fail at runtime:

$\displaystyle globalparam \le meshCopyCount * localmax$

The reason for this restriction is that localmax is the maximum number of array elements a mesh can be responsible for, and meshCopyCount is the number of meshes, so their product bounds the size of the array.

Example:

Config file:

NONREP MASS_SCALAR A 4 numA a???
NONREP MASS_SCALAR B 5 numB b???

flash.par file:

meshCopyCount = 3
numA = 11
numB = 15

In this case two non-replicated mass-scalar arrays are defined, A and B. Their lengths are specified by the runtime parameters numA and numB respectively. numB is set to its maximum value of , but numA is one less than its maximum value of so at runtime one of the meshes will not have all of its UNK variables in use. The dataset names generated by IO will take the form a001 ...a011 and b001 ...b015.

The preprocessor macros defined in Flash.h for these arrays will have the prefixes A_ and B_ respectively. For details about these macros and how they will distribute the array elements across the meshes see Sec:FlashHnonrep.