CodeGreen - Garage for Energy Measurement and Optimization

CodeGreen is a comprehensive tool for fine-grained energy profiling and optimization of code. It provides real-time energy measurement during code execution, identifies energy hotspots, and offers optimization suggestions to reduce energy consumption.

Installation

From PyPI (recommended for users)

pip install codegreen

Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.

Optional telemetry exporters for codegreen monitor: pip install "codegreen[otlp]" (OpenTelemetry/OTLP) or pip install "codegreen[prometheus]".

From source (recommended for development)

git clone https://github.com/SMART-Dal/codegreen.git
cd codegreen
./install.sh

# Linux: RAPL sensor access (one-time, requires sudo):
sudo ./install.sh   # or: sudo codegreen init-sensors

# macOS: no setup needed, energy measurement works out of the box

Platform support

Requirements

• Python 3.9+
• Linux: kernel 5.0+, Intel/AMD CPU with RAPL support
• macOS: Apple Silicon (M1-M5) or Intel, no setup needed
• Windows 11: Intel/AMD CPU (EMI via inbox intelpep.sys driver, zero install)
• Source builds: CMake 3.16+, C++17 compiler

Usage

Measure energy of any command

codegreen run -- python script.py
codegreen run --repeat 20 --warmup 3 -- ./my_binary arg1 arg2
codegreen run --budget 10.0 --json -- python train.py   # CI/CD gate

Per-function energy profiling

# Coarse mode: total program energy
codegreen measure python script.py

# Fine mode: per-function energy breakdown
codegreen measure python script.py -g fine --json

# With energy timeline plot
codegreen measure python script.py -g fine --export-plot energy.html

Project profiling, monitoring and timelines

# Per-function hotspots for a whole project (build once, run, attribute)
codegreen project python ./src -r "python main.py" -s "**/*.py"

# GPU work attributed to the launching function (torch/CUDA)
codegreen project python ./src -r "python train.py" --sync-device cuda

# Continuous host or per-PID sampling, optional OTLP / Prometheus export
codegreen monitor -d 30 -o energy.jsonl
codegreen monitor --pid 1234 --exporter prometheus --prometheus-port 9464

# Power, stacks, GC and GPU kernels on one axis for ui.perfetto.dev
codegreen timeline --nemb nemb.json --jfr run.json --out trace.json

Manual measurement from Python (Session API)

For span-based measurement of arbitrary code regions, import codegreen.Session directly — no CLI, no AST instrumentation:

import codegreen

with codegreen.Session("training-run") as s:
    with s.task("data_load"):
        load_data()
    with s.task("train"):
        model.fit(...)
    with s.task("eval"):
        score = model.evaluate(...)
# writes codegreen_<pid>.json with per-task energy + per-domain breakdown

Time-series sampling for power-vs-time plots (area under curve = energy):

with codegreen.Session("infer", record_time_series=True) as s:
    with s.task("batch1"):
        run_inference()
    s.export_plot("infer.html")   # interactive Plotly chart

The Session API uses the same NEMB backend as the CLI (RAPL/NVML/IOReport), supports nested + concurrent tasks, and degrades gracefully if the native library is unavailable. See API → Python for the full reference.

Static analysis (no execution)

codegreen analyze python script.py --save-instrumented

Benchmark validation (against perf RAPL ground truth)

codegreen benchmark -p nbody -p spectralnorm -l python -r 5 --profiler codegreen --profiler perf

Output formats

JSON (default for --json), CSV, Markdown table, and text summary. The JSON output is a comprehensive single source of truth containing system state, per-function energy, instrumentation points with AST-stable identifiers, and statistical analysis.

Language support

Adding a new language requires only a JSON config file in codegreen/instrumentation/configs/ plus the tree-sitter grammar. No Python code changes needed.

Currently supported: Python, C, C++, Java, JavaScript. Functions that cannot be framed safely (async, generators, coroutines, C++ constexpr) are reported as skipped_functions rather than instrumented.

Benchmarking

# Compare CodeGreen accuracy against perf RAPL ground truth
codegreen benchmark --suite benchmarksgame -l python --reps 5

# Run PerfOpt Java benchmark suite (JMH, original vs patched comparison)
codegreen benchmark --suite perfopt --dataset-dir /path/to/PerfOpt --jars-dir /path/to/jars

# Generate comparison artifacts for documentation
bash scripts/generate_comparison_artifacts.sh docs/benchmarks/

Energy Flow Graph (EFG)

CodeGreen includes an Energy Flow Graph module (codegreen/analysis/efg/) that builds energy-annotated control flow graphs from source code:

from codegreen.analysis.cfg.builder import build_per_method_cfgs
from codegreen.analysis.efg import build_efg, efg_to_dot, efg_to_text

cfgs = build_per_method_cfgs(java_source_code)
efg = build_efg(cfg_nodes, cfg_edges, "ClassName.method", "File.java", codegreen_data)
print(efg_to_text(efg))  # compact format for LLM prompts

Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-level accuracy annotations (MEASURED/ESTIMATED/INFERRED), configurable via EFGConfig.

See codegreen/analysis/efg/README.md for the module layout, a runnable example (python -m codegreen.analysis.efg.example.demo), and the current list of known issues. codegreen.analysis.cfg.energy_flow still resolves as a back-compat shim.

Architecture

• C++ NEMB backend: platform-aware energy measurement (RAPL on Linux, IOReport on macOS, EMI on Windows), sub-microsecond timestamping, background polling with lock-free ring buffers
• Python instrumentation: tree-sitter AST analysis, config-driven checkpoint insertion
• Energy Flow Graph: CFG + energy annotation for path-dependent analysis
• Benchmark harness: multi-suite support (benchmarksgame, PerfOpt), statistical analysis with t-distribution CI, IQR outlier detection, profiler comparison

CI/CD integration

# Fail pipeline if energy exceeds budget
codegreen run --budget 10.0 --json -- python tests/benchmark.py
# Exit code 1 if mean energy > 10 Joules, 3 if the measurement is invalid (see validity.reasons)

Upgrading

pip install --upgrade codegreen   # PyPI
# or
cd codegreen && git pull && ./install.sh --upgrade   # source

Citation

@article{rajput2026codegreen,
  title={CodeGreen: Towards Improving Precision and Portability in Software Energy Measurement},
  author={Rajput, Saurabhsingh and Sharma, Tushar},
  journal={arXiv preprint arXiv:2603.17924},
  year={2026}
}

License

MPL-2.0 License - see LICENSE file.

Docs: smart-dal.github.io/codegreen