Solver Options
--------------


Option propagation
^^^^^^^^^^^^^^^^^^

Be default, multi-case solvers allow for the automatic propagation of the unused options passed to the solver to each individual case.
Some solver options are consumed (namely the ``tmp_dir``, ``output_dir`` and ``parallel`` options), but any other options are passed directly to all the cases in the configuration file.
For example, the following YAML file:

.. code-block:: yaml

    solver:
        name: your_fancy_solver
        parallel: 2
        foo: bar
        case_1:
            case_option: 2
        case_2:
            case_option: 3

Is equivalent to:

.. code-block:: yaml

    solver:
        name: your_fancy_solver
        parallel: 2
        case_1:
            case_option: 2
            foo: bar
        case_2:
            case_option: 3
            foo: bar

This behaviour passing common options to all cases in the solver options, thereby diminishing the number of entries that need to be specified in the input file.
Nonetheless, beware of the naming of each option and refer to [solver docs] to find which options each solver consumes.


Verbosity levels
^^^^^^^^^^^^^^^^

Most solvers support manually setting the verbosity level of each simulation.
This can be controlled by setting the ``verbosity`` option to the solver, which has the following possible values:

* ``none`` (default) - all the output from the solver is suppressed.
* ``file`` - all the output from the solver is redirected to a set of files.
  The standard output is sent to the ``stdout`` file in the ``solver`` directory of the output, and the error stream is sent to the ``stderr`` file in the same directory.
  Output to the terminal is suppressed.
* ``error`` - standard output is redirected to a file (in the same location as in the ``file`` option), whilst the error stream is not suppressed --- it is printed to te output of the program.
* ``all`` - all of the solver outputs are shown in the terminal --- they are not redirected nor suppressed.

By default, all output is suppressed (the ``none`` option).
Nonetheless, when debugging optimisation runs and the setup of the problem, showing the output of the solver may be of interest.


Custom input file generators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For solvers based on input files, sometimes the default template parameter substitution may not suffice.
As an example, the optimisation of geometrical parameters may require the re-generation of the numerical discretisation of the problem.
To increase the flexibility in these cases, we may optionally specify an alternative input file generation routine.
Consider the following example:

.. code-block:: yaml

  solver:
    name: input_file_solver
    cases:
      sample_case:
        generator:
          script: sample_generator.py
          class: SampleInputGenerator
        fields:
          sample_output:
            name: sample_reader

With this YAML file, a single case named ``sample_case`` is considered, whose input file is generated by the ``SampleInputGenerator`` class defined in the ``sample_generator.py`` Python script file.
This file has the following content:

.. code-block:: python

    """Sample input file generator."""
    import os
    import numpy as np
    from piglot.parameter import ParameterSet
    from piglot.solver.input_file_solver import InputData, InputDataGenerator


    class SampleInputGenerator(InputDataGenerator):
        """Default input data generator for input file-based solvers."""

        def generate(self, parameters: ParameterSet, values: np.ndarray, tmp_dir: str) -> InputData:
            """Generate the input data for the given set of parameters.

            Parameters
            ----------
            parameters : ParameterSet
                Parameter set for this problem.
            values : np.ndarray
                Current parameters to evaluate.
            tmp_dir : str
                Temporary directory to run the problem.

            Returns
            -------
            InputData
                Input data for this problem.
            """
            param_dict = parameters.to_dict(values)
            values = np.array([ist(param_dict.values())
            input_file = os.path.join(tmp_dir, 'input.data')
            np.savetxt(input_file, values)
            return InputData(tmp_dir, input_file, [])


Input file dependencies
^^^^^^^^^^^^^^^^^^^^^^^

In addition to the main input file, some solvers may also have a list of dependent files that must be present in the working directory.
Since ``piglot`` uses temporary directories to run the simulations, these files must be copied to the temporary directory before the solver is executed.
Some solvers build the dependency list automatically (currently, only ``Links`` supports this), but others require manual specification.
In general, two kinds of dependencies can be supplied:

* **Copy dependencies** - these files are simply copied to the temporary directory, without any modification.
* **Substitution dependencies** - these files are copied to the temporary directory, but parameter substitution is performed before the solver is executed.
  This allows replacing parameters in certain dependencies, if needed.
  Note, however, that there is an additional cost associated with this operation, as ``piglot`` needs to search for the parameters in the dependency files and replace them.

To specify the dependencies, the following YAML structure can be used:

.. code-block:: yaml

    solver:
        name: sample_input_file
        cases:
        input.dat:
            substitution_dependencies:
                - dep_subs.txt
            copy_dependencies:
                - dep_copy.txt
            fields:
            sample_output:
                name: sample

In this example, the solver named ``sample_input_file`` has a single case named ``input.dat``, that requires copying the file ``dep_copy.txt`` to the temporary directory, and substituting the parameters in the file ``dep_subs.txt`` before copying it.