Configuration

GBteSt uses a set of JSON configuration files to define the test cases it will launch. A test setup is described as follows:

{
    "name": "config/<file name>",
    "cases": "config/<file name>",
    "setup_config": "config/<file name>",

    "reference_executable": "config/<file name>",
    "comparison_executable": "config/<file name>"
}

The following fields are necessary:

name: the name of the test suite

cases: path to the configuration file containing the input files to test

setup_config: path to the file containing the setup configuration

*_executable: paths to the configuration files for the executables to test

Note

Note that all the configuration files must be placed in the config folder.

Input file configuration

Each regression test consists of many input files that are used to generate results to be compared. The list of the input files to use is stored in a JSON file and each input file is described as follows:

"<input name>": {
       "path": "<path>",
       "restart_file": {"path": "<path to restart file>"},
       "equilibrium_file": "<equilibrium file>"
   }

Each input file configuration block contains:

an input name, <input name>. It is used to recognize the case in the result summary.

an absolute path to the input file, <path>.

(optional) an absolute path to a restart file, <restart file>, if needed. Note the special syntax for the restart file that requires a JSON object and not just a plain path. If a path is provided it will be copied to the simulation folder and a myjob file will be created. Note that the name of the restart file must be of the form restart_XX.h5, where XX is the number of the restart.

(optional) an equilibrium file, <equilibrium file>, if needed.

An optional value can be set to null if not needed.

Example of two cases, one using a restart and the other a magnetic equilibrium:

{
    "in_restart_half_TCV": {
        "input_path": "inputs/in_restart_half_TCV",
        "restart_file": {
            "path": "~/src/gbs-test-files/restarts/restart_264.h5"
        },
        "equilibrium_file": null,
        "petscrc_file": null
    },
    "in_equilibrium": {
        "input_path": "inputs/in_equilibrium",
        "restart_file": null,
        "equilibrium_file": "~/src/gbs-test-files/equilibria/equilibrium",
        "petscrc_file": null
    }
}

Test setup configuration

The test setup configuration file can be used to configure the modules and the system on which the tests will be run. It is composed of the following fields:

{
    "runner_type": "<runner type>",
    "runner_options": {
        "<option1>": "<value1>",
        "<option2>": "<value2>"
    },

    "modules": ["<module1>", "<module2>"],
    "system": "<system config>"
}

The fields are the following:

runner_type defines which type of runner will be used for launching the jobs. Choices are slurm or local. The first will use the Slurm scheduler to launch the jobs, while the second will directly launch the jobs using mpiexec by default.
runner_options are the options to be passed to the runner. For example, the SlurmRunner needs to know the various #SBATCH options.
modules is a list of the module to load.
system defines various system options (not implemented yet).

An example to run on the SCITAS’ Jed cluster using the GNU stack is:

{
    "runner_type": "slurm",
    "runner_options": {
        "time": "00:05:00",
        "mem": "50G"
    },

    "modules": ["gcc/11.3.0", "openmpi/4.1.3", "openblas/0.3.20", "cmake/3.23.1", "hdf5/1.12.2-mpi", "petsc/3.17.1-mpi"],
    "system": null
}

An optional value can be set to null if not needed.

Executable configuration

The executable configuration file contains the following:

{
    "executable": {
        "name": "<name>",
        "path": "<path>",
        "compiler": "<compiler>",
        "compilation_options": "<options>",
        "git_hash": "<git hash>",
        "petscrc_file": "<petscrc file>"
    },
    "input_to_change": "<input_to_change>"
}

Each executable configuration contains:

an executable name, <name>. It is used to recognize the executable in the result summary.

an absolute path to the binary, <path>.

(optional) a compiler name, <compiler>, used to describe the executable.

(optional) the compilation options, <options>, used to distinguish between two executables built with the same compiler.

(optional) a Git hash of the code version used to build the executable, <git hash>.

(optional) a petscrc file, <petscrc file>. If not provided, it will take the one in config by default.

(optional) a dictionary, <input_to_change> containing the input to change from the original namelists.

If you don’t need one option, you can assign it the null value.

An example of an executable with parameters to change from the original namelist is:

{
    "executable": {
        "name": "gbs_compare",
        "path": "~/src/gbs/build_compare/gbs",
        "compiler": null,
        "compilation_options": null,
        "git_hash": "er43hakz9"
    },
    "input_to_change": {
        "basic": {
            "dt": 1e-10,
            "nlres": false
        },
        "equil_par": {
            "B_type": "DivRec"
        }
    }
}