.. _options_ref:

Global Options
==============

- `software` [str]:
    Specify what software package to use when rsopt runs. See :ref:`Software<opt_software>` for a list of supported software.
- `method` [str]:
    When `software` package chosen contains multiple algorithms the choice is specified by `method`.
    See :ref:`Software<opt_software>` for particulars on methods supported by the chosen `software`.
- `software_options` [dict]:
    Can be used to pass configuration options directly to the chosen `software`.
    See :ref:`Software<opt_software>` for available options that can be set depending on chosen `software`.
- `nworkers` [int] (default: 2):
    Number of workers used for running simulations, and in some cases a worker may be used run the governing `software`.
    In cases where the `software` option supports parallel evaluations then workers will each, independently
    run through a Job chain. For some software options the supported number of worker is fixed (e.g. local optimizers
    can only use two workers. One to manage the optimizer and one to manage simulation execution.)
    See :ref:`Software<opt_software>` for information on support for parallel evaluation
    in a particular `software` option.
- `exit_criteria` [dict]:
  Required when there is not a deterministic stopping point (sampler software). For all optimizers this must be set
  even if some stop criteria has been provided in `software_options`. libEnsemble will pre-allocate a history array
  based on the settings of `exit_criteria` so it must fit into memory on whatever resource rsopt is being executed on.
  Allowed fields (At least one must be given):

        'sim_max' [int]:
            Stop when this many new points have been evaluated by sim_f
        'gen_max' [int]:
            Stop when this many new points have been generated by gen_f
        'elapsed_wallclock_time' [float]:
            Stop when this time (since the manager has been initialized) has elapsed
        'stop_val' [(str, float)]:
            Stop when H[str] < float for the given (str, float pair)

- `objective_function` [list]:
  Required to use an optimizer if the final code in the job chain is not a serial Python execution. Should contain
  the name of the Python module defining the objective function and the name of that function. For example
  :code:`objective_function: [functions.py, obj_f]`. If the final code
  in the job chain is serial Python then rsopt will try to directly pass its output to the optimizer if no
  `objective_function` is given.
- `record_interval` [int]:
  If given the optimizer or sampler progress (from the libEnsemble history array) will be dumped every `record_interval`
  evaluations. If not given or 0 then the history will only be dumped at the end of the run. libEnsemble will also
  attempt to dump the history in the event of premature termination due to a worker crash.
- `output_file` [str]:
  The name of a file *without the extension* where the history array will be dumped. File written will be:
  `output_file`.npy.
- `run_dir` [str]:
  If given then all code evaluations will use `run_dir` as the top level for executing evaluations. If not given
  the default path is `./ensemble`. If a relative path is given the path will be relative to the rsopt execution directory.
  Additional directories may be created within `run_dir` depending on the setting of `use_worker_dirs` and `sim_dirs_make`.
- `sym_links` [list]:
  A list of file names that will be symlinked into every simulation run directory.
- `sim_dirs_make` [bool]:
  If true then every simulation will be run in a separate directory under `run_dir`. This is always set to `True` if
  any code is using `parallel` or `rsmpi` execution regardless of setting in the configuration file. Otherwise input files
  might clash.
- `use_worker_dirs` [bool]:
  If true then sim directories are organized under a common worker directory. This is used by default
  if parallel execution is being used.
- `copy_final_logs` [bool]:
  Defaults to True. If True then ensemble.log, libE_stats.txt, the configuration file, and the final history file
  will be copied to the top level of `run_dir`. This copying does not occur if the run terminates unexpectedly.
- `executor_options` [dict]:
  Options given here are passed directly to the libEnsemble Executor.
    - `hosts` [list] (rsmpi only): A list of rsmpi host indices that workers can use. To see your available host indices run
      :code:`rsmpi` on the command line. If not set rsmpi will be allowed to assign work to all rsmpi nodes available to you.