Skip to main content

Library to coordinate the concurrent evaluation of dynamic ensembles of calculations

Project description

libEnsemble

PyPI Conda Spack

Tests Coverage Documentation Status Code style: black JOSS Status

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.

Basic Usage

Create an Ensemble, then customize it with general settings, simulation and generator parameters, and an exit condition. Run the following four-worker example via python this_file.py:

import numpy as np

from libensemble import Ensemble
from libensemble.gen_funcs.sampling import uniform_random_sample
from libensemble.sim_funcs.six_hump_camel import six_hump_camel
from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs

if __name__ == "__main__":

    libE_specs = LibeSpecs(nworkers=4)

    sim_specs = SimSpecs(
        sim_f=six_hump_camel,
        inputs=["x"],
        outputs=[("f", float)],
    )

    gen_specs = GenSpecs(
        gen_f=uniform_random_sample,
        outputs=[("x", float, 2)],
        user={
            "gen_batch_size": 50,
            "lb": np.array([-3, -2]),
            "ub": np.array([3, 2]),
        },
    )

    exit_criteria = ExitCriteria(sim_max=100)

    sampling = Ensemble(
        libE_specs=libE_specs,
        sim_specs=sim_specs,
        gen_specs=gen_specs,
        exit_criteria=exit_criteria,
    )

    sampling.add_random_streams()
    sampling.run()

    if sampling.is_manager:
        sampling.save_output(__file__)
        print("Some output data:\n", sampling.H[["x", "f"]][:10])

Inline Example

Try some other examples live in Colab.

Description

Try online

Simple Ensemble that makes a Sine wave.

Simple Ensemble

Ensemble with an MPI application.

Ensemble with an MPI application

Optimization example that finds multiple minima.

Optimization example

There are many more examples in the regression tests.

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}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

libensemble-1.4.2.tar.gz (6.8 MB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page