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.
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 out=[("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. Equivalent to a
gen_specs
dictionary.- Fields:
- 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
orinputs
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
1gen_specs = {
2 "gen_f": gen_random_sample,
3 "out": [("x", float, (1,))],
4 "user": {
5 "lower": np.array([-3]),
6 "upper": np.array([3]),
7 "gen_batch_size": 5,
8 },
9}
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 bygen_specs["ub"]
andgen_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, butgen_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 givex
for example, as the persistent generator already hasx
for those points. See more example uses ofpersis_in
.
Note
In all interfaces, custom fields should only be placed in
"user"
Generator
"out"
fields typically match Simulation"in"
fields, and vice-versa.