Running an Ensemble

class libensemble.ensemble.Ensemble

The primary object for a libEnsemble workflow. Parses and validates settings and maintains output.

Example

from gest_api.vocs import VOCS

from libensemble import Ensemble
from libensemble.gen_classes.sampling import UniformSample
from libensemble.sim_funcs.simple_sim import norm_eval
from libensemble.specs import ExitCriteria, GenSpecs, SimSpecs

sampling = Ensemble(parse_args=True)

sampling.sim_specs = SimSpecs(
    sim_f=norm_eval,
    inputs=["x"],
    outputs=[("f", float)],
)

vocs = VOCS(
    variables={"x": [-3, 3]},
    objectives={"f": "EXPLORE"},
)

generator = UniformSample(vocs=vocs)

sampling.gen_specs = GenSpecs(
    generator=generator,
    batch_size=50,
)

sampling.exit_criteria = ExitCriteria(sim_max=100)

if __name__ == "__main__":
    sampling.run()
    sampling.save_output(__file__)

Configure by:

Option 1: Providing parameters on instantiation

from libensemble import Ensemble
from libensemble.specs import SimSpecs
from my_simulator import sim_find_energy

sim_specs = SimSpecs(
    sim_f=sim_find_energy,
    inputs=["x"],
    outputs=[("y", float)],
)

experiment = Ensemble(sim_specs=sim_specs)

Option 2: Assigning parameters to an instance

from libensemble import Ensemble
from libensemble.specs import SimSpecs
from my_simulator import sim_find_energy

sim_specs = SimSpecs(
    sim_f=sim_find_energy,
    inputs=["x"],
    outputs=[("y", float)],
)

experiment = Ensemble()
experiment.sim_specs = sim_specs

Parameters:

• sim_specs (class:SimSpecs<libensemble.specs.SimSpecs>) – Specifications for the simulator function.

• gen_specs (class:GenSpecs<libensemble.specs.GenSpecs>, Optional) – Specifications for the generator.

• exit_criteria (class:ExitCriteria<libensemble.specs.ExitCriteria>) – Tell libEnsemble when to stop a run.

• libE_specs (class:LibeSpecs<libensemble.specs.LibeSpecs>, Optional) – Specifications for libEnsemble.

• alloc_specs (class:AllocSpecs<libensemble.specs.AllocSpecs>, Optional) – Specifications for the allocation function.

• persis_info (dict, Optional) – Persistent information to be passed between user function instances (example)

• executor (Executor, Optional) – libEnsemble Executor instance for use within simulator functions or generators.

• H0 (NumPy structured array, Optional) – A libEnsemble history to be prepended to this run’s history (example).

• parse_args (bool, Optional) – Read nworkers, comms, and other arguments from the command-line. For MPI, calculate nworkers and set the is_manager Boolean attribute on MPI rank 0. See the parse_args docs for more information.

ready()

Verify that all necessary data has been provided before calling run().

Performs a pre-flight check on the ensemble configuration, covering:

• A simulation callable (sim_f or simulator) is set on sim_specs.

• At least one exit condition is configured on exit_criteria.

• Workers are available (nworkers > 0 for local/threads/tcp comms, or MPI comms is set, which infers workers from the MPI communicator).

• If both gen_specs and sim_specs use the classic field-name interface, the generator output field names are a superset of the simulator input field names.

Returns:

A 2-tuple of (is_ready, issues). is_ready is True when all checks pass. issues is a list of human-readable strings describing each problem found; it is empty when is_ready is True.

Return type:

tuple[bool, list[str]]

Example

ok, issues = sampling.ready()
if not ok:
    for issue in issues:
        print(f"  - {issue}")

run()

Initializes libEnsemble.

MPI/comms Notes

Manager–worker intercommunications are parsed from the comms key of libE_specs. An MPI runtime is assumed by default if -n N wasn’t specified on the command-line or comms="local" in libE_specs.

If a MPI communicator was provided in libE_specs, then each .run() call will initiate on a duplicate of that communicator. Otherwise, a duplicate of COMM_WORLD will be used.

Returns:

• H (NumPy structured array) – History array storing rows for each point. (example)

• persis_info (dict) – Final state of persistent information (example)

• exit_flag (int) – Flag containing final task status

  0 = No errors
  1 = Exception occurred
  2 = Manager timed out and ended simulation
  3 = Current process is not in libEnsemble MPI communicator
  

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], dict, int]

save_output(basename, append_attrs=True)

Writes out History array and persis_info to files. If using a workflow_dir_path in libE_specs, will place with specified filename in that directory.

Parameters:

• Format (<basename>_results_History_length=<length>_evals=<Completed evals>_ranks=<nworkers>)

• basename (str)

• append_attrs=False (set)

• Format

• basename

• append_attrs (bool)