02 - Run with repeats¶

Get a tight mean and coefficient-of-variation across multiple runs of the same command. Demonstrates the --repeat / --warmup knobs and the outlier-removed statistics that ship with codegreen run.

What you learn¶

How --warmup discards the first N runs (filesystem cache, JIT, etc.).
How --repeat builds a sample for mean / std / 95% CI.
How to read energy_j.mean, energy_j.std, energy_j.ci95, and the outlier-removed counts.

Prerequisites¶

pip install codegreen
Linux RAPL or macOS IOReport.

Source¶

examples/02_run_repeat/main.py

"""02 Stable mean via repetitions.

Demonstrates `codegreen run --repeat 5 --warmup 1` and the CV (coefficient
of variation across runs) reported by CodeGreen. Smaller CV -> tighter
estimate. Useful when comparing two variants of the same workload.
"""
import json
import subprocess
import sys


def main() -> int:
    cmd = ["codegreen", "run", "--repeat", "5", "--warmup", "1", "--json", "--",
           "python3", "-c", "x=0\nfor i in range(2_000_000): x+=i\nprint(x)"]
    out = subprocess.run(cmd, capture_output=True, text=True, check=True)
    data = json.loads(out.stdout)
    e = data["energy_j"]
    print(f"OK: run_repeat; mean_energy_j={e['mean']:.4f}; cv_pct={e['cv_percent_across_runs']:.2f}; n={data['runs']['measurement_runs']}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Run¶

python examples/02_run_repeat/main.py

Expected output¶

OK: run_repeat; mean_energy_j=0.8123; cv_pct=2.40; n=5

Why it matters¶

The killer feature of CodeGreen's CLI mode is stable means without manual scripting. Hyperfine pioneered this for wall time; codegreen run extends it to RAPL energy. A CV under 5% on a sub-second workload tells you the measurement is repeatable. CV above 20% is a signal that the workload is too short, the host is contended, or another CodeGreen session is overlapping.