codegreen 0.2.1

Energy-aware software development tool for measuring and optimizing code energy consumption

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

Requires Linux with RAPL support. The wheel includes the pre-built C++ measurement backend.

From source (recommended for development)

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

# For RAPL sensor access (one-time, requires sudo):
sudo ./install.sh   # or: sudo codegreen init-sensors
# Then log out and back in for group permissions

Requirements

• Linux (kernel 5.0+, Ubuntu 20.04+, Debian 11+, Fedora 35+, MacOS)
• Python 3.9+
• CMake 3.16+, g++ 9+ (for source builds only)
• Intel or AMD CPU with RAPL support
• perf (for codegreen run and benchmark validation)

Usage

Measure energy of any command (like hyperfine, but for energy)

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

Static analysis (no execution)

codegreen analyze python script.py --save-instrumented

Benchmark validation (against perf RAPL ground truth)

codegreen benchmark -p nbody spectralnorm -l python -r 5 --profilers codegreen 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 src/instrumentation/configs/ plus the tree-sitter grammar. No Python code changes needed.

Currently supported: Python, C, C++, JavaScript, Java.

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 (src/analysis/cfg/) that builds energy-annotated control flow graphs from source code:

from codegreen.analysis.cfg.builder import build_per_method_cfgs
from codegreen.analysis.cfg.energy_flow 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.

Architecture

• C++ NEMB backend: RAPL energy reading with sub-microsecond timestamping, configurable polling interval
• 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

Upgrading

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

Citation

@software{Rajput_CodeGreen_2026,
  author = {Rajput, Saurabhsingh},
  doi = {10.5281/zenodo.18371772},
  title = {{CodeGreen: Per-Function Energy Measurement for Multi-Language Software}},
  url = {https://smart-dal.github.io/codegreen/},
  version = {v0.2.0},
  year = {2026}
}

License

MPL-2.0 License - see LICENSE file.

Docs: smart-dal.github.io/codegreen