libEnsemble: A complete toolkit for dynamic ensembles of calculations

Adaptive, portable, and scalable software for connecting “deciders” to experiments or simulations.

  • Dynamic ensembles: Generate parallel tasks on-the-fly based on previous computations.

  • Extreme portability and scaling: Run on or across laptops, clusters, and leadership-class machines.

  • Heterogeneous computing: Dynamically and portably assign CPUs, GPUs, or multiple nodes.

  • Application monitoring: Ensemble members can run, monitor, and cancel apps.

  • Data-flow between tasks: Running ensemble members can send and receive data.

  • Low start-up cost: No additional background services or processes required.

libEnsemble is effective at solving design, decision, and inference problems on parallel resources.

Quickstart

Installation

Install libEnsemble and its dependencies from PyPI using pip:

pip install libensemble

Other install methods are described in the docs.

Resources

Support:

Further Information:

Cite libEnsemble:

@article{Hudson2022,
  title   = {{libEnsemble}: A Library to Coordinate the Concurrent
             Evaluation of Dynamic Ensembles of Calculations},
  author  = {Stephen Hudson and Jeffrey Larson and John-Luke Navarro and Stefan M. Wild},
  journal = {{IEEE} Transactions on Parallel and Distributed Systems},
  volume  = {33},
  number  = {4},
  pages   = {977--988},
  year    = {2022},
  doi     = {10.1109/tpds.2021.3082815}
}

Basic Usage

Create an Ensemble, then customize with general settings, simulation and generator parameters, and an exit condition. Run the following via python this_file.py --comms local --nworkers 4:

 1import numpy as np
 2
 3from libensemble import Ensemble
 4from libensemble.gen_funcs.sampling import uniform_random_sample
 5from libensemble.sim_funcs.six_hump_camel import six_hump_camel
 6from libensemble.specs import ExitCriteria, GenSpecs, SimSpecs
 7from libensemble.tools import add_unique_random_streams
 8
 9if __name__ == "__main__":
10    sampling = Ensemble(parse_args=True)
11    sampling.sim_specs = SimSpecs(
12        sim_f=six_hump_camel,
13        inputs=["x"],
14        outputs=[("f", float)],
15    )
16    sampling.gen_specs = GenSpecs(
17        gen_f=uniform_random_sample,
18        outputs=[("x", float, (2,))],
19        user={
20            "gen_batch_size": 500,
21            "lb": np.array([-3, -2]),
22            "ub": np.array([3, 2]),
23        },
24    )
25
26    sampling.persis_info = add_unique_random_streams({}, sampling.nworkers + 1)
27    sampling.exit_criteria = ExitCriteria(sim_max=101)
28    sampling.run()
29    sampling.save_output(__file__)
30
31    if sampling.is_manager:
32        print("Some output data:\n", sampling.H[["x", "f"]][:10])

See the tutorial for a step-by-step beginners guide.

See the user guide for more information.

Example Compatible Packages

libEnsemble and the Community Examples repository include example generator functions for the following libraries:

  • APOSMM Asynchronously parallel optimization solver for finding multiple minima. Supported local optimization routines include:

    • DFO-LS Derivative-free solver for (bound constrained) nonlinear least-squares minimization

    • NLopt Library for nonlinear optimization, providing a common interface for various methods

    • scipy.optimize Open-source solvers for nonlinear problems, linear programming, constrained and nonlinear least-squares, root finding, and curve fitting.

    • PETSc/TAO Routines for the scalable (parallel) solution of scientific applications

  • DEAP Distributed evolutionary algorithms

  • Distributed optimization methods for minimizing sums of convex functions. Methods include:

  • ECNoise Estimating Computational Noise in Numerical Simulations

  • Surmise Modular Bayesian calibration/inference framework

  • Tasmanian Toolkit for Adaptive Stochastic Modeling and Non-Intrusive ApproximatioN

  • VTMOP Fortran package for large-scale multiobjective multidisciplinary design optimization

libEnsemble has also been used to coordinate many computationally expensive simulations. Select examples include: