Generator Specs

Used to specify the generator function, its inputs and outputs, and user data.

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.

class

...
import numpy as np
from libensemble import GenSpecs
from generator import gen_random_sample

...

gen_specs = GenSpecs(
    gen_f=gen_random_sample,
    out=[("x", float, (1,))],
    user={
        "lower": np.array([-3]),
        "upper": np.array([3]),
        "gen_batch_size": 5,
    },
)
...

pydantic model libensemble.specs.GenSpecs

Specifications for configuring a Generator Function. Equivalent to a gen_specs dictionary.

Fields:

gen_f (Callable | None)
inputs (List[str] | None)
persis_in (List[str] | None)
out (List[Tuple[str, Any] | Tuple[str, Any, int | Tuple]])
funcx_endpoint (str | None)
user (dict | None)

field funcx_endpoint: str | None = '': A funcX (https://funcx.org/) ID corresponding to an active endpoint on a remote system. libEnsemble’s workers will submit generator function instances to this endpoint to be executed, instead of being called in-place

field gen_f: Callable | None = <function latin_hypercube_sample>: Python function that matches the gen_f api. e.g. libensemble.gen_funcs.sampling. Produces parameters for evaluation by a simulator function, and makes decisions based on simulator function output

field inputs: List[str] | None = [] (alias 'in'): List of field names out of the complete history to pass into the simulation function on initialization. Can use in or inputs as keyword

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). Typically used to initialize an output array within the generator function: out = np.zeros(100, dtype=gen_specs["out"]). Also used to construct the complete dtype for libEnsemble’s history array

field persis_in: List[str] | None = []: List of field names that will be passed to a persistent generator function throughout runtime, following initialization

field user: dict | None = {}: A user-data dictionary to place bounds, constants, settings, or other parameters for customizing the generator function

dict

gen_specs = {
    "gen_f": gen_random_sample,
    "out": [("x", float, (1,))],
    "user": {
        "lower": np.array([-3]),
        "upper": np.array([3]),
        "gen_batch_size": 5,
    },
}