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

One worker runs a persistent generator and the other four run the forces simulations.

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"])}')

APOSMM with a Standardized Generator

This example from the regression tests demonstrates the v2.0 gest-api interface: a standardized APOSMM generator class parameterized by a VOCS object, paired with a gest-api simulator callable. The generator runs on the manager thread by default, leaving all workers available for simulations.

tests/regression_tests/test_asktell_aposmm_nlopt.py

"""
Runs libEnsemble with APOSMM with the NLopt local optimizer.

Execute via one of the following commands (e.g. 3 workers):
   mpiexec -np 4 python test_persistent_aposmm_nlopt.py
   python test_persistent_aposmm_nlopt.py --nworkers 3 --comms local
   python test_persistent_aposmm_nlopt.py --nworkers 3 --comms tcp

When running with the above commands, the number of concurrent evaluations of
the objective function will be 2, as one of the three workers will be the
persistent generator.
"""

# Do not change these lines - they are parsed by run-tests.sh
# TESTSUITE_COMMS: local mpi tcp
# TESTSUITE_NPROCS: 3

from math import gamma, pi, sqrt

import numpy as np

import libensemble.gen_funcs
from libensemble.executors.mpi_executor import MPIExecutor
from libensemble.sim_funcs import six_hump_camel

# Import libEnsemble items for this test

libensemble.gen_funcs.rc.aposmm_optimizers = "nlopt"
from time import time

from gest_api.vocs import VOCS

from libensemble import Ensemble
from libensemble.gen_classes import APOSMM
from libensemble.manager import LoggedException
from libensemble.specs import ExitCriteria, GenSpecs, SimSpecs
from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima


def six_hump_camel_func(x):
    """
    Definition of the six-hump camel
    """
    x1 = x["core"]
    x2 = x["edge"]
    term1 = (4 - 2.1 * x1**2 + (x1**4) / 3) * x1**2
    term2 = x1 * x2
    term3 = (-4 + 4 * x2**2) * x2**2

    return {"energy": term1 + term2 + term3}


# Main block is necessary only when using local comms with spawn start method (default on macOS and Windows).
if __name__ == "__main__":

    for run in range(3):

        workflow = Ensemble(parse_args=True)

        if workflow.is_manager:
            start_time = time()

        n = 2

        vocs = VOCS(
            variables={"core": [-3, 3], "edge": [-2, 2], "core_on_cube": [-3, 3], "edge_on_cube": [-2, 2]},
            objectives={"energy": "MINIMIZE"},
        )

        aposmm = APOSMM(
            vocs,
            max_active_runs=workflow.nworkers,  # should this match nworkers always? practically?
            variables_mapping={"x": ["core", "edge"], "x_on_cube": ["core_on_cube", "edge_on_cube"], "f": ["energy"]},
            initial_sample_size=100,
            sample_points=minima,
            localopt_method="LN_BOBYQA",
            rk_const=0.5 * ((gamma(1 + (n / 2)) * 5) ** (1 / n)) / sqrt(pi),
            xtol_abs=1e-6,
            ftol_abs=1e-6,
        )

        workflow.gen_specs = GenSpecs(
            generator=aposmm,
            vocs=vocs,
            batch_size=5,
            initial_batch_size=10,
        )

        if run == 0:
            workflow.sim_specs = SimSpecs(simulator=six_hump_camel_func, vocs=vocs)
            workflow.exit_criteria = ExitCriteria(sim_max=2000)