Simulation Specs

Used to specify the simulation 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 SimSpecs
from simulator import sim_find_sine

...

sim_specs = SimSpecs(
    sim_f=sim_find_sine,
    inputs=["x"],
    out=[("y", float)],
    user={"batch": 1234},
)
...

pydantic model libensemble.specs.SimSpecs

Specifications for configuring a Simulation Function. Equivalent to a sim_specs dictionary.

Fields:

• sim_f (Callable)

• inputs (List[str])

• 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 simulator function instances to this endpoint to be executed, instead of calling them locally

field inputs: List[str] = [] (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 simulation function: out = np.zeros(100, dtype=sim_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 simulation function throughout runtime, following initialization

field sim_f: Callable = <function one_d_example>

Python function that matches the sim_f api. e.g. libensemble.sim_funcs.borehole. Evaluates parameters produced by a generator function

field user: dict | None = {}

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

dict

...
import numpy as np
from simulator import six_hump_camel

...

sim_specs = {
    "sim_f": six_hump_camel,
    "in": ["x"],
    "out": [("y", float)],
    "user": {"batch": 1234},
}
...

• test_uniform_sampling.py has a sim_specs that declares the name of the "in" field variable, "x" (as specified by the corresponding generator "out" field "x" from the gen_specs example). Only the field name is required in sim_specs["in"].

    sim_specs = {
        "sim_f": six_hump_camel,  # Function whose output is being minimized
        "in": ["x"],  # Keys to be given to sim_f
        "out": [("f", float)],  # Name of the outputs from sim_f
    }

• run_libe_forces.py has a longer sim_specs declaration with a number of user-specific fields. These are given to the corresponding sim_f, which can be found at forces_simf.py.

    "sim_f": run_forces,  # Function whose output is being minimized
    "in": ["x"],  # Name of input for sim_f
    "out": [("energy", float)],  # Name, type of output from sim_f
    "user": {
        "keys": ["seed"],
        "cores": 2,
        "sim_particles": 1e3,
        "sim_timesteps": 5,
        "sim_kill_minutes": 10.0,
        "particle_variance": 0.2,
        "kill_rate": 0.5,
        "fail_on_sim": False,
        "fail_on_submit": False,  # Won't occur if 'fail_on_sim' True
    },
}