Running an Ensemble

class libensemble.ensemble.Ensemble(sim_specs=SimSpecs(sim_f=None, simulator=None, inputs=[], persis_in=[], outputs=[], globus_compute_endpoint='', threaded=False, user={}, vocs=None), gen_specs=GenSpecs(generator=None, gen_f=None, inputs=[], persis_in=[], outputs=[], initial_batch_size=0, batch_size=0, initial_sample_method=None, threaded=False, user={}, vocs=None, num_active_gens=1, async_return=False, active_recv_gen=False, batch_evaluate_same_priority=False, alt_type=False), exit_criteria=None, libE_specs=LibeSpecs(comms='mpi', nworkers=0, gen_on_worker=False, service_mode=False, service_mode_idle_timeout=None, mpi_comm=None, dry_run=False, abort_on_exception=True, save_every_k_sims=0, save_every_k_gens=0, save_H_and_persis_on_abort=True, save_H_on_completion=False, save_H_with_date=False, H_file_prefix='libE_history', worker_timeout=1, kill_canceled_sims=False, use_workflow_dir=False, reuse_output_dir=False, workflow_dir_path='.', ensemble_dir_path=PosixPath('ensemble'), ensemble_copy_back=False, use_worker_dirs=False, sim_dirs_make=False, sim_dir_copy_files=[], sim_dir_symlink_files=[], sim_input_dir=None, gen_dirs_make=False, gen_dir_copy_files=[], gen_dir_symlink_files=[], gen_input_dir=None, cache_long_sims=False, cache_tolerances={}, cache_dir='/home/docs/.cache/libensemble', cache_name=None, calc_dir_id_width=4, platform='', platform_specs={}, profile=False, disable_log_files=False, safe_mode=False, stats_fmt={}, live_data=None, final_gen_send=False, disable_resource_manager=False, num_resource_sets=0, gen_num_procs=0, gen_num_gpus=0, gpus_per_group=None, use_tiles_as_gpus=False, enforce_worker_core_bounds=False, dedicated_mode=False, gen_workers=[], resource_info={}, scheduler_opts={}), alloc_specs=AllocSpecs(alloc_f=<function only_persistent_gens>, user={}), persis_info={}, executor=None, H0=None, parse_args=False)

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

Example
 1from gest_api.vocs import VOCS
 2
 3from libensemble import Ensemble
 4from libensemble.gen_classes.sampling import UniformSample
 5from libensemble.sim_funcs.simple_sim import norm_eval
 6from libensemble.specs import GenSpecs, SimSpecs
 7
 8sampling = Ensemble(parse_args=True)
 9
10sampling.sim_specs = SimSpecs(
11    sim_f=norm_eval,
12    inputs=["x"],
13    outputs=[("f", float)],
14)
15
16vocs = VOCS(
17    variables={"x": [-3, 3]},
18    objectives={"f": "EXPLORE"},
19)
20
21generator = UniformSample(vocs=vocs)
22
23sampling.gen_specs = GenSpecs(
24    generator=generator,
25    batch_size=50,
26)
27
28if __name__ == "__main__":
29    sampling.run(sim_max=100)
30    sampling.save_output(__file__)

Configure by:

Option 1: Providing parameters on instantiation
 1from libensemble import Ensemble
 2from libensemble.specs import SimSpecs
 3from my_simulator import sim_find_energy
 4
 5sim_specs = SimSpecs(
 6    sim_f=sim_find_energy,
 7    inputs=["x"],
 8    outputs=[("y", float)],
 9)
10
11experiment = Ensemble(sim_specs=sim_specs)
Option 2: Assigning parameters to an instance
 1from libensemble import Ensemble
 2from libensemble.specs import SimSpecs
 3from my_simulator import sim_find_energy
 4
 5sim_specs = SimSpecs(
 6    sim_f=sim_find_energy,
 7    inputs=["x"],
 8    outputs=[("y", float)],
 9)
10
11experiment = Ensemble()
12experiment.sim_specs = sim_specs
Parameters:
  • sim_specs (SimSpecs) – Specifications for the simulator function.

  • gen_specs (GenSpecs, Optional) – Specifications for the generator.

  • exit_criteria (ExitCriteria) – Tell libEnsemble when to stop a run.

  • libE_specs (LibeSpecs, Optional) – Specifications for libEnsemble.

  • alloc_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 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}")
reset()

Reset the ensemble state to allow a fresh, independent run.

Clears the accumulated history (H0) and persis_info so that the next run() call starts from a clean slate — as if no previous run had occurred.

Use this between two calls to run() when you want independent runs rather than the default history-chaining behaviour:

ens.run(sim_max=10)   # first independent run
ens.reset()           # clear accumulated history
ens.run(sim_max=20)   # second independent run, H0 is empty again
Return type:

None

run(sim_max=None, gen_max=None, wallclock_max=None, stop_val=None)

Initializes libEnsemble.

Parameters:
  • sim_max (int, Optional) – Maximum number of new simulation evaluations for this run. Overrides exit_criteria.sim_max for this call only.

  • gen_max (int, Optional) – Maximum number of new generator calls for this run. Overrides exit_criteria.gen_max for this call only.

  • wallclock_max (float, Optional) – Wallclock timeout in seconds for this run. Overrides exit_criteria.wallclock_max for this call only.

  • stop_val (tuple[str, float], Optional) – Stop criterion (field, value) for this run. Overrides exit_criteria.stop_val for this call only.

  • dropdown: (..) –

    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.

  • dropdown: –

    Substeps / multi-step usage: Pass exit-criteria kwargs to run a subset of an ensemble at a time. The ensemble history (H0) is automatically chained across calls:

    sampling = Ensemble(...)
    sampling.sim_specs = SimSpecs(...)
    sampling.gen_specs = GenSpecs(...)
    
    # Run in three substeps
    sampling.run(sim_max=30)
    # ... adjust generator hyperparameters ...
    sampling.run(sim_max=30)
    sampling.run(sim_max=40)
    

    From the second call onward, libE_specs.final_gen_send and libE_specs.reuse_output_dir are automatically set to True to support persistent generators across substep runs.

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 the files in that directory.

The basename is reduced to its filename stem. A leading test_ is removed to preserve the calling-script convention, while occurrences elsewhere are retained. If append_attrs is true, run attributes are appended to the stem.

Returns the History filename on the manager and None on other ranks.

Parameters:
  • basename (str)

  • append_attrs (bool)

Return type:

str | None