.. _datastruct-history-array:

history array
=============
::

    H: numpy structured array
        History to store output from gen_f/sim_f/alloc_f for each entry

libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
store output information about points generated by the ``gen_f`` and then the
resultant output from the ``sim_f``. The history array also stores information
about the time (since the epoch) when the points are generated/evaluated and
which workers are/were involved.

For ease, ``gen_f`` and ``sim_f`` are expected to return output as NumPy
structured arrays. The names of the input fields for ``gen_f`` and ``sim_f``
must be output from ``gen_f`` or ``sim_f``. In addition to output fields, the
final history array returned by libEnsemble will include the following
fields, almost all of which are protected from the user. These fields are
populated internally:

* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
  associated ``sim_id``. The generator can assign this, but users must be
  careful to ensure that points are added in order. For example, if ``alloc_f``
  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
  should ensure that both don’t generate points with the same ``sim_id``.

* ``given`` [bool]: True if this ``gen_f`` output been given to a libEnsemble
  worker to be evaluated by a ``sim_f``.

* ``given_time`` [float]: Time this entry
  was *first* given to a worker to be evaluated by a ``sim_f``.

* ``last_given_time`` [float]: Time this entry
  was *last* given to a worker to be evaluated by a ``sim_f``.

* ``returned`` [bool]: True if this entry has been evaluated by a ``sim_f``.

* ``returned_time`` [float]: Time this entry was *last* returned from a ``sim_f``.

* ``given_back`` [bool]: True if this ``gen_f`` output been given back to a ``gen_f``
  worker after being returned from evaluation.

.. * ``given_back_time`` [float]: Time this entry
..   was *first* given back to a ``gen_f`` worker.

* ``last_given_back_time`` [float]: Time this entry
  was *last* given back to a ``gen_f`` worker.

* ``sim_worker`` [int]: libEnsemble worker that performed the ``sim_f`` evaluation.

* ``gen_worker`` [int]: libEnsemble worker that generated this entry.

* ``gen_time`` [float]: Time this entry was put into ``H`` by the manager.

* ``last_gen_time`` [float]: Time this entry was last requested by a ``gen_f``.

* ``cancel_requested`` [bool]: True if cancellation of evaluation of this entry was requested.

* ``kill_sent`` [bool]: True if a kill signal has been sent to the worker evaluating this entry.

Other than ``'sim_id'`` and ``cancel_requested``, protected fields cannot be
overwritten by user functions unless ``libE_specs['safe_mode']`` is set to ``False``.

.. warning::
  Adjusting values in protected fields may crash libEnsemble.
