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.

 1...
 2import numpy as np
 3from libensemble import GenSpecs
 4from generator import gen_random_sample
 5
 6...
 7
 8gen_specs = GenSpecs(
 9    gen_f=gen_random_sample,
10    outputs=[("x", float, (1,))],
11    user={
12        "lower": np.array([-3]),
13        "upper": np.array([3]),
14        "gen_batch_size": 5,
15    },
16)
17...
pydantic model libensemble.specs.GenSpecs

Specifications for configuring a Generator Function.

Fields:
field gen_f: Callable | None = None

Python function matching the gen_f interface. Produces parameters for evaluation by a simulator function, and makes decisions based on simulator function output.

field globus_compute_endpoint: str | None = ''

A Globus Compute (https://www.globus.org/compute) ID corresponding to an active endpoint on a remote system. libEnsemble’s workers will submit generator function instances to this endpoint instead of calling them locally.

field inputs: List[str] | None = [] (alias 'in')

List of field names out of the complete history to pass into the generator function upon calling.

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

List of 2- or 3-tuples corresponding to NumPy dtypes. e.g. ("dim", int, (3,)), or ("path", str). Typically used to initialize an output array within the generator: out = np.zeros(100, dtype=gen_specs["out"]). Also used to construct libEnsemble’s history array.

field persis_in: List[str] | None = []

List of field names to send to a persistent generator function throughout the run, following initialization.

field threaded: bool | None = False

Instruct Worker process to launch user function to a thread.

field user: dict | None = {}

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

 1...
 2import numpy as np
 3from generator import gen_random_sample
 4
 5...
 6
 7gen_specs = {
 8    "gen_f": gen_random_sample,
 9    "out": [("x", float, (1,))],
10    "user": {
11        "lower": np.array([-3]),
12        "upper": np.array([3]),
13        "gen_batch_size": 5,
14    },
15}

See also

  • test_uniform_sampling.py: the generator function uniform_random_sample in sampling.py will generate 500 random points uniformly over the 2D domain defined by gen_specs["ub"] and gen_specs["lb"].

    gen_specs = {
        "gen_f": uniform_random_sample,  # Function generating sim_f input
        "out": [("x", float, (2,))],  # Tell libE gen_f output, type, size
        "user": {
            "gen_batch_size": 500,  # Used by this specific gen_f
            "lb": np.array([-3, -2]),  # Used by this specific gen_f
            "ub": np.array([3, 2]),  # Used by this specific gen_f
        },
    }

See also

  • test_persistent_aposmm_nlopt.py shows an example where gen_specs["in"] is empty, but gen_specs["persis_in"] specifies values to return to the persistent generator.

  • test_persistent_aposmm_with_grad.py shows a similar example where an H0 is used to provide points from a previous run. In this case, gen_specs["in"] is populated to provide the generator with data for the initial points.

  • In some cases you might be able to give different (perhaps fewer) fields in "persis_in" than "in"; you may not need to give x for example, as the persistent generator already has x for those points. See more example uses of persis_in.

Note

  • In all interfaces, custom fields should only be placed in "user"

  • Generator "out" fields typically match Simulation "in" fields, and vice-versa.