| Name | pympipool JSON |
| Version |
0.9.0
JSON |
| download |
| home_page | None |
| Summary | Scale serial and MPI-parallel python functions over hundreds of compute nodes all from within a jupyter notebook or serial python process. |
| upload_time | 2024-07-14 19:01:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.9 |
| license | BSD 3-Clause License Copyright (c) 2022, Jan Janssen All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
pyiron
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# executorlib
[](https://github.com/pyiron/executorlib/actions/workflows/unittest-openmpi.yml)
[](https://coveralls.io/github/pyiron/executorlib?branch=main)
[](https://mybinder.org/v2/gh/pyiron/executorlib/HEAD?labpath=notebooks%2Fexamples.ipynb)
## Challenges
In high performance computing (HPC) the Python programming language is commonly used as high-level language to
orchestrate the coupling of scientific applications. Still the efficient usage of highly parallel HPC clusters remains
challenging, in primarily three aspects:
* **Communication**: Distributing python function calls over hundreds of compute node and gathering the results on a
shared file system is technically possible, but highly inefficient. A socket-based communication approach is
preferable.
* **Resource Management**: Assigning Python functions to GPUs or executing Python functions on multiple CPUs using the
message passing interface (MPI) requires major modifications to the python workflow.
* **Integration**: Existing workflow libraries implement a secondary the job management on the Python level rather than
leveraging the existing infrastructure provided by the job scheduler of the HPC.
### executorlib is ...
In a given HPC allocation the `executorlib` library addresses these challenges by extending the Executor interface
of the standard Python library to support the resource assignment in the HPC context. Computing resources can either be
assigned on a per function call basis or as a block allocation on a per Executor basis. The `executorlib` library
is built on top of the [flux-framework](https://flux-framework.org) to enable fine-grained resource assignment. In
addition, [Simple Linux Utility for Resource Management (SLURM)](https://slurm.schedmd.com) is supported as alternative
queuing system and for workstation installations `executorlib` can be installed without a job scheduler.
### executorlib is not ...
The executorlib library is not designed to request an allocation from the job scheduler of an HPC. Instead within a given
allocation from the job scheduler the `executorlib` library can be employed to distribute a series of python
function calls over the available computing resources to achieve maximum computing resource utilization.
## Example
The following examples illustrates how `executorlib` can be used to distribute a series of MPI parallel function calls
within a queuing system allocation. `example.py`:
```python
import flux.job
from executorlib import Executor
def calc(i):
from mpi4py import MPI
size = MPI.COMM_WORLD.Get_size()
rank = MPI.COMM_WORLD.Get_rank()
return i, size, rank
with flux.job.FluxExecutor() as flux_exe:
with Executor(max_cores=2, cores_per_worker=2, executor=flux_exe) as exe:
fs = exe.submit(calc, 3)
print(fs.result())
```
This example can be executed using:
```
python example.py
```
Which returns:
```
>>> [(0, 2, 0), (0, 2, 1)], [(1, 2, 0), (1, 2, 1)]
```
The important part in this example is that [mpi4py](https://mpi4py.readthedocs.io) is only used in the `calc()`
function, not in the python script, consequently it is not necessary to call the script with `mpiexec` but instead
a call with the regular python interpreter is sufficient. This highlights how `executorlib` allows the users to
parallelize one function at a time and not having to convert their whole workflow to use [mpi4py](https://mpi4py.readthedocs.io).
The same code can also be executed inside a jupyter notebook directly which enables an interactive development process.
The interface of the standard [concurrent.futures.Executor](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures)
is extended by adding the option `cores_per_worker=2` to assign multiple MPI ranks to each function call. To create two
workers the maximum number of cores can be increased to `max_cores=4`. In this case each worker receives two cores
resulting in a total of four CPU cores being utilized.
After submitting the function `calc()` with the corresponding parameter to the executor `exe.submit(calc, 0)`
a python [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) is
returned. Consequently, the `executorlib.Executor` can be used as a drop-in replacement for the
[`concurrent.futures.Executor`](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures)
which allows the user to add parallelism to their workflow one function at a time.
## Disclaimer
While we try to develop a stable and reliable software library, the development remains a opensource project under the
BSD 3-Clause License without any warranties::
```
BSD 3-Clause License
Copyright (c) 2022, Jan Janssen
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```
# Documentation
* [Installation](https://executorlib.readthedocs.io/en/latest/installation.html)
* [Compatible Job Schedulers](https://executorlib.readthedocs.io/en/latest/installation.html#compatible-job-schedulers)
* [executorlib with Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#executorlib-with-flux-framework)
* [Test Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#test-flux-framework)
* [Without Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#without-flux-framework)
* [Examples](https://executorlib.readthedocs.io/en/latest/examples.html)
* [Compatibility](https://executorlib.readthedocs.io/en/latest/examples.html#compatibility)
* [Resource Assignment](https://executorlib.readthedocs.io/en/latest/examples.html#resource-assignment)
* [Data Handling](https://executorlib.readthedocs.io/en/latest/examples.html#data-handling)
* [Up-Scaling](https://executorlib.readthedocs.io/en/latest/examples.html#up-scaling)
* [Coupled Functions](https://executorlib.readthedocs.io/en/latest/examples.html#coupled-functions)
* [SLURM Job Scheduler](https://executorlib.readthedocs.io/en/latest/examples.html#slurm-job-scheduler)
* [Workstation Support](https://executorlib.readthedocs.io/en/latest/examples.html#workstation-support)
* [Development](https://executorlib.readthedocs.io/en/latest/development.html)
* [Contributions](https://executorlib.readthedocs.io/en/latest/development.html#contributions)
* [License](https://executorlib.readthedocs.io/en/latest/development.html#license)
* [Integration](https://executorlib.readthedocs.io/en/latest/development.html#integration)
Raw data
{
"_id": null,
"home_page": null,
"name": "pympipool",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "pyiron",
"author": null,
"author_email": "Jan Janssen <janssen@lanl.gov>",
"download_url": "https://files.pythonhosted.org/packages/17/07/ecfa3731f5655d3fd45ab82e20ab01022cd4f02f9f5a259cb5c4c6bfea80/pympipool-0.9.0.tar.gz",
"platform": null,
"description": "# executorlib\n[](https://github.com/pyiron/executorlib/actions/workflows/unittest-openmpi.yml)\n[](https://coveralls.io/github/pyiron/executorlib?branch=main)\n[](https://mybinder.org/v2/gh/pyiron/executorlib/HEAD?labpath=notebooks%2Fexamples.ipynb)\n\n## Challenges\nIn high performance computing (HPC) the Python programming language is commonly used as high-level language to\norchestrate the coupling of scientific applications. Still the efficient usage of highly parallel HPC clusters remains\nchallenging, in primarily three aspects:\n\n* **Communication**: Distributing python function calls over hundreds of compute node and gathering the results on a\n shared file system is technically possible, but highly inefficient. A socket-based communication approach is \n preferable.\n* **Resource Management**: Assigning Python functions to GPUs or executing Python functions on multiple CPUs using the \n message passing interface (MPI) requires major modifications to the python workflow.\n* **Integration**: Existing workflow libraries implement a secondary the job management on the Python level rather than\n leveraging the existing infrastructure provided by the job scheduler of the HPC.\n\n### executorlib is ...\nIn a given HPC allocation the `executorlib` library addresses these challenges by extending the Executor interface\nof the standard Python library to support the resource assignment in the HPC context. Computing resources can either be\nassigned on a per function call basis or as a block allocation on a per Executor basis. The `executorlib` library\nis built on top of the [flux-framework](https://flux-framework.org) to enable fine-grained resource assignment. In\naddition, [Simple Linux Utility for Resource Management (SLURM)](https://slurm.schedmd.com) is supported as alternative\nqueuing system and for workstation installations `executorlib` can be installed without a job scheduler.\n\n### executorlib is not ...\nThe executorlib library is not designed to request an allocation from the job scheduler of an HPC. Instead within a given\nallocation from the job scheduler the `executorlib` library can be employed to distribute a series of python\nfunction calls over the available computing resources to achieve maximum computing resource utilization.\n\n## Example\nThe following examples illustrates how `executorlib` can be used to distribute a series of MPI parallel function calls \nwithin a queuing system allocation. `example.py`:\n```python\nimport flux.job\nfrom executorlib import Executor\n\ndef calc(i):\n from mpi4py import MPI\n size = MPI.COMM_WORLD.Get_size()\n rank = MPI.COMM_WORLD.Get_rank()\n return i, size, rank\n\nwith flux.job.FluxExecutor() as flux_exe:\n with Executor(max_cores=2, cores_per_worker=2, executor=flux_exe) as exe:\n fs = exe.submit(calc, 3)\n print(fs.result())\n```\nThis example can be executed using:\n```\npython example.py\n```\nWhich returns:\n```\n>>> [(0, 2, 0), (0, 2, 1)], [(1, 2, 0), (1, 2, 1)]\n```\nThe important part in this example is that [mpi4py](https://mpi4py.readthedocs.io) is only used in the `calc()`\nfunction, not in the python script, consequently it is not necessary to call the script with `mpiexec` but instead\na call with the regular python interpreter is sufficient. This highlights how `executorlib` allows the users to\nparallelize one function at a time and not having to convert their whole workflow to use [mpi4py](https://mpi4py.readthedocs.io).\nThe same code can also be executed inside a jupyter notebook directly which enables an interactive development process.\n\nThe interface of the standard [concurrent.futures.Executor](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures)\nis extended by adding the option `cores_per_worker=2` to assign multiple MPI ranks to each function call. To create two \nworkers the maximum number of cores can be increased to `max_cores=4`. In this case each worker receives two cores\nresulting in a total of four CPU cores being utilized.\n\nAfter submitting the function `calc()` with the corresponding parameter to the executor `exe.submit(calc, 0)`\na python [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) is\nreturned. Consequently, the `executorlib.Executor` can be used as a drop-in replacement for the\n[`concurrent.futures.Executor`](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures)\nwhich allows the user to add parallelism to their workflow one function at a time.\n\n## Disclaimer\nWhile we try to develop a stable and reliable software library, the development remains a opensource project under the\nBSD 3-Clause License without any warranties::\n```\nBSD 3-Clause License\n\nCopyright (c) 2022, Jan Janssen\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n\n* Neither the name of the copyright holder nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n```\n\n# Documentation\n* [Installation](https://executorlib.readthedocs.io/en/latest/installation.html)\n * [Compatible Job Schedulers](https://executorlib.readthedocs.io/en/latest/installation.html#compatible-job-schedulers)\n * [executorlib with Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#executorlib-with-flux-framework)\n * [Test Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#test-flux-framework)\n * [Without Flux Framework](https://executorlib.readthedocs.io/en/latest/installation.html#without-flux-framework)\n* [Examples](https://executorlib.readthedocs.io/en/latest/examples.html)\n * [Compatibility](https://executorlib.readthedocs.io/en/latest/examples.html#compatibility)\n * [Resource Assignment](https://executorlib.readthedocs.io/en/latest/examples.html#resource-assignment)\n * [Data Handling](https://executorlib.readthedocs.io/en/latest/examples.html#data-handling)\n * [Up-Scaling](https://executorlib.readthedocs.io/en/latest/examples.html#up-scaling)\n * [Coupled Functions](https://executorlib.readthedocs.io/en/latest/examples.html#coupled-functions)\n * [SLURM Job Scheduler](https://executorlib.readthedocs.io/en/latest/examples.html#slurm-job-scheduler) \n * [Workstation Support](https://executorlib.readthedocs.io/en/latest/examples.html#workstation-support)\n* [Development](https://executorlib.readthedocs.io/en/latest/development.html)\n * [Contributions](https://executorlib.readthedocs.io/en/latest/development.html#contributions)\n * [License](https://executorlib.readthedocs.io/en/latest/development.html#license)\n * [Integration](https://executorlib.readthedocs.io/en/latest/development.html#integration)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2022, Jan Janssen All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Scale serial and MPI-parallel python functions over hundreds of compute nodes all from within a jupyter notebook or serial python process.",
"version": "0.9.0",
"project_urls": {
"Documentation": "https://executorlib.readthedocs.io",
"Homepage": "https://github.com/pyiron/executorlib",
"Repository": "https://github.com/pyiron/executorlib"
},
"split_keywords": [
"pyiron"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31e051954e71a1d840a8a538eff41957965cb4e982bcf21fe2e14e0f82ea2372",
"md5": "8fe144d8992c9b1dc699ecd7999301c9",
"sha256": "e0068a086fb6a484f2aa6aa821fc3392e4b9e8ac22149fa4bd507fe664adcc78"
},
"downloads": -1,
"filename": "pympipool-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fe144d8992c9b1dc699ecd7999301c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 44953,
"upload_time": "2024-07-14T19:01:19",
"upload_time_iso_8601": "2024-07-14T19:01:19.556766Z",
"url": "https://files.pythonhosted.org/packages/31/e0/51954e71a1d840a8a538eff41957965cb4e982bcf21fe2e14e0f82ea2372/pympipool-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1707ecfa3731f5655d3fd45ab82e20ab01022cd4f02f9f5a259cb5c4c6bfea80",
"md5": "9747cf83d23beda9bed7989ac583a7f1",
"sha256": "c1e84591b6fadd2cd9ce47b0c8c1fe6867e4b1187d71193958801186dbdaef5a"
},
"downloads": -1,
"filename": "pympipool-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "9747cf83d23beda9bed7989ac583a7f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 42736,
"upload_time": "2024-07-14T19:01:21",
"upload_time_iso_8601": "2024-07-14T19:01:21.633089Z",
"url": "https://files.pythonhosted.org/packages/17/07/ecfa3731f5655d3fd45ab82e20ab01022cd4f02f9f5a259cb5c4c6bfea80/pympipool-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-14 19:01:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyiron",
"github_project": "executorlib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pympipool"
}
