Generator Specs

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

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

...

gen_specs = GenSpecs(
    gen_f=gen_random_sample,
    outputs=[("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.

Fields:

• gen_f (object | None)

• generator (object | None)

• inputs (list[str] | None)

• persis_in (list[str] | None)

• outputs (list[tuple])

• globus_compute_endpoint (str | None)

• initial_batch_size (int)

• batch_size (int)

• threaded (bool | None)

• user (dict | None)

• vocs (object | None)

field batch_size: int = 0

Number of points to generate in each batch. If zero, falls back to the number of completed evaluations most recently told to the generator.

Note: Certain generators included with libEnsemble decide batch sizes via gen_specs["user"] or other methods.

field gen_f: object | 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 generator: object | None = None

A pre-initialized generator object.

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 initial_batch_size: int = 0

Number of initial points to request that the generator create. If zero, falls back to batch_size. If both options are zero, defaults to the number of workers.

Note: Certain generators included with libEnsemble decide batch sizes via gen_specs["user"] or other methods.

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] = [] (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

field vocs: object | None = None

A VOCS object. If provided and persis_in/outputs are not explicitly set, they will be automatically derived from VOCS.

Note

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

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