Generator Specs

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

Standardized (gest-api)

from libensemble import GenSpecs
from libensemble.gen_classes import UniformSample
from gest_api.vocs import VOCS

vocs = VOCS(
    variables={"x": [-3.0, 3.0]},
    objectives={"y": "MINIMIZE"},
)

gen_specs = GenSpecs(
    generator=UniformSample(vocs),
    vocs=vocs,
)
...

Classic (gen_f)

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.

Fields:

• generator (object | None)

• gen_f (object | None)

• inputs (list[str] | None)

• persis_in (list[str] | None)

• outputs (list[tuple])

• initial_batch_size (int)

• batch_size (int)

• initial_sample_method (str | object | None)

• threaded (bool | None)

• user (dict | None)

• vocs (object | None)

• num_active_gens (int)

• async_return (bool)

• active_recv_gen (bool)

• batch_evaluate_same_priority (bool)

• alt_type (bool)

field active_recv_gen: bool = False

Initialize generator in active-receive mode. The generator can receive results even if it’s not ready to produce new points. Only used if using the only_persistent_gens allocation function (the default).

field alt_type: bool = False

Enable specialized allocator behavior for only_persistent_gens.

field async_return: bool = False

Return results to generator one-at-a-time as they come in (after sample). Default of False implies batch return. Only used if using the only_persistent_gens allocation function (the default).

field batch_evaluate_same_priority: bool = False

Pass all points with the same priority value as a batch to a single simulator call.

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.

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. Produces parameters for evaluation by a simulator function, and makes decisions based on simulator function output.

These inherit from the gest-api (https://github.com/campa-consortium/gest-api) base class. Recommended over the classic gen_f interface.

field initial_batch_size: int = 0

Initial sample size. For standardized generators, this is the number of initial points to request that the generator create. If zero, falls back to batch_size. For persistent generators, this is the number of points evaluated before switching from batch return to asynchronous return (if async_return is True).

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

field initial_sample_method: str | object | None = None

Method for producing initial sample points before starting the generator. If None (default), the generator is responsible for producing its own initial sample via suggest(). May be set to either:

• a string naming a built-in sampler — currently "uniform" or "latin_hypercube" — which libEnsemble instantiates with the VOCS, or

• a pre-constructed sampler instance (any object with a suggest() method, typically a LibensembleGenerator subclass from gen_classes.sampling). Use this form when you need to pass extra constructor arguments (random_seed, max_resource_sets, components, etc.) or want to use a custom sampler.

libEnsemble draws initial_batch_size points from the sampler, evaluates them, and ingests the results into the generator before optimization begins.

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 num_active_gens: int = 1

Maximum number of persistent generators to start. Only used if using the only_persistent_gens allocation function (the default).

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.