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, calculatenworkersand set theis_managerBoolean attribute on MPI rank 0. See theparse_argsdocs 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_forsimulator) is set onsim_specs.At least one exit condition is configured on
exit_criteria.Workers are available (
nworkers > 0for local/threads comms, or MPI comms is set, which infers workers from the MPI communicator).If both
gen_specsandsim_specsuse 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_readyisTruewhen all checks pass.issuesis a list of human-readable strings describing each problem found; it is empty whenis_readyisTrue.- 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) andpersis_infoso that the nextrun()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_maxfor this call only.gen_max (int, Optional) – Maximum number of new generator calls for this run. Overrides
exit_criteria.gen_maxfor this call only.wallclock_max (float, Optional) – Wallclock timeout in seconds for this run. Overrides
exit_criteria.wallclock_maxfor this call only.stop_val (tuple[str, float], Optional) – Stop criterion
(field, value)for this run. Overridesexit_criteria.stop_valfor this call only.dropdown: (..) –
MPI/comms Notes: Manager–worker intercommunications are parsed from the
commskey of libE_specs. An MPI runtime is assumed by default if-n Nwasn’t specified on the command-line orcomms="local"inlibE_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 ofCOMM_WORLDwill 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_sendandlibE_specs.reuse_output_dirare automatically set toTrueto 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 status0 = 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_pathinlibE_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. Ifappend_attrsis true, run attributes are appended to the stem.Returns the History filename on the manager and
Noneon other ranks.- Parameters:
basename (str)
append_attrs (bool)
- Return type:
str | None