codegreen 0.3.0

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

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

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: energy measurement requires sudo (IOReport access):
sudo codegreen run -- python script.py

Platform support

Platform	pip install	Energy measurement	Backend
Linux x86_64 (Intel/AMD)	Pre-built wheel	Full	RAPL via NEMB
macOS ARM64 (Apple Silicon)	Pre-built wheel	Full	IOReport + kpc via NEMB
macOS Intel	From source	Full	IOReport via NEMB
Other	From source	Time-only	Fallback

Requirements

• Python 3.9+
• Linux: kernel 5.0+, Intel/AMD CPU with RAPL support
• macOS: Apple Silicon (M1-M5) or Intel, sudo for energy measurement
• Source builds: CMake 3.16+, C++17 compiler

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 codegreen/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 (codegreen/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: platform-aware energy measurement (RAPL on Linux, IOReport on macOS), 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

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