User Function API

libEnsemble requires functions for generation, simulation, and allocation.

While libEnsemble provides a default allocation function, the simulator and generator functions must be specified. The required API and example arguments are given here. Example sim and gen functions are provided in the libEnsemble package.

See here for more in-depth guides to writing user functions

sim_f API

The simulator function will be called by libEnsemble’s workers with the following API:

out = sim_f(H[sim_specs['in']][sim_ids_from_allocf], persis_info, sim_specs, libE_info)

Parameters:

H: numpy structured array (example)

persis_info: dict (example)

sim_specs: dict (example)

libE_info: dict (example)

Returns:

H: numpy structured array with keys/value-sizes matching those in sim_specs[‘out’] (example)

persis_info: dict (example)

calc_status: int, optional Provides a task status to the manager and the libE_stats.txt file (example)

gen_f API

The generator function will be called by libEnsemble’s workers with the following API:

out = gen_f(H[gen_specs['in']][sim_ids_from_allocf], persis_info, gen_specs, libE_info)

Parameters:

H: numpy structured array (example)

persis_info: dict (example)

gen_specs: dict (example)

libE_info: dict (example)

Returns:

H: numpy structured array with keys/value-sizes matching those in gen_specs[‘out’] (example)

persis_info: dict (example)

calc_status: int, optional Provides a task status to the manager and the libE_stats.txt file (example)

alloc_f API

The allocation function will be called by libEnsemble’s manager with the following API:

Work, persis_info, stop_flag = alloc_f(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

Parameters:

W: numpy structured array (example)

H: numpy structured array (example)

sim_specs: dict (example)

gen_specs: dict (example)

alloc_specs: dict (example)

persis_info: dict (example)

libE_info: dict Various statistics useful to the allocation function for determining how much work has been evaluated, or if the routine should prepare to complete. See the allocation function guide for more information.

Returns:

Work: dict Dictionary with integer keys i for work to be sent to worker i. (example)

persis_info: dict (example)

stop_flag: int, optional Set to 1 to request libEnsemble manager to stop giving additional work after receiving existing work