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 H 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.

  • 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.


Adjusting values in protected fields may crash libEnsemble.