From 1d50bd2885ad5e48f70a48f5edeac269016c91b4 Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 11:24:14 +0200 Subject: [PATCH 1/9] Update readme and add citation --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e9c47cd2..b3b2577a 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,71 @@ -

- optimas logo -

- - -# Optimization at scale, powered by [libEnsemble](https://libensemble.readthedocs.io/) [![PyPI](https://img.shields.io/pypi/v/optimas)](https://pypi.org/project/optimas/) [![tests badge](https://github.com/optimas-org/optimas/actions/workflows/unix.yml/badge.svg)](https://github.com/optimas-org/optimas/actions) [![Documentation Status](https://readthedocs.org/projects/optimas/badge/?version=latest)](https://optimas.readthedocs.io/en/latest/?badge=latest) [![DOI](https://zenodo.org/badge/287560975.svg)](https://zenodo.org/badge/latestdoi/287560975) [![License](https://img.shields.io/pypi/l/optimas.svg)](license.txt) + +
+
+ + optimas logo + + +

+ Optimization at scale, powered by + libEnsemble +

+ +

+ Explore the docs » +
+
+ View Examples + · + Support + · + API Reference +

+
+ Optimas is a Python library for scalable optimization on massively-parallel supercomputers. See the [documentation](https://optimas.readthedocs.io/) for installation instructions, tutorials, and more information. + +## Installation +Optimas can be directly installed form PyPI +```sh +pip install optimas +``` +For detailed instructions about how to install optimas in HPC systems check the [guide](https://optimas.readthedocs.io/en/latest/user_guide/installation.html#instructions) in the documentation. + +## Citing optimas +If your usage of `optimas` leads to a scientific publication, please consider citing the optimas paper: +```bibtex +@article{PhysRevAccelBeams.26.084601, + title = {Bayesian optimization of laser-plasma accelerators assisted by reduced physical models}, + author = {Ferran Pousa, A. and Jalas, S. and Kirchen, M. and Martinez de la Ossa, A. and Th\'evenet, M. and Hudson, S. and Larson, J. and Huebl, A. and Vay, J.-L. and Lehe, R.}, + journal = {Phys. Rev. Accel. Beams}, + volume = {26}, + issue = {8}, + pages = {084601}, + numpages = {9}, + year = {2023}, + month = {Aug}, + publisher = {American Physical Society}, + doi = {10.1103/PhysRevAccelBeams.26.084601}, + url = {https://link.aps.org/doi/10.1103/PhysRevAccelBeams.26.084601} +} +``` +and libEnsemble: +```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} +} +``` From 28732e87dd3bffaf767f68fcdda68bd8b5d5c9ed Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 11:29:03 +0200 Subject: [PATCH 2/9] Update slack link --- README.md | 2 +- doc/source/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b3b2577a..d3cf2ec2 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@
View Examples · - Support + Support · API Reference

diff --git a/doc/source/conf.py b/doc/source/conf.py index 06fbf8cd..b3da5f51 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -80,7 +80,7 @@ }, { "name": "Slack", - "url": "https://optimas.slack.com/", + "url": "https://optimas-group.slack.com/", "icon": "fa-brands fa-slack", }, ], From 1d685e627d8ac8037b7fec586a0f93cba653e227 Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:18:18 +0200 Subject: [PATCH 3/9] Update local installation instructions --- doc/source/user_guide/installation_local.rst | 24 -------------------- 1 file changed, 24 deletions(-) diff --git a/doc/source/user_guide/installation_local.rst b/doc/source/user_guide/installation_local.rst index 191d875c..e9f738d3 100644 --- a/doc/source/user_guide/installation_local.rst +++ b/doc/source/user_guide/installation_local.rst @@ -3,30 +3,6 @@ Installation on a local computer The recommended approach is to install optimas in a ``conda`` environment. -Install basic dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: - - conda install numpy pandas - -Install PyTorch -~~~~~~~~~~~~~~~ - -If your computer does not feature a CUDA-capable GPU, install PyTorch for CPU: - -.. code:: - - conda install pytorch cpuonly -c pytorch - - -If you have a CUDA-capable GPU and want to take make it available to optimas, -install PyTorch with: - -.. code:: - - conda install pytorch pytorch-cuda=11.7 -c pytorch -c nvidia - Install ``mpi4py`` ~~~~~~~~~~~~~~~~~~ If your system has already an MPI implementation installed, install ``mpi4py`` From 8f7d188844646a2f76ff3b3194037a2c9d8e93ef Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:20:27 +0200 Subject: [PATCH 4/9] Update dependencies --- doc/source/user_guide/installation.rst | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/installation.rst index fb078224..d7eeddc5 100644 --- a/doc/source/user_guide/installation.rst +++ b/doc/source/user_guide/installation.rst @@ -1,30 +1,9 @@ -Installing optimas -================== -Optimas is supported on Python 3.8 and above. The package can be installed from -PyPI using ``pip`` or directly from GitHub. - - Dependencies ------------- +============ + Optimas relies on the following packages: -* `NumPy `_ - Basic dependency for array operations. -* `Pandas `_ - Data analysis library required for post-processing and other dependencies. * `mpi4py `_ - Python bindings for MPI. Required for launching parallel simulations. * `libEnsemble `_ - The backbone of optimas, orchestrates the concurrent evaluation of simulations, the resource detection and allocation, and the communication between simulations and manager. * `jinja2 `_ - Needed to generate simulation scripts from templates. -* `Pytorch `_ - Required by the Bayesian optimization generators. * `Ax `_ - Algorithms for Bayesian optimization. - -Instructions ------------- -Step-by-step instructions for installing optimas on a local computer and on -different HPC clusters: - -.. toctree:: - :maxdepth: 1 - - installation_local - installation_maxwell - installation_juwels - installation_perlmutter From 4b66365b5b43b7227f65e48e03e01ae9f0113e6c Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:21:01 +0200 Subject: [PATCH 5/9] Rename file --- doc/source/user_guide/{installation.rst => dependencies.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/source/user_guide/{installation.rst => dependencies.rst} (100%) diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/dependencies.rst similarity index 100% rename from doc/source/user_guide/installation.rst rename to doc/source/user_guide/dependencies.rst From b1e4ff2a67b0cabfa70d536aa73b8d9ce6e0941e Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:22:36 +0200 Subject: [PATCH 6/9] Rearrange user guide --- doc/source/user_guide/index.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 8d508e84..76fcedfe 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -4,10 +4,14 @@ User guide ========== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Installation - installation + dependencies + installation_local + installation_maxwell + installation_juwels + installation_perlmutter .. toctree:: :maxdepth: 2 From 61af0d098bb2f6e3ce7cec9cecdcf082289f785b Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:40:09 +0200 Subject: [PATCH 7/9] Update readme --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d3cf2ec2..b4b358a1 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,21 @@ Optimas is a Python library for scalable optimization on massively-parallel supercomputers. See the [documentation](https://optimas.readthedocs.io/) for installation instructions, tutorials, and more information. ## Installation -Optimas can be directly installed form PyPI +From PyPI ```sh pip install optimas ``` -For detailed instructions about how to install optimas in HPC systems check the [guide](https://optimas.readthedocs.io/en/latest/user_guide/installation.html#instructions) in the documentation. +From GitHub +```sh +pip install git+https://github.com/optimas-org/optimas.git +``` +Make sure `mpi4py` is available in your environment prior to installing optimas (see [here](https://optimas.readthedocs.io/en/latest/user_guide/installation_local.html) for more details). + +Optimas is regularly used and tested in large distributed HPC systems. +We have prepared installation instructions for +[JUWELS (JSC)](https://optimas.readthedocs.io/en/latest/user_guide/installation_juwels.html), +[Maxwell (DESY)](https://optimas.readthedocs.io/en/latest/user_guide/installation_maxwell.html) and +[Perlmutter (NERSC)](https://optimas.readthedocs.io/en/latest/user_guide/installation_perlmutter.html). ## Citing optimas If your usage of `optimas` leads to a scientific publication, please consider citing the optimas paper: From 9f912f504d7e94f1ff7ee4a2bba1cf6200befaf8 Mon Sep 17 00:00:00 2001 From: Angel Ferran Pousa Date: Fri, 18 Aug 2023 13:46:37 +0200 Subject: [PATCH 8/9] Add citation information --- README.md | 2 +- doc/source/user_guide/citation.rst | 38 ++++++++++++++++++++++++++++++ doc/source/user_guide/index.rst | 8 ++++++- 3 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 doc/source/user_guide/citation.rst diff --git a/README.md b/README.md index b4b358a1..93ab285c 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ We have prepared installation instructions for [Perlmutter (NERSC)](https://optimas.readthedocs.io/en/latest/user_guide/installation_perlmutter.html). ## Citing optimas -If your usage of `optimas` leads to a scientific publication, please consider citing the optimas paper: +If your usage of `optimas` leads to a scientific publication, please consider citing the original [paper](https://link.aps.org/doi/10.1103/PhysRevAccelBeams.26.084601): ```bibtex @article{PhysRevAccelBeams.26.084601, title = {Bayesian optimization of laser-plasma accelerators assisted by reduced physical models}, diff --git a/doc/source/user_guide/citation.rst b/doc/source/user_guide/citation.rst new file mode 100644 index 00000000..682ab91b --- /dev/null +++ b/doc/source/user_guide/citation.rst @@ -0,0 +1,38 @@ +Citing optimas +============== + +If your usage of ``optimas`` leads to a scientific publication, please consider +citing the original `paper `_: + +.. code-block:: bibtex + + @article{PhysRevAccelBeams.26.084601, + title = {Bayesian optimization of laser-plasma accelerators assisted by reduced physical models}, + author = {Ferran Pousa, A. and Jalas, S. and Kirchen, M. and Martinez de la Ossa, A. and Th\'evenet, M. and Hudson, S. and Larson, J. and Huebl, A. and Vay, J.-L. and Lehe, R.}, + journal = {Phys. Rev. Accel. Beams}, + volume = {26}, + issue = {8}, + pages = {084601}, + numpages = {9}, + year = {2023}, + month = {Aug}, + publisher = {American Physical Society}, + doi = {10.1103/PhysRevAccelBeams.26.084601}, + url = {https://link.aps.org/doi/10.1103/PhysRevAccelBeams.26.084601} + } + +and 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} + } \ No newline at end of file diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 76fcedfe..1ebbc0d5 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -19,4 +19,10 @@ User guide basic_usage/basic_setup basic_usage/running_with_simulations - basic_usage/analyze_output \ No newline at end of file + basic_usage/analyze_output + +.. toctree:: + :maxdepth: 1 + :caption: Citation + + citation From 578d89c0744110e47e90c1bb1e6fec2141f62de5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81ngel=20Ferran=20Pousa?= Date: Fri, 18 Aug 2023 20:16:50 +0200 Subject: [PATCH 9/9] Make grid single column in small screens --- doc/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 7e3c6ee2..dd7b73b9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,7 +12,7 @@ parallel optimization, from a typical laptop to exascale HPC systems. It is built on top of `libEnsemble `_. -.. grid:: 3 +.. grid:: 1 1 3 3 :gutter: 2 .. grid-item-card:: User guide