Skip to content
Library for managing ensemble-like collections of computations
Python TeX Shell C Other
Branch: master
Clone or download
shuds13 Merge pull request #201 from Libensemble/hotfix/update_auth_ver_quick…

Fix citation with new author and version number in quickstart
Latest commit ee15f2c Jul 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
conda Try remove no-update-deps on scipy and mpi4py Jun 28, 2019
docs Fix citation with new author and version number in quickstart Jul 11, 2019
libensemble Update author list Jul 11, 2019
postproc_scripts Update readme for plot scripts Mar 20, 2019
tex Removing GKLS from planning_doc Dec 1, 2017
.flake8 Trying flake8 again May 28, 2019
.gitignore Gitignoring docs/_build Aug 6, 2018
.readthedocs.yml Add setup_py_install: true May 21, 2019
.style.yapf Whitespace before inline comments Apr 25, 2019
.travis.yml Try remove no-update-deps on scipy and mpi4py Jun 28, 2019
CONTRIBUTING.rst Update CONTRIBUTING.rst Jul 8, 2019
LICENSE Updating LICENSE file Dec 13, 2018 Update MANIFEST for sdist Jun 28, 2018
README.rst Updated README TeX citation with new author and version number Jul 11, 2019 Update author list Jul 11, 2019


libEnsemble Documentation Status

What is libEnsemble?

libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles of computations. Designed with flexibility in mind, libEnsemble can utilize massively parallel resources to accelerate the solution of design, decision, and inference problems.

libEnsemble aims for:

  • Extreme scaling
  • Fault tolerance
  • Monitoring/killing jobs (recovers resources)
  • Portability and flexibility
  • Exploitation of persistent data/control flow.

A more detailed overview can be found in the docs.

A visual overview is given in the libEnsemble poster.


Required dependencies:

For libEnsemble running with the mpi4py parallelism:

  • A functional MPI 1.x/2.x/3.x implementation such as MPICH built with shared/dynamic libraries.
  • mpi4py v2.0.0 or above

Optional dependency:

From v0.2.0, libEnsemble has the option of using the Balsam job manager. This is required for running libEnsemble on the compute nodes of some supercomputing platforms (eg. Cray XC40); platforms that do not support launching jobs from compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the launch nodes using multiprocessing.

The example sim and gen functions and tests require the following dependencies:

PETSc and NLopt must be built with shared libraries enabled and present in sys.path (eg. via setting the PYTHONPATH environment variable). NLopt should produce a file if Python is found on the system.


Use pip to install libEnsemble and its dependencies:

pip install libensemble

libEnsemble is also available in the Spack distribution. It can be installed from Spack with:

spack install py-libensemble

The tests and examples can be accessed in the github repository. A tarball of the most recent release is also available.


The provided test suite includes both unit and regression tests and is run regularly on:

The test suite requires the mock, pytest, pytest-cov and pytest-timeout packages to be installed and can be run from the libensemble/tests directory of the source distribution by running:


To clean the test repositories run:

./ -c

Further options are available. To see a complete list of options run:

./ -h

Coverage reports are produced separately for unit tests and regression tests under the relevant directories. For parallel tests, the union of all processors is taken. Furthermore, a combined coverage report is created at the top level, which can be viewed after running the tests via the html file libensemble/tests/cov_merge/index.html. The Travis CI coverage results are given online at Coveralls.

Note: The job_controller tests can be run using the direct-launch or Balsam job controllers. However, currently only the direct-launch versions can be run on Travis CI, which reduces the test coverage results.

Basic Usage

The examples directory contains example libEnsemble calling scripts, sim functions, gen functions, alloc functions and job submission scripts.

See the user-guide for more information.


Citing libEnsemble

Please use the following to cite libEnsemble in a publication:

  author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and David Bindel and John-Luke Navarro},
  title       = {{libEnsemble} Users Manual},
  institution = {Argonne National Laboratory},
  number      = {Revision 0.5.1},
  year        = {2019},
  url         = {}


Join the libEnsemble mailing list at:

or email questions to:

or communicate (and establish a private channel, if desired) at:

You can’t perform that action at this time.