Allocation Functions

Below are example allocation functions available in libEnsemble.

Important

See the API for allocation functions here.

Note

The default alloc_func is give_sim_work_first.

give_sim_work_first

give_sim_work_first.give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

Decide what should be given to workers. This allocation function gives any available simulation work first, and only when all simulations are completed or running does it start (at most alloc_specs['user']['num_active_gens']) generator instances.

Allows for a alloc_specs['user']['batch_mode'] where no generation work is given out unless all entries in H are returned.

Can give points in highest priority, if 'priority' is a field in H. If alloc_specs[‘user’][‘give_all_with_same_priority’] is set to True, then all points with the same priority value are given as a batch to the sim.

Workers performing sims will be assigned resources given in H[‘resource_sets’] this field exists, else defaulting to one. Workers performing gens are assigned resource_sets given by persis_info[‘gen_resources’] or zero.

This is the default allocation function if one is not defined.

See also

test_uniform_sampling.py # noqa

fast_alloc

fast_alloc.give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

This allocation function gives (in order) entries in H to idle workers to evaluate in the simulation function. The fields in sim_specs['in'] are given. If all entries in H have been given a be evaluated, a worker is told to call the generator function, provided this wouldn’t result in more than alloc_specs['user']['num_active_gen'] active generators.

This fast_alloc variation of give_sim_work_first is useful for cases that simply iterate through H, issuing evaluations in order and, in particular, is likely to be faster if there will be many short simulation evaluations, given that this function contains fewer column length operations.

See also

test_fast_alloc.py # noqa

fast_alloc_to_aposmm

fast_alloc_to_aposmm.give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info): This allocation function gives (in order) entries in H to idle workers to evaluate in the simulation function. The fields in sim_specs['in'] are given. If all entries in H have been given to be evaluated, a worker is told to call the generator function, provided this wouldn’t result in more than alloc_specs['user']['num_active_gen'] active generators. Also allows for a 'batch_mode'.

See also

test_old_aposmm_with_gradients.py # noqa

start_only_persistent

start_only_persistent.only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

This allocation function will give simulation work if possible, but otherwise start up to alloc_specs['user']['num_active_gens'] persistent generators (defaulting to one).

By default, evaluation results are given back to the generator once all generated points have been returned from the simulation evaluation. If alloc_specs['user']['async_return'] is set to True, then any returned points are given back to the generator.

If any workers are marked as zero_resource_workers, then these will only be used for generators.

If any of the persistent generators has exited, then ensemble shutdown is triggered.

User options:

To be provided in calling script: E.g., alloc_specs['user']['async_return'] = True

init_sample_size: int, optional: Initial sample size - always return in batch. Default: 0
num_active_gens: int, optional: Maximum number of persistent generators to start. Default: 1
async_return: boolean, optional: Return results to gen as they come in (after sample). Default: False (batch return).
active_recv_gen: boolean, optional: Create gen in active receive mode. If True, the manager does not need to wait for a return from the generator before sending further returned points. Default: False

start_only_persistent.only_persistent_workers(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

SH: TODO - Need to update docstring… This allocation function will give simulation work if possible, but otherwise start up to alloc_specs['user']['num_active_gens'] persistent generators (defaulting to one).

By default, evaluation results are given back to the generator once all generated points have been returned from the simulation evaluation. If alloc_specs['user']['async_return'] is set to True, then any returned points are given back to the generator.

If any workers are marked as zero_resource_workers, then these will only be used for generators.

If any of the persistent generators has exited, then ensemble shutdown is triggered.

User options:

To be provided in calling script: E.g., alloc_specs['user']['async_return'] = True

init_sample_size: int, optional: Initial sample size - always return in batch. Default: 0
num_active_gens: int, optional: Maximum number of persistent generators to start. Default: 1
async_return: boolean, optional: Return results to gen as they come in (after sample). Default: False (batch return).
active_recv_gen: boolean, optional: Create gen in active receive mode. If True, the manager does not need to wait for a return from the generator before sending further returned points. Default: False

start_persistent_local_opt_gens

start_persistent_local_opt_gens.start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info, libE_info)

This allocation function will do the following:

Start up a persistent generator that is a local opt run at the first point identified by APOSMM’s decide_where_to_start_localopt. Note, it will do this only if at least one worker will be left to perform simulation evaluations.
If multiple starting points are available, the one with smallest function value is chosen.
If no candidate starting points exist, points from existing runs will be evaluated (oldest first).
If no points are left, call the generation function.