codegreen 0.3.16__tar.gz → 0.4.1__tar.gz

{codegreen-0.3.16/codegreen.egg-info → codegreen-0.4.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: codegreen
-Version: 0.3.16
-Summary: Know the true energy cost of your code -- hardware-level measurement via RAPL, NVML, IOReport, EMI
+Version: 0.4.1
+Summary: Know the true energy cost of your code
 Author-email: Saurabhsingh Rajput <saurabh@dal.ca>
 Maintainer-email: Saurabhsingh Rajput <saurabh@dal.ca>
 License: Mozilla Public License Version 2.0
@@ -411,7 +411,8 @@ Requires-Dist: pydantic>=1.10.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: packaging>=21.0
 Requires-Dist: markdown-it-py<4.0.0,>=3.0.0
-Requires-Dist: tree-sitter-language-pack
+Requires-Dist: tree-sitter<0.26,>=0.21
+Requires-Dist: tree-sitter-language-pack<1.0,>=0.7
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -487,7 +488,7 @@ sudo ./install.sh   # or: sudo codegreen init-sensors
 
 ## Usage
 
-### Measure energy of any command (like hyperfine, but for energy)
+### Measure energy of any command
 
 ```bash
 codegreen run -- python script.py
@@ -508,6 +509,34 @@ codegreen measure python script.py -g fine --json
 codegreen measure python script.py -g fine --export-plot energy.html
 ```
 
+### Manual measurement from Python (Session API)
+
+For span-based measurement of arbitrary code regions, import `codegreen.Session` directly — no CLI, no AST instrumentation:
+
+```python
+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):
+
+```python
+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](docs/website/docs/api/python.md) for the full reference.
+
 ### Static analysis (no execution)
 
 ```bash

{codegreen-0.3.16 → codegreen-0.4.1}/README.md

@@ -55,7 +55,7 @@ sudo ./install.sh   # or: sudo codegreen init-sensors
 
 ## Usage
 
-### Measure energy of any command (like hyperfine, but for energy)
+### Measure energy of any command
 
 ```bash
 codegreen run -- python script.py
@@ -76,6 +76,34 @@ codegreen measure python script.py -g fine --json
 codegreen measure python script.py -g fine --export-plot energy.html
 ```
 
+### Manual measurement from Python (Session API)
+
+For span-based measurement of arbitrary code regions, import `codegreen.Session` directly — no CLI, no AST instrumentation:
+
+```python
+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):
+
+```python
+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](docs/website/docs/api/python.md) for the full reference.
+
 ### Static analysis (no execution)
 
 ```bash

codegreen-0.4.1/benchmark/_workload_gpt2.py

@@ -0,0 +1,31 @@
+"""GPT-2 generation workload. Same script is used unchanged across modes."""
+import os, time
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+
+import torch
+from transformers import GPT2LMHeadModel, GPT2Tokenizer
+
+PROMPTS = [
+    "Energy-aware computing is",
+    "The cheapest way to train a model is",
+    "Hardware energy counters report",
+    "Modern transformers can be optimized by",
+] * 8  # 32 prompts -> dominates total runtime over import cost
+
+
+def main():
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    tok = GPT2Tokenizer.from_pretrained("gpt2")
+    tok.pad_token = tok.eos_token
+    tok.padding_side = "left"
+    model = GPT2LMHeadModel.from_pretrained("gpt2").to(device).eval()
+    batch = tok(PROMPTS, padding=True, return_tensors="pt").to(device)
+    t0 = time.perf_counter()
+    with torch.no_grad():
+        out = model.generate(**batch, max_new_tokens=128, do_sample=False)
+    dt = time.perf_counter() - t0
+    print(f"workload done: device={device} prompts={len(PROMPTS)} gen_s={dt:.2f}")
+
+
+if __name__ == "__main__":
+    main()

codegreen-0.4.1/benchmark/_workload_gpt2_session.py

@@ -0,0 +1,30 @@
+"""Same workload as cg_workload.py but bracketed under codegreen.Session.
+Measures the same wall-clock span codegreen run measures."""
+import os, time
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+
+import codegreen
+
+with codegreen.Session("whole-script", output_file=os.environ.get("CG_OUT", "/tmp/cg_session_run.json")) as s:
+    with s.task("everything"):
+        import torch
+        from transformers import GPT2LMHeadModel, GPT2Tokenizer
+
+        PROMPTS = [
+            "Energy-aware computing is",
+            "The cheapest way to train a model is",
+            "Hardware energy counters report",
+            "Modern transformers can be optimized by",
+        ] * 8
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        tok = GPT2Tokenizer.from_pretrained("gpt2")
+        tok.pad_token = tok.eos_token
+        tok.padding_side = "left"
+        model = GPT2LMHeadModel.from_pretrained("gpt2").to(device).eval()
+        batch = tok(PROMPTS, padding=True, return_tensors="pt").to(device)
+        t0 = time.perf_counter()
+        with torch.no_grad():
+            out = model.generate(**batch, max_new_tokens=128, do_sample=False)
+        dt = time.perf_counter() - t0
+        print(f"workload done: device={device} prompts={len(PROMPTS)} gen_s={dt:.2f}")

codegreen-0.4.1/benchmark/cg_modes_compare.py

@@ -0,0 +1,109 @@
+"""Run identical GPT-2 workload through CodeGreen access modes and compare totals.
+
+  Mode A: `codegreen run`   -- whole-program energy via the CLI
+  Mode B: `codegreen.Session` (manual span around the entire script body)
+
+Both bracket the same wall-clock span, so the readings should agree within
+small noise (no instrumentation overhead from extra checkpoints).
+
+A third reference is bare wall-clock (no codegreen) to check timing parity."""
+import json, os, statistics, subprocess, sys, time
+
+REPEAT = int(os.environ.get("CG_REPEAT", "3"))
+HERE = os.path.dirname(os.path.abspath(__file__))
+WORKLOAD = os.path.join(HERE, "_workload_gpt2.py")
+WORKLOAD_SESSION = os.path.join(HERE, "_workload_gpt2_session.py")
+
+
+def _parse_json_blob(stdout: str) -> dict:
+    """codegreen --json prints multi-line JSON; find the outermost {...} block."""
+    s = stdout
+    start = s.find("{")
+    end = s.rfind("}")
+    if start < 0 or end < 0 or end <= start:
+        raise RuntimeError(f"no JSON block found in stdout (last 300 chars):\n{s[-300:]}")
+    return json.loads(s[start:end + 1])
+
+
+def mode_cli_run():
+    cmd = ["codegreen", "run", "python", WORKLOAD, "--repeat", "1", "--warmup", "0", "--json"]
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+    if res.returncode != 0:
+        raise RuntimeError(f"codegreen run failed:\n{res.stderr[-400:]}")
+    d = _parse_json_blob(res.stdout)
+    e = d.get("energy_joules", {})
+    t = d.get("time_seconds", {})
+    energy = e.get("mean") if isinstance(e, dict) else e
+    secs = t.get("mean") if isinstance(t, dict) else t
+    return {"energy_j": energy, "power_w": d.get("power_watts"), "wall_s": secs,
+            "domains": d.get("domains") or {}}
+
+
+def mode_session():
+    out = f"/tmp/_session_{os.getpid()}_{time.time()}.json"
+    env = dict(os.environ); env["CG_OUT"] = out
+    res = subprocess.run([sys.executable, WORKLOAD_SESSION], env=env, capture_output=True, text=True, timeout=600)
+    if res.returncode != 0:
+        raise RuntimeError(f"session script failed:\n{res.stderr[-400:]}")
+    rep = json.load(open(out))
+    task = rep["tasks"][0]
+    return {"energy_j": task["energy_j"], "power_w": task["avg_power_w"],
+            "wall_s": task["duration_s"], "domains": task["domains"]}
+
+
+def mode_bare():
+    t0 = time.perf_counter()
+    res = subprocess.run([sys.executable, WORKLOAD], capture_output=True, text=True, timeout=600)
+    dt = time.perf_counter() - t0
+    if res.returncode != 0:
+        raise RuntimeError(f"bare run failed:\n{res.stderr[-400:]}")
+    return {"energy_j": None, "power_w": None, "wall_s": dt, "domains": {}}
+
+
+def repeat_run(label, fn):
+    rows = []
+    for _ in range(REPEAT):
+        try: rows.append(fn())
+        except Exception as e: rows.append({"error": str(e)})
+    return label, rows
+
+
+def stat(rows, key):
+    vs = [r[key] for r in rows if "error" not in r and r.get(key) is not None]
+    if not vs: return None
+    return statistics.mean(vs), (statistics.stdev(vs) if len(vs) > 1 else 0.0)
+
+
+def main():
+    print(f"GPT-2 workload, {REPEAT} repeats per mode\n")
+    rs = []
+    for label, fn in [("Bare (timing only)", mode_bare),
+                      ("CLI: codegreen run", mode_cli_run),
+                      ("Session (manual)",   mode_session)]:
+        print(f"-- running {label}")
+        rs.append(repeat_run(label, fn))
+
+    print(f"\n{'mode':<22} {'energy_j (mean +/- std)':<28} {'power_w':<10} {'wall_s':<14} runs")
+    print("-" * 92)
+    base_e = base_w = None
+    for label, rows in rs:
+        ok = [r for r in rows if "error" not in r]
+        e = stat(rows, "energy_j"); p = stat(rows, "power_w"); w = stat(rows, "wall_s")
+        if not ok:
+            print(f"{label:<22} ERROR")
+            continue
+        if e and base_e is None and "Session" not in label and "CLI" in label:
+            base_e = e[0]
+        if w and base_w is None: base_w = w[0]
+        e_str = f"{e[0]:>9.2f} +/- {e[1]:<6.2f}" if e else "      n/a            "
+        e_pct = f"({100*(e[0]-base_e)/base_e:+5.2f}%)" if (e and base_e) else "        "
+        p_str = f"{p[0]:>5.1f} W" if p else "  n/a "
+        w_str = f"{w[0]:>4.2f} s ({100*(w[0]-base_w)/base_w:+4.1f}%)" if (w and base_w) else f"{w[0]:>4.2f} s"
+        print(f"{label:<22} {e_str} J {e_pct}  {p_str:<10} {w_str:<14} {len(ok)}/{REPEAT}")
+
+    json.dump({"repeat": REPEAT, "results": rs}, open("/tmp/cg_modes_compare.json", "w"), indent=2, default=str)
+    print(f"\nraw JSON: /tmp/cg_modes_compare.json")
+
+
+if __name__ == "__main__":
+    main()

{codegreen-0.3.16 → codegreen-0.4.1}/codegreen/__init__.py

@@ -12,10 +12,10 @@ try:
     from importlib.metadata import version as _pkg_version
     __version__ = _pkg_version("codegreen")
 except Exception:
-    __version__ = "0.3.15"  # fallback for dev/editable installs
+    __version__ = "0.4.1"  # fallback for dev/editable installs
 __author__ = "Saurabhsingh Rajput"
 __email__ = "saurabh@dal.ca"
-__description__ = "Know the true energy cost of your code -- hardware-level measurement via RAPL, NVML, IOReport, EMI"
+__description__ = "Know the true energy cost of your code"
 
 # Ensure package root is on sys.path for imports
 import sys as _sys
@@ -25,9 +25,26 @@ _install_dir = str(_Path(__file__).resolve().parent.parent)
 if _install_dir not in _sys.path:
     _sys.path.insert(0, _install_dir)
 
+# Manual API symbols are lazy-loaded so that `import codegreen` (for the CLI,
+# instrumenter, or analyzer) does NOT pull in the runtime module and register
+# its atexit hook. The runtime is loaded only when a user actually accesses
+# Session / TaskResult / task.
+_LAZY_RUNTIME_ATTRS = {"Session", "TaskResult", "task"}
+
+
+def __getattr__(name):
+    if name in _LAZY_RUNTIME_ATTRS:
+        from codegreen.instrumentation.language_runtimes.python import codegreen_runtime as _rt
+        return getattr(_rt, name)
+    raise AttributeError(f"module 'codegreen' has no attribute {name!r}")
+
+
 __all__ = [
     "__version__",
     "__author__",
     "__email__",
     "__description__",
+    "Session",
+    "TaskResult",
+    "task",
 ]

{codegreen-0.3.16 → codegreen-0.4.1}/codegreen/analyzer/plot.py

@@ -249,3 +249,71 @@ def _render_matplotlib(points: list[dict[str, Any]], path: Path) -> None:
     fig.tight_layout(rect=[0, 0, 1, 0.96])
     fig.savefig(path, dpi=150, bbox_inches="tight", facecolor=BG)
     plt.close(fig)
+
+
+def export_session_plot(report: dict, path: Path) -> None:
+    """Render a power-vs-time chart from a codegreen.Session report.
+    Expects report["tasks"] with each task having `timeseries` of {t,j,w,d}."""
+    tasks = [t for t in report.get("tasks", []) if t.get("timeseries")]
+    if not tasks:
+        return
+    path = Path(path)
+    if path.suffix == ".html":
+        _render_session_plotly(tasks, path)
+    elif path.suffix in (".png", ".svg", ".pdf"):
+        _render_session_matplotlib(tasks, path)
+    else:
+        _render_session_plotly(tasks, path.with_suffix(".html"))
+
+
+def _render_session_plotly(tasks: list, path: Path) -> None:
+    try:
+        import plotly.graph_objects as go
+    except ImportError:
+        return
+    fig = go.Figure()
+    t0_ns = min(s["t"] for t in tasks for s in t["timeseries"])
+    for t in tasks:
+        ts = t["timeseries"]
+        x = [(s["t"] - t0_ns) / 1e9 for s in ts]
+        y = [s["w"] for s in ts]
+        fig.add_trace(go.Scatter(
+            x=x, y=y, mode="lines", name=t["name"],
+            line=dict(width=1),
+            hovertemplate="t=%{x:.3f}s  P=%{y:.1f}W<extra>" + t["name"] + "</extra>",
+        ))
+    fig.update_layout(
+        template="plotly_dark",
+        paper_bgcolor=BG, plot_bgcolor=CARD,
+        title=f"CodeGreen Session Power Trace  ({len(tasks)} task(s))",
+        xaxis_title="Time (s)", yaxis_title="Power (W)",
+        height=420, showlegend=True,
+        font=dict(color=TXT),
+    )
+    fig.write_html(str(path), include_plotlyjs=True, full_html=True)
+
+
+def _render_session_matplotlib(tasks: list, path: Path) -> None:
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError:
+        return
+    fig, ax = plt.subplots(figsize=(10, 4), facecolor=BG)
+    ax.set_facecolor(CARD)
+    t0_ns = min(s["t"] for t in tasks for s in t["timeseries"])
+    for t in tasks:
+        ts = t["timeseries"]
+        x = [(s["t"] - t0_ns) / 1e9 for s in ts]
+        y = [s["w"] for s in ts]
+        ax.plot(x, y, lw=0.8, label=t["name"])
+    ax.set_xlabel("Time (s)", color=TXT)
+    ax.set_ylabel("Power (W)", color=TXT)
+    ax.set_title("CodeGreen Session Power Trace", color=CG)
+    ax.legend(loc="upper right", fontsize=8)
+    ax.grid(alpha=0.15)
+    ax.tick_params(colors=TXT)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight", facecolor=BG)
+    plt.close(fig)

{codegreen-0.3.16 → codegreen-0.4.1}/codegreen/cli/cli.py

@@ -2428,7 +2428,7 @@ def run_command(
     budget: Annotated[Optional[float], typer.Option("--budget", help="Energy budget in Joules (fail if exceeded)")] = None,
     include_warmup: Annotated[bool, typer.Option("--include-warmup", help="Measure energy during warmup and include in results")] = False,
 ):
-    """[bold]Measure energy[/bold] of any shell command (like hyperfine but for energy).
+    """[bold]Measure energy[/bold] of any shell command with hardware-level precision.
 
     [bold]Important:[/bold] Use [cyan]--[/cyan] before commands that have their own flags.
     Without it, flags like -c or -jar are parsed as codegreen options and will fail.