Top-Level Scripts

Many other examples of top-level scripts can be found in libEnsemble’s regression tests.

Local Sine Tutorial

This example is from the Local Sine Tutorial, meant to run with Python’s multiprocessing as the primary comms method.

examples/tutorials/simple_sine/test_local_sine_tutorial.py

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")

    vocs = VOCS(variables={"x": [-3, 3]}, objectives={"y": "EXPLORE"})  # Configure our generator with this object

    generator = RandomSample(vocs)  # Instantiate our generator

    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

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

    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)

    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")

Electrostatic Forces with Executor

These examples are from a test for evaluating the scaling capabilities of libEnsemble by calculating particle electrostatic forces through a user application. This application is registered with the MPIExecutor, then submitted for execution in the sim_f. Note the use of the parse_args=True which allows reading arguments such as the number of workers from the command line.

Traditional Version

Run using five workers with:

python run_libe_forces.py -n 5

tests/scaling_tests/forces/forces_simple/run_libe_forces.py

#!/usr/bin/env python
import os
import sys
from pathlib import Path

import numpy as np
from forces_simf import run_forces  # Sim func from current dir

from libensemble import Ensemble
from libensemble.executors import MPIExecutor
from libensemble.gen_funcs.persistent_sampling import persistent_uniform as gen_f
from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs

if __name__ == "__main__":
    # Initialize MPI Executor
    exctr = MPIExecutor()

    # Register simulation executable with executor
    sim_app = Path.cwd() / "../forces_app/forces.x"

    if not os.path.isfile(sim_app):
        sys.exit("forces.x not found - please build first in ../forces_app dir")

    exctr.register_app(full_path=sim_app, app_name="forces")

    # Parse number of workers, comms type, etc. from arguments
    ensemble = Ensemble(parse_args=True, executor=exctr)
    nsim_workers = ensemble.nworkers - 1  # One worker is for persistent generator

    # Persistent gen does not need resources
    ensemble.libE_specs = LibeSpecs(
        num_resource_sets=nsim_workers,
        sim_dirs_make=True,
    )

    ensemble.sim_specs = SimSpecs(
        sim_f=run_forces,
        inputs=["x"],
        outputs=[("energy", float)],
    )

    ensemble.gen_specs = GenSpecs(
        gen_f=gen_f,
        inputs=[],  # No input when start persistent generator
        persis_in=["sim_id"],  # Return sim_ids of evaluated points to generator
        outputs=[("x", float, (1,))],
        initial_batch_size=nsim_workers,
        async_return=False,
        user={
            "lb": np.array([1000]),  # min particles
            "ub": np.array([3000]),  # max particles
        },
    )

    # Starts one persistent generator. Simulated values are returned in batch.

    # Instruct libEnsemble to exit after this many simulations
    ensemble.exit_criteria = ExitCriteria(sim_max=8)

    # Run ensemble
    ensemble.run()

    if ensemble.is_manager:
        # Note, this will change if changing sim_max, nworkers, lb, ub, etc.
        print(f'Final energy checksum: {np.sum(ensemble.H["energy"])}')

gest-api APOSMM

This example from the regression tests demonstrates the gest-api interface with a standardized APOSMM generator class parameterized by a VOCS object, and paired with a gest-api simulator callable.