Configuration
#############

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

.. code-block:: json

    {
        "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:

.. code-block:: json

    "<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:

.. code-block:: json

    {    
        "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:

.. code-block:: json

    {
        "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:

.. code-block:: json

    {
        "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:

.. code-block:: json

   {
       "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:

.. code-block:: json

    {
        "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"
            }
        }
    }