Allocation Specs

Allocation function specifications to be set in the user calling script. Optional.

Can be constructed and passed to libEnsemble as a Python class or a dictionary. When provided as a Python class, all data is validated immediately on instantiation.

pydantic model libensemble.specs.AllocSpecs

Specifications for configuring an Allocation Function. Equivalent to an alloc_specs dictionary.

Fields:

• alloc_f (Callable)

• user (dict | None)

• out (List[Tuple[str, Any] | Tuple[str, Any, int | Tuple]])

field alloc_f: Callable = <function give_sim_work_first>

Python function that matches the alloc_f api. e.g. libensemble.alloc_funcs.give_sim_work_first. Decides if and when simulator and generator functions should be called, and with what resources and parameters

field out: List[Tuple[str, Any] | Tuple[str, Any, int | Tuple]] = []

List of tuples corresponding to NumPy dtypes. e.g. ("dim", int, (3,)), or ("path", str). Allocation functions that modify libEnsemble’s History array with additional fields (e.g. to mark timing information, or determine if parameters should be distributed again, etc.) should list those fields here. Also used to construct the complete dtype for libEnsemble’s history array

field user: dict | None = {'num_active_gens': 1}

A user-data dictionary to place bounds, constants, settings, or other parameters for customizing the allocation function

Note

• libEnsemble uses the following defaults if the user doesn’t provide their own alloc_specs:

Default settings for alloc_specs

    alloc_f: Callable = give_sim_work_first
    """
    Python function that matches the alloc_f api. e.g. `libensemble.alloc_funcs.give_sim_work_first`. Decides if and
    when simulator and generator functions should be called, and with what resources and parameters
    """

    user: Optional[dict] = {"num_active_gens": 1}
    """
    A user-data dictionary to place bounds, constants, settings, or other parameters for customizing the allocation
    function
    """

    out: List[Union[Tuple[str, Any], Tuple[str, Any, Union[int, Tuple]]]] = []
    """
    List of tuples corresponding to NumPy dtypes. e.g. ``("dim", int, (3,))``, or ``("path", str)``.
    Allocation functions that modify libEnsemble's History array with additional fields (e.g. to mark
    timing information, or determine if parameters should be distributed again, etc.) should list those
    fields here. Also used to construct the complete dtype for libEnsemble's history array
    """

• Users can import and adjust these defaults using:

from libensemble.specs import AllocSpecs
my_new_alloc = AllocSpecs()
my_new_alloc.alloc_f = another_function

See also

• test_uniform_sampling_one_residual_at_a_time.py specifies fields to be used by the allocation function give_sim_work_first from fast_alloc_and_pausing.py.

    alloc_specs = {
        "alloc_f": give_sim_work_first,  # Allocation function
        "user": {
            "stop_on_NaNs": True,  # Should alloc preempt evals
            "batch_mode": True,  # Wait until all sim evals are done
            "num_active_gens": 1,  # Only allow one active generator
            "stop_partial_fvec_eval": True,  # Should alloc preempt evals
        },
    }