Exploration output
==================

By default, the output of an optimas :class:`~optimas.explorations.Exploration`
is stored in an ``exploration`` folder located in the same directory as the
main script. This output consists of log files, folders and data generated by
`libEnsemble <https://libensemble.readthedocs.io/en/main/history_output_logging.html>`_
and the evaluations/simulations.

Log files
~~~~~~~~~

In every run, the following log files are generated:

- ``libE-stats.txt``: log indicating the worker, start time, end time, etc. of
  each evaluation.
- ``ensemble.log``: log of ``libEnsemble`` containing the main events of
  the run. This includes the commands with which each evaluation was launched.
- ``exploration_history_after_sim_<last_simulation_number>.npy``:
  numpy file that contains the
  `history array <https://libensemble.readthedocs.io/en/main/function_guides/history_array.html>`_
  of the run. This is a structured array that stores the data of each
  evaluation, including the values of the
  :class:`~optimas.core.VaryingParameter`\s,
  :class:`~optimas.core.Objective`\s, analyzed
  :class:`~optimas.core.Parameter`\s and other useful diagnostics.
  The periodicity with which this file is updated can be set with the
  ``history_save_period`` argument of the :class:`~optimas.explorations.Exploration`.
- ``exploration_parameters.json``: JSON file containing a serialized
  version of the :class:`~optimas.core.VaryingParameter`\s,
  :class:`~optimas.core.Objective`\s and other
  :class:`~optimas.core.Parameter`\s of the exploration.

In addition, if the run is aborted for any reason, two additional files
will be created:

- ``libE_history_at_abort_<sim_count>.npy``: numpy file containing the history
  array when the run was aborted.
- ``libE_persis_info_at_abort_<sim_count>.pickle``: contains the internal
  ``persis_info`` of libEnsemble when the run was aborted.


Simulation data
~~~~~~~~~~~~~~~

When using a :class:`~optimas.evaluators.TemplateEvaluator` (see
:ref:`optimas-with-simulations`), an ``exploration/evaluations`` directory is
also created. Inside this directory, a new folder following the pattern
``sim<simulation_number>`` will be created for each
simulation. This folder contains the simulation script, a copy of the files
specified in ``sim_files``, and the output data of the simulation.


Surrogate model
~~~~~~~~~~~~~~~

Some generators store an internal surrogate model. This is the case,
for example, of the
:class:`~optimas.generators.AxSingleFidelityGenerator`, which stores an
``AxClient`` with the surrogate model used for Bayesian optimization.

Generators that have this capability can also save the internal model
to file with a certain periodicity (set by the ``model_save_period``
attribute). By default, these models will be saved in a
``exploration/model_history`` directory.


Example output
~~~~~~~~~~~~~~

An example of the output structure can be seen below. This case
corresponds an optimas run using an
:class:`~optimas.generators.AxSingleFidelityGenerator` and a
:class:`~optimas.evaluators.TemplateEvaluator`, such as in the example
:ref:`bo-basic`.

.. code-block:: bash
   :emphasize-lines: 4,7,21

   /
   ├── run_optimas.py
   ├── template_simulation_script.py
   └── exploration
       ├── ensemble.log
       ├── libE_stats.txt
       ├── exploration_history_after_sim_99.txt
       ├── exploration_parameters.json
       ├── evaluations
       │   ├── sim0000
       │   │   ├── simulation_script.py
       │   │   └── result.txt
       │   ├── sim0001
       │   │   ├── simulation_script.py
       │   │   └── result.txt
       │   ├── sim0002
       │   │   ├── simulation_script.py
       │   │   └── result.txt
       │  ...
       │   └── sim0099
       │       ├── simulation_script.py
       │       └── result.txt
       └── model_history
           ├── ax_client_at_eval_5.json
          ...
           └── ax_client_at_eval_100.json