From 50b97b80b8c75bcd10e66c5fe27a8dcff1378a62 Mon Sep 17 00:00:00 2001 From: Moritz Schreiber <68053396+mosc9575@users.noreply.github.com> Date: Tue, 2 Dec 2025 14:07:35 +0100 Subject: [PATCH 1/4] reactivate status badge and fix minor issues in readme.md --- README.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 9128e1b2b..13363f6fa 100644 --- a/README.rst +++ b/README.rst @@ -4,13 +4,12 @@ mpi-sppy Optimization under uncertainty for `Pyomo `_ models. `Documentation is available at readthedocs `_ and -a there is a `paper `_ +there is a `paper `_. Status for internal tests ^^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: https://github.com/Pyomo/mpi-sppy/workflows/pyotracker/badge.svg - :target: https://github.com/Pyomo/mpi-sppy/actions/workflows/pyotracker.yml +[![pyo tracker](https://github.com/Pyomo/mpi-sppy/actions/workflows/pyotracker.yml/badge.svg)](https://github.com/Pyomo/mpi-sppy/actions/workflows/pyotracker.yml) MPI @@ -22,13 +21,13 @@ Here are two methods that seem to work well for installation, at least when cons #. Install OpenMPI and mpi4py using conda. - * ``conda install openmpi; conda install mpi4py`` (in that order) - + * ``conda install openmpi; conda install mpi4py`` (in that order) + #. If you already have an existing version of MPI, it may be better compile mpi4py against it. This can be done by installing mpi4py though pip. * ``pip install mpi4py`` -#. It is also possible to automate mpi4py installation through pip as an optional dependency when installing mpi-sppy from pip or from source by adding the `[mpi]` extras flag. +#. It is also possible to automate mpi4py installation through pip as an optional dependency when installing mpi-sppy from pip or from source by adding the `[mpi]` extras flag. * ``pip install -e .[mpi]`` (after cloning and moving to the repo root directory) @@ -48,7 +47,7 @@ Installing mpi-sppy ^^^^^^^^^^^^^^^^^^^ It is possible to pip install mpi-sppy; however, most users are better off -getting the software from github because it is under active development. +getting the software from Github because it is under active development. Citing mpi-sppy ^^^^^^^^^^^^^^^ @@ -58,7 +57,7 @@ If you find mpi-sppy useful in your work, we kindly request that you cite the fo @article{mpi-sppy, title={A Parallel Hub-and-Spoke System for Large-Scale Scenario-Based Optimization Under Uncertainty}, - author={Bernard Knueven and David Mildebrath and Christopher Muir and John D Siirola and Jean-Paul Watson and David L Woodruff}, + author={Bernard Knueven and David Mildebrath and Christopher Muir and John D Siirola and Jean-Paul Watson and David L Woodruff}, journal = {Math. Prog. Comp.}, volume = {15}, pages = {591-–619}, From 21a391f79026bf0317fc8c41ea87700de072c16a Mon Sep 17 00:00:00 2001 From: Moritz Schreiber <68053396+mosc9575@users.noreply.github.com> Date: Tue, 2 Dec 2025 22:07:28 +0100 Subject: [PATCH 2/4] Update and rename README.rst to README.md Highlighting and formatting ist done by markdown (MD) instead of ReStructuredText (RST). --- README.rst => README.md | 84 ++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 39 deletions(-) rename README.rst => README.md (57%) diff --git a/README.rst b/README.md similarity index 57% rename from README.rst rename to README.md index 13363f6fa..1d9738d3f 100644 --- a/README.rst +++ b/README.md @@ -1,41 +1,46 @@ mpi-sppy ======== -Optimization under uncertainty for `Pyomo `_ models. +Optimization under uncertainty for [Pyomo](https://pyomo.org) models. -`Documentation is available at readthedocs `_ and -there is a `paper `_. +[Documentation is available at readthedocs](https://mpi-sppy.readthedocs.io/en/latest/) and +there is a [paper](https://link.springer.com/article/10.1007/s12532-023-00247-3). Status for internal tests -^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------- [![pyo tracker](https://github.com/Pyomo/mpi-sppy/actions/workflows/pyotracker.yml/badge.svg)](https://github.com/Pyomo/mpi-sppy/actions/workflows/pyotracker.yml) - MPI -^^^ +--- A recent version of MPI and a compatible version of mpi4py are needed. Here are two methods that seem to work well for installation, at least when considering non-HPC platforms. -#. Install OpenMPI and mpi4py using conda. - - * ``conda install openmpi; conda install mpi4py`` (in that order) - -#. If you already have an existing version of MPI, it may be better compile mpi4py against it. This can be done by installing mpi4py though pip. - - * ``pip install mpi4py`` - -#. It is also possible to automate mpi4py installation through pip as an optional dependency when installing mpi-sppy from pip or from source by adding the `[mpi]` extras flag. - - * ``pip install -e .[mpi]`` (after cloning and moving to the repo root directory) - -To test -your installation, cd to the directory where you installed mpi-sppy +1. Install OpenMPI and mpi4py using conda. Keep the order. + ``` + conda install openmpi + conda install mpi4py + ``` +2. If you already have an existing version of MPI, it may be better compile mpi4py against it. + This can be done by installing mpi4py though pip. + ``` + pip install mpi4py + ``` +4. It is also possible to automate mpi4py installation through pip as an optional dependency when + installing mpi-sppy from pip or from source by adding the `[mpi]` extras flag. + ```shell + pip install -e .[mpi] + ``` + Run the line aborve after cloning and moving to the repo root directory. + +To test your installation, cd to the directory where you installed mpi-sppy (it is called ``mpi-sppy``) and then give this command. -``mpirun -n 2 python -m mpi4py mpi_one_sided_test.py`` +``` +mpirun -n 2 python -m mpi4py mpi_one_sided_test.py +``` If you don't see any error messages, you might have an MPI installation that will work well. Note that even if there is @@ -44,30 +49,29 @@ results. Per the comment below, the run-times may just be unnecessarily inflated. Installing mpi-sppy -^^^^^^^^^^^^^^^^^^^ +------------------- It is possible to pip install mpi-sppy; however, most users are better off getting the software from Github because it is under active development. Citing mpi-sppy -^^^^^^^^^^^^^^^ -If you find mpi-sppy useful in your work, we kindly request that you cite the following `paper `_: - -:: - - @article{mpi-sppy, - title={A Parallel Hub-and-Spoke System for Large-Scale Scenario-Based Optimization Under Uncertainty}, - author={Bernard Knueven and David Mildebrath and Christopher Muir and John D Siirola and Jean-Paul Watson and David L Woodruff}, - journal = {Math. Prog. Comp.}, - volume = {15}, - pages = {591-–619}, - year={2023} - } - - +--------------- +If you find mpi-sppy useful in your work, we kindly request that you cite the following +[paper](https://link.springer.com/article/10.1007/s12532-023-00247-3): + +``` + @article{mpi-sppy, + title={A Parallel Hub-and-Spoke System for Large-Scale Scenario-Based Optimization Under Uncertainty}, + author={Bernard Knueven and David Mildebrath and Christopher Muir and John D Siirola and Jean-Paul Watson and David L Woodruff}, + journal = {Math. Prog. Comp.}, + volume = {15}, + pages = {591-–619}, + year={2023} + } +``` AN IMPORTANT NOTE FOR MPICH USERS ON HPC PLATFORMS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------------- At least on some US Department of Energy (e.g., at Lawrence Livermore National Laboratory) compute clusters, users of mpi-sppy that are @@ -76,7 +80,9 @@ order for both (1) proper execution of the one-sided test referenced above and (2) rapid results when running any of the algorithms shipped with mpi-sppy: +``` export MPICH_ASYNC_PROGRESS=1 +``` Without this setting, we have observed run-times increase by a factor of between 2 and 4, due to non-blocking point-to-point calls @@ -87,7 +93,7 @@ ranks (e.g., >> 10), we have observed mpi-sppy stalling once scenario instances are created. 2022 NOTICE -^^^^^^^^^^^ +----------- There was a disruptive change on August 11, 2022 concerning how options are accessed. See the file ``disruptions.txt`` for more From a730ad85479a85d866484f371991e8dde18783bb Mon Sep 17 00:00:00 2001 From: Moritz Schreiber <68053396+mosc9575@users.noreply.github.com> Date: Tue, 2 Dec 2025 22:09:58 +0100 Subject: [PATCH 3/4] Change enumeration --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1d9738d3f..aff7324c5 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Here are two methods that seem to work well for installation, at least when cons ``` pip install mpi4py ``` -4. It is also possible to automate mpi4py installation through pip as an optional dependency when +3. It is also possible to automate mpi4py installation through pip as an optional dependency when installing mpi-sppy from pip or from source by adding the `[mpi]` extras flag. ```shell pip install -e .[mpi] From 95a7510a0c70bc3efc55125968e55388170d2889 Mon Sep 17 00:00:00 2001 From: Moritz Schreiber <68053396+mosc9575@users.noreply.github.com> Date: Tue, 2 Dec 2025 22:25:12 +0100 Subject: [PATCH 4/4] Rename README.rst to README.MD in setup.py --- setup.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 1d923267e..aef44d7c2 100644 --- a/setup.py +++ b/setup.py @@ -21,7 +21,7 @@ packages = find_packages() this_directory = Path(__file__).parent -long_description = (this_directory / "README.rst").read_text() +long_description = (this_directory / "README.md").read_text() # intentionally leaving out mpi4py to help readthedocs setup( @@ -43,6 +43,7 @@ extras_require={ 'doc': [ 'sphinx_rtd_theme', + 'sphinx-copybutton', 'sphinx', ] },