Running an Ensemble

class libensemble.ensemble.Ensemble

The primary object for a libEnsemble workflow. Parses and validates settings, sets up logging, and maintains output.

Example
 1import numpy as np
 2
 3from libensemble import Ensemble
 4from libensemble.gen_funcs.sampling import latin_hypercube_sample
 5from libensemble.sim_funcs.simple_sim import norm_eval
 6from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs
 7
 8libE_specs = LibeSpecs(nworkers=4)
 9sampling = Ensemble(libE_specs=libE_specs)
10sampling.sim_specs = SimSpecs(
11    sim_f=norm_eval,
12    inputs=["x"],
13    outputs=[("f", float)],
14)
15sampling.gen_specs = GenSpecs(
16    gen_f=latin_hypercube_sample,
17    outputs=[("x", float, (1,))],
18    user={
19        "gen_batch_size": 50,
20        "lb": np.array([-3]),
21        "ub": np.array([3]),
22    },
23)
24
25sampling.add_random_streams()
26sampling.exit_criteria = ExitCriteria(sim_max=100)
27
28if __name__ == "__main__":
29    sampling.run()
30    sampling.save_output(__file__)

Run the above example via python this_file.py.

Instead of using the libE_specs line, you can also use sampling = Ensemble(parse_args=True) and run via python this_file.py -n 4 (4 workers). The parse_args=True parameter instructs the Ensemble class to read command-line arguments.

Configure by:

Option 1: Providing parameters on instantiation
 1from libensemble import Ensemble
 2from my_simulator import sim_find_energy
 3
 4sim_specs = {
 5    "sim_f": sim_find_energy,
 6    "in": ["x"],
 7    "out": [("y", float)],
 8}
 9
10experiment = Ensemble(sim_specs=sim_specs)
Option 2: Assigning parameters to an instance
 1from libensemble import Ensemble, SimSpecs
 2from my_simulator import sim_find_energy
 3
 4sim_specs = SimSpecs(
 5    sim_f=sim_find_energy,
 6    inputs=["x"],
 7    outputs=[("y", float)],
 8)
 9
10experiment = Ensemble()
11experiment.sim_specs = sim_specs
Option 3: Loading parameters from files
1from libensemble import Ensemble
2
3experiment = Ensemble()
4
5my_experiment.from_yaml("my_parameters.yaml")
6# or...
7my_experiment.from_toml("my_parameters.toml")
8# or...
9my_experiment.from_json("my_parameters.json")

 1libE_specs:
 2    save_every_k_gens: 20
 3
 4exit_criteria:
 5    sim_max: 80
 6
 7gen_specs:
 8    gen_f: generator.gen_random_sample
 9    outputs:
10        x:
11            type: float
12            size: 1
13    user:
14        gen_batch_size: 5
15
16sim_specs:
17    sim_f: simulator.sim_find_sine
18    inputs:
19        - x
20    outputs:
21        y:
22            type: float

 1[libE_specs]
 2    save_every_k_gens = 300
 3
 4[exit_criteria]
 5    sim_max = 80
 6
 7[gen_specs]
 8    gen_f = "generator.gen_random_sample"
 9    [gen_specs.outputs]
10        [gen_specs.outputs.x]
11            type = "float"
12            size = 1
13    [gen_specs.user]
14        gen_batch_size = 5
15
16[sim_specs]
17    sim_f = "simulator.sim_find_sine"
18    inputs = ["x"]
19    [sim_specs.outputs]
20        [sim_specs.outputs.y]
21            type = "float"

 1{
 2    "libE_specs": {
 3        "save_every_k_gens": 300,
 4    },
 5    "exit_criteria": {
 6        "sim_max": 80
 7    },
 8    "gen_specs": {
 9        "gen_f": "generator.gen_random_sample",
10        "outputs": {
11            "x": {
12                "type": "float",
13                "size": 1
14            }
15        },
16        "user": {
17            "gen_batch_size": 5
18        }
19    },
20    "sim_specs": {
21        "sim_f": "simulator.sim_find_sine",
22        "inputs": ["x"],
23        "outputs": {
24            "f": {"type": "float"}
25        }
26    }
27}
Parameters:

  • sim_specs (dict or SimSpecs) – Specifications for the simulation function

  • gen_specs (dict or GenSpecs, Optional) – Specifications for the generator function

  • exit_criteria (dict or ExitCriteria, Optional) – Tell libEnsemble when to stop a run

  • libE_specs (dict or LibeSpecs, Optional) – Specifications for libEnsemble

  • alloc_specs (dict or 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 simulation or generator functions

  • 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()

Quickly verify that all necessary data has been provided

Return type:

bool

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 --comms local wasn’t specified on the command-line or in libE_specs.

If a MPI communicator was provided in libE_specs, then each .run() call will initiate intercommunications 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:

(numpy.ndarray[tuple[int, …], numpy.dtype[+_ScalarType_co]], <class ‘dict’>, <class ‘int’>)

from_yaml(file_path)

Parameterizes libEnsemble from yaml file

Parameters:

file_path (str)

from_toml(file_path)

Parameterizes libEnsemble from toml file

Parameters:

file_path (str)

from_json(file_path)

Parameterizes libEnsemble from json file

Parameters:

file_path (str)

add_random_streams(num_streams=0, seed='')

Adds np.random generators for each worker ID to self.persis_info.

Parameters:

  • num_streams (int, Optional) – Number of matching worker ID and random stream entries to create. Defaults to self.nworkers.

  • seed (str, Optional) – Seed for NumPy’s RNG.

save_output(basename, append_attrs=True)

Writes out History array and persis_info to files. If using a workflow_dir, 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)