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:

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

Is equivalent to:

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:

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:

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

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.