libensemble


Namelibensemble JSON
Version 1.4.3 PyPI version JSON
download
home_pagehttps://github.com/Libensemble/libensemble
SummaryLibrary to coordinate the concurrent evaluation of dynamic ensembles of calculations
upload_time2024-12-16 20:38:45
maintainerNone
docs_urlNone
authorJeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro
requires_pythonNone
licenseBSD 3-clause
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            |libE_logo|

|PyPI| |Conda| |Spack|

|Tests| |Coverage| |Docs| |Style| |JOSS|

.. after_badges_rst_tag

=====================================================================
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``:

.. code-block:: python

    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:**

- Ask questions or report issues on GitHub_.
- Email ``libEnsemble@lists.mcs.anl.gov`` to request `libEnsemble Slack page`_.
- Join the `libEnsemble mailing list`_ for updates about new releases.

**Further Information:**

- Documentation is provided by ReadtheDocs_.
- Contributions_ to libEnsemble are welcome.
- Browse production functions and workflows in the `Community Examples repository`_.

**Cite libEnsemble:**

.. code-block:: bibtex

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

.. |libE_logo| image:: https://raw.githubusercontent.com/Libensemble/libensemble/main/docs/images/libE_logo.png
   :align: middle
   :alt: libEnsemble
.. |PyPI| image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
   :target: https://pypi.org/project/libensemble
.. |Conda| image:: https://img.shields.io/conda/v/conda-forge/libensemble?color=blue
   :target: https://anaconda.org/conda-forge/libensemble
.. |Spack| image:: https://img.shields.io/spack/v/py-libensemble?color=blue
   :target: https://packages.spack.io/package.html?name=py-libensemble
.. |Tests| image:: https://github.com/Libensemble/libensemble/actions/workflows/extra.yml/badge.svg?branch=main
   :target: https://github.com/Libensemble/libensemble/actions
.. |Coverage| image:: https://codecov.io/github/Libensemble/libensemble/graph/badge.svg
   :target: https://codecov.io/github/Libensemble/libensemble
.. |Docs| image:: https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
   :target: https://libensemble.readthedocs.org/en/latest/
   :alt: Documentation Status
.. |Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: black
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.06031/status.svg
   :target: https://doi.org/10.21105/joss.06031
   :alt: JOSS Status

.. _Community Examples repository: https://github.com/Libensemble/libe-community-examples
.. _conda-forge: https://conda-forge.org/
.. _Contributions: https://github.com/Libensemble/libensemble/blob/main/CONTRIBUTING.rst
.. _docs: https://libensemble.readthedocs.io/en/main/advanced_installation.html
.. _GitHub: https://github.com/Libensemble/libensemble
.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
.. _libEnsemble Slack page: https://libensemble.slack.com
.. _MPICH: http://www.mpich.org/
.. _mpmath: http://mpmath.org/
.. _PyPI: https://pypi.org
.. _Quickstart: https://libensemble.readthedocs.io/en/main/introduction.html
.. _ReadtheDocs: http://libensemble.readthedocs.org/
.. _regression tests: https://github.com/Libensemble/libensemble/tree/main/libensemble/tests/regression_tests

.. |Inline Example| image:: https://colab.research.google.com/assets/colab-badge.svg
  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/readme_notebook.ipynb

.. |Simple Ensemble| image:: https://colab.research.google.com/assets/colab-badge.svg
  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/simple_sine/sine_tutorial_notebook.ipynb

.. |Ensemble with an MPI application| image:: https://colab.research.google.com/assets/colab-badge.svg
  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/forces_with_executor/forces_tutorial_notebook.ipynb

.. |Optimization example| image:: https://colab.research.google.com/assets/colab-badge.svg
  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/aposmm/aposmm_tutorial_notebook.ipynb

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Libensemble/libensemble",
    "name": "libensemble",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": null,
    "author": "Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro",
    "author_email": "libensemble@lists.mcs.anl.gov",
    "download_url": "https://files.pythonhosted.org/packages/1f/79/fa8c97d1bc5a1df4fe4286bb66ced3d19d42205beca928c1019dfb79ffcd/libensemble-1.4.3.tar.gz",
    "platform": null,
    "description": "|libE_logo|\n\n|PyPI| |Conda| |Spack|\n\n|Tests| |Coverage| |Docs| |Style| |JOSS|\n\n.. after_badges_rst_tag\n\n=====================================================================\nlibEnsemble: A complete toolkit for dynamic ensembles of calculations\n=====================================================================\n\nAdaptive, portable, and scalable software for connecting \"deciders\" to experiments or simulations.\n\n\u2022 **Dynamic ensembles**: Generate parallel tasks on-the-fly based on previous computations.\n\u2022 **Extreme portability and scaling**: Run on or across laptops, clusters, and leadership-class machines.\n\u2022 **Heterogeneous computing**: Dynamically and portably assign CPUs, GPUs, or multiple nodes.\n\u2022 **Application monitoring**: Ensemble members can run, monitor, and cancel apps.\n\u2022 **Data-flow between tasks**: Running ensemble members can send and receive data.\n\u2022 **Low start-up cost**: No additional background services or processes required.\n\nlibEnsemble is effective at solving design, decision, and inference problems on parallel resources.\n\n`Quickstart`_\n\nInstallation\n============\n\nInstall libEnsemble and its dependencies from PyPI_ using pip::\n\n    pip install libensemble\n\nOther install methods are described in the docs_.\n\nBasic Usage\n===========\n\nCreate an ``Ensemble``, then customize it with general settings, simulation and generator parameters,\nand an exit condition. Run the following four-worker example via ``python this_file.py``:\n\n.. code-block:: python\n\n    import numpy as np\n\n    from libensemble import Ensemble\n    from libensemble.gen_funcs.sampling import uniform_random_sample\n    from libensemble.sim_funcs.six_hump_camel import six_hump_camel\n    from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs\n\n    if __name__ == \"__main__\":\n\n        libE_specs = LibeSpecs(nworkers=4)\n\n        sim_specs = SimSpecs(\n            sim_f=six_hump_camel,\n            inputs=[\"x\"],\n            outputs=[(\"f\", float)],\n        )\n\n        gen_specs = GenSpecs(\n            gen_f=uniform_random_sample,\n            outputs=[(\"x\", float, 2)],\n            user={\n                \"gen_batch_size\": 50,\n                \"lb\": np.array([-3, -2]),\n                \"ub\": np.array([3, 2]),\n            },\n        )\n\n        exit_criteria = ExitCriteria(sim_max=100)\n\n        sampling = Ensemble(\n            libE_specs=libE_specs,\n            sim_specs=sim_specs,\n            gen_specs=gen_specs,\n            exit_criteria=exit_criteria,\n        )\n\n        sampling.add_random_streams()\n        sampling.run()\n\n        if sampling.is_manager:\n            sampling.save_output(__file__)\n            print(\"Some output data:\\n\", sampling.H[[\"x\", \"f\"]][:10])\n\n|Inline Example|\n\nTry some other examples live in Colab.\n\n+---------------------------------------------------------------+-------------------------------------+\n| Description                                                   | Try online                          |\n+===============================================================+=====================================+\n| Simple Ensemble that makes a Sine wave.                       | |Simple Ensemble|                   |\n+---------------------------------------------------------------+-------------------------------------+\n| Ensemble with an MPI application.                             | |Ensemble with an MPI application|  |\n+---------------------------------------------------------------+-------------------------------------+\n| Optimization example that finds multiple minima.              | |Optimization example|              |\n+---------------------------------------------------------------+-------------------------------------+\n\nThere are many more examples in the `regression tests`_.\n\nResources\n=========\n\n**Support:**\n\n- Ask questions or report issues on GitHub_.\n- Email ``libEnsemble@lists.mcs.anl.gov`` to request `libEnsemble Slack page`_.\n- Join the `libEnsemble mailing list`_ for updates about new releases.\n\n**Further Information:**\n\n- Documentation is provided by ReadtheDocs_.\n- Contributions_ to libEnsemble are welcome.\n- Browse production functions and workflows in the `Community Examples repository`_.\n\n**Cite libEnsemble:**\n\n.. code-block:: bibtex\n\n  @article{Hudson2022,\n    title   = {{libEnsemble}: A Library to Coordinate the Concurrent\n               Evaluation of Dynamic Ensembles of Calculations},\n    author  = {Stephen Hudson and Jeffrey Larson and John-Luke Navarro and Stefan M. Wild},\n    journal = {{IEEE} Transactions on Parallel and Distributed Systems},\n    volume  = {33},\n    number  = {4},\n    pages   = {977--988},\n    year    = {2022},\n    doi     = {10.1109/tpds.2021.3082815}\n  }\n\n.. |libE_logo| image:: https://raw.githubusercontent.com/Libensemble/libensemble/main/docs/images/libE_logo.png\n   :align: middle\n   :alt: libEnsemble\n.. |PyPI| image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue\n   :target: https://pypi.org/project/libensemble\n.. |Conda| image:: https://img.shields.io/conda/v/conda-forge/libensemble?color=blue\n   :target: https://anaconda.org/conda-forge/libensemble\n.. |Spack| image:: https://img.shields.io/spack/v/py-libensemble?color=blue\n   :target: https://packages.spack.io/package.html?name=py-libensemble\n.. |Tests| image:: https://github.com/Libensemble/libensemble/actions/workflows/extra.yml/badge.svg?branch=main\n   :target: https://github.com/Libensemble/libensemble/actions\n.. |Coverage| image:: https://codecov.io/github/Libensemble/libensemble/graph/badge.svg\n   :target: https://codecov.io/github/Libensemble/libensemble\n.. |Docs| image:: https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000\n   :target: https://libensemble.readthedocs.org/en/latest/\n   :alt: Documentation Status\n.. |Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/psf/black\n   :alt: Code style: black\n.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.06031/status.svg\n   :target: https://doi.org/10.21105/joss.06031\n   :alt: JOSS Status\n\n.. _Community Examples repository: https://github.com/Libensemble/libe-community-examples\n.. _conda-forge: https://conda-forge.org/\n.. _Contributions: https://github.com/Libensemble/libensemble/blob/main/CONTRIBUTING.rst\n.. _docs: https://libensemble.readthedocs.io/en/main/advanced_installation.html\n.. _GitHub: https://github.com/Libensemble/libensemble\n.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble\n.. _libEnsemble Slack page: https://libensemble.slack.com\n.. _MPICH: http://www.mpich.org/\n.. _mpmath: http://mpmath.org/\n.. _PyPI: https://pypi.org\n.. _Quickstart: https://libensemble.readthedocs.io/en/main/introduction.html\n.. _ReadtheDocs: http://libensemble.readthedocs.org/\n.. _regression tests: https://github.com/Libensemble/libensemble/tree/main/libensemble/tests/regression_tests\n\n.. |Inline Example| image:: https://colab.research.google.com/assets/colab-badge.svg\n  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/readme_notebook.ipynb\n\n.. |Simple Ensemble| image:: https://colab.research.google.com/assets/colab-badge.svg\n  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/simple_sine/sine_tutorial_notebook.ipynb\n\n.. |Ensemble with an MPI application| image:: https://colab.research.google.com/assets/colab-badge.svg\n  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/forces_with_executor/forces_tutorial_notebook.ipynb\n\n.. |Optimization example| image:: https://colab.research.google.com/assets/colab-badge.svg\n  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/aposmm/aposmm_tutorial_notebook.ipynb\n",
    "bugtrack_url": null,
    "license": "BSD 3-clause",
    "summary": "Library to coordinate the concurrent evaluation of dynamic ensembles of calculations",
    "version": "1.4.3",
    "project_urls": {
        "Homepage": "https://github.com/Libensemble/libensemble"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1f79fa8c97d1bc5a1df4fe4286bb66ced3d19d42205beca928c1019dfb79ffcd",
                "md5": "effd78dddbc983fafc7fa01e0ba67254",
                "sha256": "d30fd5ec93ae78a8e931765fd773b0693fde8b43130aca547c931230225c0f63"
            },
            "downloads": -1,
            "filename": "libensemble-1.4.3.tar.gz",
            "has_sig": false,
            "md5_digest": "effd78dddbc983fafc7fa01e0ba67254",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 6811245,
            "upload_time": "2024-12-16T20:38:45",
            "upload_time_iso_8601": "2024-12-16T20:38:45.258425Z",
            "url": "https://files.pythonhosted.org/packages/1f/79/fa8c97d1bc5a1df4fe4286bb66ced3d19d42205beca928c1019dfb79ffcd/libensemble-1.4.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-16 20:38:45",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Libensemble",
    "github_project": "libensemble",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "libensemble"
}
        
Elapsed time: 0.50962s