libEnsemble

Library for managing ensemble-like collections of computations.

Dependencies

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

Optional dependency:

• Balsam

From v0.2.0, libEnsemble has the option of using the Balsam job manager. This is required for running on some supercomputing platforms (eg. Cray XC40); platforms which do not support launching jobs on compute nodes.

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

• SciPy
• petsc4py
• PETSc - This can optionally be installed by pip along with petsc4py
• NLopt - Installed with shared libraries enabled.

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 nlopt.py if Python is found on the system.

Installation

You can use pip to install libEnsemble and its dependencies:

pip install libensemble

Libensemble is also available in the Spack distribution.

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

Testing

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

• Travis CI

The test suite requires the 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:

./run-tests.sh

To clean the test repositories run:

./run-tests.sh -c

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

./run-tests.sh -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.

Documentation

• http://libensemble.readthedocs.org/

Support

You can join the libEnsemble mailing list at:

• https://lists.mcs.anl.gov/mailman/listinfo/libensemble

or email questions to:

• [email protected]