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.

pydantic model libensemble.specs.AllocSpecs

Specifications for configuring an Allocation Function.

Fields:

• alloc_f (Callable)

• user (dict | None)

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

field alloc_f: Callable = <function give_sim_work_first>

Python function matching the alloc_f interface. Decides when simulator and generator functions should be called, and with what resources and parameters.

field outputs: List[Tuple[str, Any] | Tuple[str, Any, int | Tuple]] = [] (alias 'out')

List of 2- or 3-tuples corresponding to NumPy dtypes. e.g. ("dim", int, (3,)), or ("path", str). Allocation functions that modify libEnsemble’s History array with additional fields should list those fields here. Also used to construct 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 matching the ``alloc_f`` interface. Decides 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.
    """

    outputs: List[Union[Tuple[str, Any], Tuple[str, Any, Union[int, Tuple]]]] = Field([], alias="out")
    """
    List of 2- or 3-tuples corresponding to NumPy dtypes. e.g. ``("dim", int, (3,))``, or ``("path", str)``.
    Allocation functions that modify libEnsemble's History array with additional fields should list those
    fields here. Also used to construct 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
        },
    }