Metadata-Version: 2.4
Name: perun
Version: 0.9.1
Summary: Measure the energy used by your MPI+Python applications.
Project-URL: Homepage, https://github.com/Helmholtz-AI-Energy/perun
Project-URL: Documentation, https://perun.readthedocs.io
Project-URL: Repository, https://github.com/Helmholtz-AI-Energy/perun
Project-URL: Issues, https://github.com/Helmholtz-AI-Energy/perun/issues
Project-URL: Changelog, https://github.com/Helmholtz-AI-Energy/perun/blob/main/CHANGELOG.md
Author-email: "Gutiérrez Hermosillo Muriedas, Juan Pedro" <juan.muriedas@kit.edu>
Maintainer-email: "Gutiérrez Hermosillo Muriedas, Juan Pedro" <juan.muriedas@kit.edu>
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.
License-File: LICENSE
Keywords: benchmarking,command-line,energy,hpc,monitoring,mpi,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Benchmark
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: h5py>=3.5.9
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3
Requires-Dist: psutil>=5.9.0
Requires-Dist: py-cpuinfo>=5.0.0
Requires-Dist: tabulate>=0.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: hypothesis~=6.100; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: python-semantic-release>=8.1.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autoapi; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Provides-Extra: mpi
Requires-Dist: mpi4py>=3.1; extra == 'mpi'
Provides-Extra: nvidia
Requires-Dist: nvidia-ml-py>=12.535.77; extra == 'nvidia'
Provides-Extra: rocm
Requires-Dist: amdsmi>=6.2.0; extra == 'rocm'
Description-Content-Type: text/x-rst

.. image:: https://raw.githubusercontent.com/Helmholtz-AI-Energy/perun/main/docs/images/full_logo.svg

| |fair-software| |openssf| |zenodo| |license| |docs|
| |pypi-version| |python-version| |pypi-downloads| |black| |codecov|

.. |fair-software| image:: https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green
   :target: https://fair-software.eu
.. |openssf| image:: https://bestpractices.coreinfrastructure.org/projects/7253/badge
   :target: https://bestpractices.coreinfrastructure.org/projects/7253
.. |zenodo| image:: https://zenodo.org/badge/523363424.svg
   :target: https://zenodo.org/badge/latestdoi/523363424
.. |pypi-version| image:: https://img.shields.io/pypi/v/perun
.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/perun
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
.. |codecov| image:: https://codecov.io/gh/Helmholtz-AI-Energy/perun/graph/badge.svg?token=9O6FSJ6I3G
   :target: https://codecov.io/gh/Helmholtz-AI-Energy/perun
.. |python-version| image:: https://img.shields.io/badge/Python-3.9+-blue.svg
   :target: https://www.python.org/downloads/
.. |license| image:: https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
   :target: https://opensource.org/licenses/BSD-3-Clause
.. |docs| image:: https://readthedocs.org/projects/perun/badge/?version=latest
   :target: 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 and binaries, supporting different hardware configurations
- Capable of handling MPI applications, 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

-----------------------------------------------------------------


Quick Start
-----------

Installation
^^^^^^^^^^^^

From PyPI:

.. code:: console

    $ pip install perun

Extra dependencies like *nvidia-smi*, *rocm-smi* and *mpi4py* can be installed using pip as well:

.. code:: console

    $ pip install perun[nvidia, rocm, mpi]

From Github:

.. code:: console

    $ pip install git+https://github.com/Helmholtz-AI-Energy/perun

Command Line
^^^^^^^^^^^^

To use *perun* as a command-line tool:

.. code:: console

    $ perun monitor path/to/your/script.py [args]

*perun* will output two files, an HDF5 style containing all the raw data that was gathered, and a text file with a summary of the results.

.. code:: 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. In total, 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.


Binary support (experimental)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*perun* is capable of monitoring simple applications written in other languages:

.. code:: console

    $ perun monitor --binary path/to/your/executable [args]

Function Monitoring
^^^^^^^^^^^^^^^^^^^

Using a function decorator

.. code:: python

    import time
    from perun import monitor

    @monitor()
    def main(n: int):
        time.sleep(n)

After running with ``perun monitor``, the report will contain:

.. code:: 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 using ``mpi4py``:

.. code:: console

    $ mpirun -n 8 perun monitor path/to/your/script.py

Docs
----

See the `documentation <https://perun.readthedocs.io/en/latest/>`_ or `examples <https://github.com/Helmholtz-AI-Energy/perun/tree/main/examples>`_ for more details.

Citing perun
------------

If you found *perun* useful, please cite 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

.. code-block:: 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",
     isbn="978-3-031-39698-4"
   }
