matcha-gpu 0.2.1

GPU energy metering for AI training workloads

⚡ matcha

GPU energy metering for AI training workloads. Pure Python. No dashboards.

Polls GPU power at 100ms via NVML and reports energy consumption per training step.

Built by Keeya Labs.

Install

pip install matcha-gpu

Requires an NVIDIA GPU with drivers installed (nvidia-smi must work).

Quick Start

Option A: Wrap any training script (zero code changes)

matcha wrap python train_gpt.py

Matcha parses your script's stdout for step markers (step 10, iter 10, [10/1000], etc.) and reports energy between each step.

# also print the training script's output
matcha wrap -p python train_gpt.py

# custom gpu and sampling interval
matcha wrap --gpu 1 --interval 50 python train_gpt.py

Option B: SDK (3 lines added to your training loop)

import matcha

m = matcha.init()

for step in range(num_steps):
    m.step_start()

    # ... your training code, unchanged ...

    energy = m.step_end(step)
    # energy.energy_j   — joules
    # energy.avg_power_w — average watts during step
    # energy.peak_power_w

summary = m.finish()
# summary.total_energy_j
# summary.energy_kwh
# summary.j_per_step

Monitor GPU power (no training script)

matcha monitor
matcha monitor --gpu 0 --window 2.0

Output

  ⚡ matcha — gpu energy metering
  ────────────────────────────────────────────────────────
  gpu        NVIDIA H100 80GB HBM3
  tdp        700W
  sampling   every 100ms
  ────────────────────────────────────────────────────────

    step      energy      time    avg W   peak W  power
  ────────────────────────────────────────────────────────
       0     12.45 J    0.198s   62.8W    71.2W  ██████░░░░░░
       1     13.01 J    0.201s   64.7W    73.1W  ██████░░░░░░
       2     12.88 J    0.199s   64.7W    72.4W  ██████░░░░░░

  ────────────────────────────────────────────────────────
  ⚡ session summary
  ────────────────────────────────────────────────────────

  gpu            NVIDIA H100 80GB HBM3
  total energy   623.45 J
  total time     10.02s
  steps          50
  energy/step    12.47 J
  avg power      62.2W
  peak power     73.1W

  est. cost      $0.000021 @ $0.12/kWh

License

Apache 2.0 — see LICENSE.