Quick Start

Installation

From PyPI:

$ pip install perun

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

$ pip install perun[nvidia, rocm, mpi]

From Github:

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

Command Line

To use perun as a command-line tool:

$ 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.

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:

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

Function Monitoring

Using a function decorator

import time
from perun import monitor

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

After running with perun monitor, the report will contain:

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:

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