User Function API¶
libEnsemble requires functions for generation, simulation, and allocation.
While libEnsemble provides a default allocation function, the sim and gen functions must be specified. The required API and example arguments are given here. Example sim and gen functions are provided in the libEnsemble package.
The libEnsemble History Array
libEnsemble uses a NumPy structured array H to
store output from
gen_f and corresponding
sim_f output. Similarly,
sim_f are expected to return output in NumPy structured
arrays. The names of the fields to be given as input to
must be an output from
sim_f. In addition to the fields output
gen_f, the final history returned from libEnsemble will
include the following fields:
sim_id[int]: Each unit of work output from
gen_fmust have an associated
sim_id. The generator can assign this, but users must be careful to ensure points are added in order. For example,
if alloc_fallows for two
gen_finstances to be running simultaneously,
alloc_fshould ensure that both don’t generate points with the same
given[bool]: Has this
gen_foutput been given to a libEnsemble worker to be evaluated yet?
given_time[float]: At what time (since the epoch) was this
gen_foutput given to a worker?
sim_worker[int]: libEnsemble worker that it was given to be evaluated.
gen_worker[int]: libEnsemble worker that generated this
gen_time[float]: At what time (since the epoch) was this entry (or collection of entries) put into
Hby the manager
returned[bool]: Has this worker completed the evaluation of this unit of work?
The sim_f function will be called by libEnsemble with the following API:
out = sim_f(H[sim_specs['in']][sim_ids_from_allocf], persis_info, sim_specs, libE_info)
The gen_f calculations will be called by libEnsemble with the following API:
out = gen_f(H[gen_specs['in']][sim_ids_from_allocf], persis_info, gen_specs, libE_info)
The alloc_f calculations will be called by libEnsemble with the following API:
Work, persis_info, stop_flag = alloc_f(W, H, sim_specs, gen_specs, alloc_specs, persis_info)