| Name | perun JSON |
| Version |
0.8.7
JSON |
| download |
| home_page | None |
| Summary | Measure the energy used by your MPI+Python applications. |
| upload_time | 2024-08-16 14:28:45 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | BSD 3-Clause License Copyright (c) 2022, Helmholtz AI Energy All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. 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. 3. 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 |
benchmarking
command-line
energy
hpc
monitoring
mpi
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://raw.githubusercontent.com/Helmholtz-AI-Energy/perun/main/docs/images/full_logo.svg">
</div>
[](https://fair-software.eu)
[](https://bestpractices.coreinfrastructure.org/projects/7253)
[](https://zenodo.org/badge/latestdoi/523363424)
[](https://github.com/psf/black)
[](https://codecov.io/gh/Helmholtz-AI-Energy/perun)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://perun.readthedocs.io/en/latest/?badge=latest)
perun is a Python package that calculates the energy consumption of Python scripts by sampling usage statistics from your Intel, Nvidia or AMD hardware components. It can handle MPI applications, gather data from hundreds of nodes, and accumulate it efficiently. perun can be used as a command-line tool or as a function decorator in Python scripts.
Check out the [docs](https://perun.readthedocs.io/en/latest/) or a working [example](https://github.com/Helmholtz-AI-Energy/perun/blob/main/examples/torch_mnist/README.md)!
## Key Features
- Measures energy consumption of Python scripts using Intel RAPL, ROCM-SMI, Nvidia-NVML, and psutil
- Capable of handling MPI application, gathering data from hundreds of nodes efficiently
- Monitor individual functions using decorators
- Tracks energy usage of the application over multiple executions
- Easy to benchmark applications and functions
- Experimental!: Can monitor any non-distributed command line application
## Installation
From PyPI:
```console
pip install perun
```
> Extra dependencies like nvidia-smi, rocm-smi and mpi can be installed through pip as well:
```console
pip install perun[nvidia, rocm, mpi]
```
From Github:
```console
pip install git+https://github.com/Helmholtz-AI-Energy/perun
```
## Quick Start
### Command Line
To use perun as a command-line tool, run the monitor subcommand followed by the path to your Python script and its arguments:
```console
$ perun monitor path/to/your/script.py [args]
```
perun will output two files, and HDF5 style containing all the raw data that was gathered, and a text file with a summary of the results.
```text
PERUN REPORT
App name: finetune_qa_accelerate
First run: 2023-08-15T18:56:11.202060
Last run: 2023-08-17T13:29:29.969779
RUN ID: 2023-08-17T13:29:29.969779
| Round # | Host | RUNTIME | ENERGY | CPU_POWER | CPU_UTIL | GPU_POWER | GPU_MEM | DRAM_POWER | MEM_UTIL |
|----------:|:--------------------|:----------|:-----------|:------------|:-----------|:------------|:-----------|:-------------|:-----------|
| 0 | hkn0432.localdomain | 995.967 s | 960.506 kJ | 231.819 W | 3.240 % | 702.327 W | 55.258 GB | 29.315 W | 0.062 % |
| 0 | hkn0436.localdomain | 994.847 s | 960.469 kJ | 235.162 W | 3.239 % | 701.588 W | 56.934 GB | 27.830 W | 0.061 % |
| 0 | All | 995.967 s | 1.921 MJ | 466.981 W | 3.240 % | 1.404 kW | 112.192 GB | 57.145 W | 0.061 % |
The application has been run 7 times. Throught its runtime, it has used 3.128 kWh, released a total of 1.307 kgCO2e into the atmosphere, and you paid 1.02 € in electricity for it.
```
Perun will keep track of the energy of your application over multiple runs.
#### Binary support (experimental)
perun is capable of monitoring simple applications written in other languages, as long as they don't make use of MPI or are distributed over multiple computational nodes.
```console
$ perun monitor --binary path/to/your/executable [args]
```
### Function Monitoring
Using a function decorator, information can be calculated about the runtime, power draw and component utilization while the function is executing.
```python
import time
from perun import monitor
@monitor()
def main(n: int):
time.sleep(n)
```
After running the script with ```perun monitor```, the text report will add information about the monitored functions.
```text
Monitored Functions
| Round # | Function | Avg Calls / Rank | Avg Runtime | Avg Power | Avg CPU Util | Avg GPU Mem Util |
|----------:|:----------------------------|-------------------:|:----------------|:-----------------|:---------------|:-------------------|
| 0 | main | 1 | 993.323±0.587 s | 964.732±0.499 W | 3.244±0.003 % | 35.091±0.526 % |
| 0 | prepare_train_features | 88 | 0.383±0.048 s | 262.305±19.251 W | 4.541±0.320 % | 3.937±0.013 % |
| 0 | prepare_validation_features | 11 | 0.372±0.079 s | 272.161±19.404 W | 4.524±0.225 % | 4.490±0.907 % |
```
### MPI
Perun is compatible with MPI applications that make use of ```mpi4py```, and requires changes in the code or in the perun configuration. Simply replace the ```python``` command with ```perun monitor```.
```console
mpirun -n 8 perun monitor path/to/your/script.py
```
## Docs
To get more information, check out our [docs page](https://perun.readthedocs.io/en/latest/) or check the [examples](https://github.com/Helmholtz-AI-Energy/perun/tree/main/examples).
## Citing perun
If you found perun usefull, please consider citing the conference paper:
* Gutiérrez Hermosillo Muriedas, J.P., Flügel, K., Debus, C., Obermaier, H., Streit, A., Götz, M.: perun: Benchmarking Energy Consumption of High-Performance Computing Applications. In: Cano, J., Dikaiakos, M.D., Papadopoulos, G.A., Pericàs, M., and Sakellariou, R. (eds.) Euro-Par 2023: Parallel Processing. pp. 17–31. Springer Nature Switzerland, Cham (2023). https://doi.org/10.1007/978-3-031-39698-4_2.
```bibtex
@InProceedings{10.1007/978-3-031-39698-4_2,
author="Guti{\'e}rrez Hermosillo Muriedas, Juan Pedro
and Fl{\"u}gel, Katharina
and Debus, Charlotte
and Obermaier, Holger
and Streit, Achim
and G{\"o}tz, Markus",
editor="Cano, Jos{\'e}
and Dikaiakos, Marios D.
and Papadopoulos, George A.
and Peric{\`a}s, Miquel
and Sakellariou, Rizos",
title="perun: Benchmarking Energy Consumption of High-Performance Computing Applications",
booktitle="Euro-Par 2023: Parallel Processing",
year="2023",
publisher="Springer Nature Switzerland",
address="Cham",
pages="17--31",
abstract="Looking closely at the Top500 list of high-performance computers (HPC) in the world, it becomes clear that computing power is not the only number that has been growing in the last three decades. The amount of power required to operate such massive computing machines has been steadily increasing, earning HPC users a higher than usual carbon footprint. While the problem is well known in academia, the exact energy requirements of hardware, software and how to optimize it are hard to quantify. To tackle this issue, we need tools to understand the software and its relationship with power consumption in today's high performance computers. With that in mind, we present perun, a Python package and command line interface to measure energy consumption based on hardware performance counters and selected physical measurement sensors. This enables accurate energy measurements on various scales of computing, from a single laptop to an MPI-distributed HPC application. We include an analysis of the discrepancies between these sensor readings and hardware performance counters, with particular focus on the power draw of the usually overlooked non-compute components such as memory. One of our major insights is their significant share of the total energy consumption. We have equally analyzed the runtime and energy overhead perun generates when monitoring common HPC applications, and found it to be minimal. Finally, an analysis on the accuracy of different measuring methodologies when applied at large scales is presented.",
isbn="978-3-031-39698-4"
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "perun",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Guti\u00e9rrez Hermosillo Muriedas, Juan Pedro\" <juan.muriedas@kit.edu>",
"keywords": "benchmarking, command-line, energy, hpc, monitoring, mpi, python",
"author": null,
"author_email": "\"Guti\u00e9rrez Hermosillo Muriedas, Juan Pedro\" <juan.muriedas@kit.edu>",
"download_url": "https://files.pythonhosted.org/packages/bc/14/2d0273a9b495d7af027518175042fd9ce8c85a86a7cab37a4a749734904f/perun-0.8.7.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/Helmholtz-AI-Energy/perun/main/docs/images/full_logo.svg\">\n</div>\n\n \n \n\n[](https://fair-software.eu)\n[](https://bestpractices.coreinfrastructure.org/projects/7253)\n[](https://zenodo.org/badge/latestdoi/523363424)\n\n\n[](https://github.com/psf/black)\n[](https://codecov.io/gh/Helmholtz-AI-Energy/perun)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://perun.readthedocs.io/en/latest/?badge=latest)\n\nperun is a Python package that calculates the energy consumption of Python scripts by sampling usage statistics from your Intel, Nvidia or AMD hardware components. It can handle MPI applications, gather data from hundreds of nodes, and accumulate it efficiently. perun can be used as a command-line tool or as a function decorator in Python scripts.\n\nCheck out the [docs](https://perun.readthedocs.io/en/latest/) or a working [example](https://github.com/Helmholtz-AI-Energy/perun/blob/main/examples/torch_mnist/README.md)!\n\n## Key Features\n\n - Measures energy consumption of Python scripts using Intel RAPL, ROCM-SMI, Nvidia-NVML, and psutil\n - Capable of handling MPI application, gathering data from hundreds of nodes efficiently\n - Monitor individual functions using decorators\n - Tracks energy usage of the application over multiple executions\n - Easy to benchmark applications and functions\n - Experimental!: Can monitor any non-distributed command line application\n\n## Installation\n\nFrom PyPI:\n\n```console\npip install perun\n```\n\n> Extra dependencies like nvidia-smi, rocm-smi and mpi can be installed through pip as well:\n```console\npip install perun[nvidia, rocm, mpi]\n```\n\nFrom Github:\n\n```console\npip install git+https://github.com/Helmholtz-AI-Energy/perun\n```\n\n## Quick Start\n\n### Command Line\n\nTo use perun as a command-line tool, run the monitor subcommand followed by the path to your Python script and its arguments:\n\n```console\n$ perun monitor path/to/your/script.py [args]\n```\n\nperun will output two files, and HDF5 style containing all the raw data that was gathered, and a text file with a summary of the results.\n\n\n```text\nPERUN REPORT\n\nApp name: finetune_qa_accelerate\nFirst run: 2023-08-15T18:56:11.202060\nLast run: 2023-08-17T13:29:29.969779\n\n\nRUN ID: 2023-08-17T13:29:29.969779\n\n| Round # | Host | RUNTIME | ENERGY | CPU_POWER | CPU_UTIL | GPU_POWER | GPU_MEM | DRAM_POWER | MEM_UTIL |\n|----------:|:--------------------|:----------|:-----------|:------------|:-----------|:------------|:-----------|:-------------|:-----------|\n| 0 | hkn0432.localdomain | 995.967 s | 960.506 kJ | 231.819 W | 3.240 % | 702.327 W | 55.258 GB | 29.315 W | 0.062 % |\n| 0 | hkn0436.localdomain | 994.847 s | 960.469 kJ | 235.162 W | 3.239 % | 701.588 W | 56.934 GB | 27.830 W | 0.061 % |\n| 0 | All | 995.967 s | 1.921 MJ | 466.981 W | 3.240 % | 1.404 kW | 112.192 GB | 57.145 W | 0.061 % |\n\nThe application has been run 7 times. Throught its runtime, it has used 3.128 kWh, released a total of 1.307 kgCO2e into the atmosphere, and you paid 1.02 \u20ac in electricity for it.\n```\n\nPerun will keep track of the energy of your application over multiple runs.\n\n#### Binary support (experimental)\n\nperun is capable of monitoring simple applications written in other languages, as long as they don't make use of MPI or are distributed over multiple computational nodes.\n\n```console\n$ perun monitor --binary path/to/your/executable [args]\n```\n\n### Function Monitoring\n\nUsing a function decorator, information can be calculated about the runtime, power draw and component utilization while the function is executing.\n\n```python\n\nimport time\nfrom perun import monitor\n\n@monitor()\ndef main(n: int):\n time.sleep(n)\n```\n\nAfter running the script with ```perun monitor```, the text report will add information about the monitored functions.\n\n```text\nMonitored Functions\n\n| Round # | Function | Avg Calls / Rank | Avg Runtime | Avg Power | Avg CPU Util | Avg GPU Mem Util |\n|----------:|:----------------------------|-------------------:|:----------------|:-----------------|:---------------|:-------------------|\n| 0 | main | 1 | 993.323\u00b10.587 s | 964.732\u00b10.499 W | 3.244\u00b10.003 % | 35.091\u00b10.526 % |\n| 0 | prepare_train_features | 88 | 0.383\u00b10.048 s | 262.305\u00b119.251 W | 4.541\u00b10.320 % | 3.937\u00b10.013 % |\n| 0 | prepare_validation_features | 11 | 0.372\u00b10.079 s | 272.161\u00b119.404 W | 4.524\u00b10.225 % | 4.490\u00b10.907 % |\n```\n\n### MPI\n\nPerun is compatible with MPI applications that make use of ```mpi4py```, and requires changes in the code or in the perun configuration. Simply replace the ```python``` command with ```perun monitor```.\n\n```console\nmpirun -n 8 perun monitor path/to/your/script.py\n```\n\n## Docs\n\nTo get more information, check out our [docs page](https://perun.readthedocs.io/en/latest/) or check the [examples](https://github.com/Helmholtz-AI-Energy/perun/tree/main/examples).\n\n## Citing perun\n\nIf you found perun usefull, please consider citing the conference paper:\n\n * Guti\u00e9rrez Hermosillo Muriedas, J.P., Fl\u00fcgel, K., Debus, C., Obermaier, H., Streit, A., G\u00f6tz, M.: perun: Benchmarking Energy Consumption of\u00a0High-Performance Computing Applications. In: Cano, J., Dikaiakos, M.D., Papadopoulos, G.A., Peric\u00e0s, M., and Sakellariou, R. (eds.) Euro-Par 2023: Parallel Processing. pp. 17\u201331. Springer Nature Switzerland, Cham (2023). https://doi.org/10.1007/978-3-031-39698-4_2.\n\n\n```bibtex\n@InProceedings{10.1007/978-3-031-39698-4_2,\n author=\"Guti{\\'e}rrez Hermosillo Muriedas, Juan Pedro\n and Fl{\\\"u}gel, Katharina\n and Debus, Charlotte\n and Obermaier, Holger\n and Streit, Achim\n and G{\\\"o}tz, Markus\",\n editor=\"Cano, Jos{\\'e}\n and Dikaiakos, Marios D.\n and Papadopoulos, George A.\n and Peric{\\`a}s, Miquel\n and Sakellariou, Rizos\",\n title=\"perun: Benchmarking Energy Consumption of\u00a0High-Performance Computing Applications\",\n booktitle=\"Euro-Par 2023: Parallel Processing\",\n year=\"2023\",\n publisher=\"Springer Nature Switzerland\",\n address=\"Cham\",\n pages=\"17--31\",\n abstract=\"Looking closely at the Top500 list of high-performance computers (HPC) in the world, it becomes clear that computing power is not the only number that has been growing in the last three decades. The amount of power required to operate such massive computing machines has been steadily increasing, earning HPC users a higher than usual carbon footprint. While the problem is well known in academia, the exact energy requirements of hardware, software and how to optimize it are hard to quantify. To tackle this issue, we need tools to understand the software and its relationship with power consumption in today's high performance computers. With that in mind, we present perun, a Python package and command line interface to measure energy consumption based on hardware performance counters and selected physical measurement sensors. This enables accurate energy measurements on various scales of computing, from a single laptop to an MPI-distributed HPC application. We include an analysis of the discrepancies between these sensor readings and hardware performance counters, with particular focus on the power draw of the usually overlooked non-compute components such as memory. One of our major insights is their significant share of the total energy consumption. We have equally analyzed the runtime and energy overhead perun\u00a0generates when monitoring common HPC applications, and found it to be minimal. Finally, an analysis on the accuracy of different measuring methodologies when applied at large scales is presented.\",\n isbn=\"978-3-031-39698-4\"\n}\n```\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2022, Helmholtz AI Energy All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. 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. 3. 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": "Measure the energy used by your MPI+Python applications.",
"version": "0.8.7",
"project_urls": {
"Changelog": "https://github.com/Helmholtz-AI-Energy/perun/blob/main/CHANGELOG.md",
"Documentation": "https://perun.readthedocs.io",
"Homepage": "https://github.com/Helmholtz-AI-Energy/perun",
"Issues": "https://github.com/Helmholtz-AI-Energy/perun/issues",
"Repository": "https://github.com/Helmholtz-AI-Energy/perun"
},
"split_keywords": [
"benchmarking",
" command-line",
" energy",
" hpc",
" monitoring",
" mpi",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "712c1b593fcffc602d5961d088b67e14fa27addbb65a419229c9bd1fb9012b48",
"md5": "7a744a0149f32b510e9bdc3e8044479b",
"sha256": "f3d67a061ff098e2576c8a921964d791b795a59d267b7f2683ba96cfab833f8e"
},
"downloads": -1,
"filename": "perun-0.8.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a744a0149f32b510e9bdc3e8044479b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 60134,
"upload_time": "2024-08-16T14:28:43",
"upload_time_iso_8601": "2024-08-16T14:28:43.636607Z",
"url": "https://files.pythonhosted.org/packages/71/2c/1b593fcffc602d5961d088b67e14fa27addbb65a419229c9bd1fb9012b48/perun-0.8.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bc142d0273a9b495d7af027518175042fd9ce8c85a86a7cab37a4a749734904f",
"md5": "dba03c2aad5d0d25f4cd1f95a4d043ac",
"sha256": "a003df57a926dcfa58c6304c76c38c13673b3d31da13eff7805771f7280d4ca7"
},
"downloads": -1,
"filename": "perun-0.8.7.tar.gz",
"has_sig": false,
"md5_digest": "dba03c2aad5d0d25f4cd1f95a4d043ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 191884,
"upload_time": "2024-08-16T14:28:45",
"upload_time_iso_8601": "2024-08-16T14:28:45.175136Z",
"url": "https://files.pythonhosted.org/packages/bc/14/2d0273a9b495d7af027518175042fd9ce8c85a86a7cab37a4a749734904f/perun-0.8.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 14:28:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Helmholtz-AI-Energy",
"github_project": "perun",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "perun"
}
