4. Script

Introduction || 1. Getting started || 2. Generator || 3. Simulator || 4. Script || 5. Next steps

Now lets write the script that configures our generator and simulator functions and starts libEnsemble.

Create an empty Python file named calling.py. In this file, we’ll start by importing NumPy, libEnsemble’s setup classes, the generator, and simulator function.

In a class called LibeSpecs we’ll specify the number of workers and the manager/worker intercommunication method. "local", refers to Python’s multiprocessing.

import numpy as np
from gest_api.vocs import VOCS
from sine_gen_std import RandomSample
from sine_sim import sim_find_sine

from libensemble import Ensemble
from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs

if __name__ == "__main__":  # Python-quirk required on macOS and windows
    libE_specs = LibeSpecs(nworkers=4, comms="local")

We configure the settings and specifications for our sim_f and gen_f functions in the GenSpecs and SimSpecs classes, which we saw previously being passed to our functions as dictionaries. These classes also describe to libEnsemble what inputs and outputs from those functions to expect.

    gen_specs = GenSpecs(
        generator=generator,  # Pass our generator and config to libEnsemble
        vocs=vocs,
        batch_size=4,
    )

    sim_specs = SimSpecs(
        sim_f=sim_find_sine,  # Our simulator function
        inputs=["x"],  # InputArray field names. "x" from gen_f output
        out=[("y", float)],  # sim_f output. "y" = sine("x")
    )  # sim_specs_end_tag

We then specify the circumstances where libEnsemble should stop execution in ExitCriteria.

    exit_criteria = ExitCriteria(sim_max=80)  # Stop libEnsemble after 80 simulations

Now we’re ready to write our libEnsemble libE function call. ensemble.H is the final version of the history array. ensemble.flag should be zero if no errors occur.

    ensemble = Ensemble(sim_specs, gen_specs, exit_criteria, libE_specs)
    ensemble.run()  # start the ensemble. Blocks until completion.

    history = ensemble.H  # start visualizing our results

    print([i for i in history.dtype.fields])  # (optional) to visualize our history array
    print(history)

That’s it! Now that these files are complete, we can run our simulation.

python calling.py

If everything ran perfectly and you included the above print statements, you should get something similar to the following output (although the columns might be rearranged).

["y", "sim_started_time", "gen_worker", "sim_worker", "sim_started", "sim_ended", "x", "allocated", "sim_id", "gen_ended_time"]
[(-0.37466051, 1.559+09, 2, 2,  True,  True, [-0.38403059],  True,  0, 1.559+09)
(-0.29279634, 1.559+09, 2, 3,  True,  True, [-2.84444261],  True,  1, 1.559+09)
( 0.29358492, 1.559+09, 2, 4,  True,  True, [ 0.29797487],  True,  2, 1.559+09)
(-0.3783986, 1.559+09, 2, 1,  True,  True, [-0.38806564],  True,  3, 1.559+09)
(-0.45982062, 1.559+09, 2, 2,  True,  True, [-0.47779319],  True,  4, 1.559+09)
...

In this arrangement, our output values are listed on the far left with the generated values being the fourth column from the right.

Two additional log files should also have been created. ensemble.log contains debugging or informational logging output from libEnsemble, while libE_stats.txt contains a quick summary of all calculations performed.

Here is graphed output using Matplotlib, with entries colored by which worker performed the simulation:

If you want to verify your results through plotting and installed Matplotlib earlier, copy and paste the following code into the bottom of your calling script and run python calling.py again

    import matplotlib.pyplot as plt

    colors = ["b", "g", "r", "y", "m", "c", "k", "w"]

    for i in range(1, libE_specs.nworkers + 1):  # type: ignore
        worker_xy = np.extract(history["sim_worker"] == i, history)
        x = [entry.tolist() for entry in worker_xy["x"]]
        y = [entry for entry in worker_xy["y"]]
        plt.scatter(x, y, label="Worker {}".format(i), c=colors[i - 1])

    plt.title("Sine calculations for a uniformly sampled random distribution")
    plt.xlabel("x")
    plt.ylabel("sine(x)")
    plt.legend(loc="lower right")
    plt.savefig("tutorial_sines.png")

Each of these example files can be found in the repository in examples/tutorials/simple_sine.

Exercise

Write a Calling Script with the following specifications:

1. Set the generator function’s lower and upper bounds to -6 and 6, respectively

2. Increase the generator batch size to 10

3. Set libEnsemble to stop execution after 160 generations using the gen_max option

4. Print an error message if any errors occurred while libEnsemble was running

Click Here for Solution

import numpy as np
from sine_gen import gen_random_sample
from sine_sim import sim_find_sine

from libensemble import Ensemble
from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
from libensemble.specs import AllocSpecs, ExitCriteria, GenSpecs, LibeSpecs, SimSpecs

if __name__ == "__main__":
    libE_specs = LibeSpecs(nworkers=4, comms="local")

    gen_specs = GenSpecs(
        gen_f=gen_random_sample,  # Our generator function
        out=[("x", float, (1,))],  # gen_f output (name, type, size)
        batch_size=10,  # number of x's gen_f generates per call
        user={
            "lower": np.array([-6]),  # lower boundary for random sampling
            "upper": np.array([6]),  # upper boundary for random sampling
        },
    )

    sim_specs = SimSpecs(
        sim_f=sim_find_sine,  # Our simulator function
        inputs=["x"],  # InputArray field names. "x" from gen_f output
        out=[("y", float)],  # sim_f output. "y" = sine("x")
    )

    alloc_specs = AllocSpecs(alloc_f=give_sim_work_first)

    exit_criteria = ExitCriteria(gen_max=160)

    ensemble = Ensemble(sim_specs, gen_specs, exit_criteria, libE_specs, alloc_specs)
    ensemble.run()

    if ensemble.flag != 0:
        print("Oh no! An error occurred!")