codegreen 0.3.16__tar.gz → 0.4.0__tar.gz

{codegreen-0.3.16/codegreen.egg-info → codegreen-0.4.0}/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.0
+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.0}/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.0/benchmark/cg_vs_codecarbon_transformers.py

@@ -0,0 +1,109 @@
+"""Verify codegreen.Session against CodeCarbon EmissionsTracker on a transformers
+fine-tune (mirrors https://docs.codecarbon.io/latest/how-to/transformers/).
+
+Trackers run **sequentially** (not concurrent) to avoid double-instrumentation noise:
+
+  Phase 1: CodeCarbon-only  -> 1 fine-tune  (baseline reference)
+  Phase 2: CodeGreen-only   -> 3 fine-tunes inside one Session, one per API form:
+             explicit start_task / stop_task
+             `with sess.task(...)` context manager
+             `@codegreen.task(...)` decorator
+
+Each fine-tune trains on the same IMDB slice with the same TrainingArguments,
+so per-task CG energy / time / power are directly comparable to the CC baseline.
+
+Run: python -m benchmark.cg_vs_codecarbon_transformers [--n 128] [--epochs 1] [--batch 8]
+"""
+import argparse, json, os, time
+
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+
+
+def _build_dataset_and_model_factory(model_name, n):
+    from transformers import AutoTokenizer, AutoModelForSequenceClassification
+    from datasets import load_dataset
+    tok = AutoTokenizer.from_pretrained(model_name)
+    ds = load_dataset("imdb", split=f"train[:{n}]")
+    ds = ds.map(lambda b: tok(b["text"], truncation=True, padding="max_length", max_length=128), batched=True)
+    ds = ds.rename_column("label", "labels")
+    ds.set_format("torch", columns=["input_ids", "attention_mask", "labels"])
+    return ds, lambda: AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)
+
+
+def _train_args(out, epochs, batch):
+    from transformers import TrainingArguments
+    return TrainingArguments(output_dir=out, num_train_epochs=epochs,
+                             per_device_train_batch_size=batch, save_strategy="no",
+                             report_to=[], disable_tqdm=True, logging_strategy="no", use_cpu=True)
+
+
+def _do_train(new_model, ds, out, epochs, batch):
+    from transformers import Trainer
+    Trainer(model=new_model(), args=_train_args(out, epochs, batch), train_dataset=ds).train()
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--n", type=int, default=128)
+    p.add_argument("--epochs", type=int, default=1)
+    p.add_argument("--batch", type=int, default=8)
+    p.add_argument("--out", default="/tmp/cg_session.json")
+    p.add_argument("--model", default="distilbert-base-uncased")
+    args = p.parse_args()
+
+    ds, new_model = _build_dataset_and_model_factory(args.model, args.n)
+
+    # ---- Phase 1: CodeCarbon-only baseline ----
+    from codecarbon import EmissionsTracker
+    cc = EmissionsTracker(project_name="cg_vs_cc", output_dir="/tmp",
+                          log_level="error", save_to_file=False)
+    cc.start()
+    t0 = time.perf_counter()
+    _do_train(new_model, ds, "/tmp/_cc", args.epochs, args.batch)
+    cc_wall = time.perf_counter() - t0
+    co2 = cc.stop()
+    cc_j = (cc.final_emissions_data.energy_consumed or 0.0) * 3.6e6
+
+    # ---- Phase 2: CodeGreen Session (3 forms in one session, sequential) ----
+    import codegreen
+    sess = codegreen.Session(output_file=args.out, record_time_series=True)
+    sess.start()
+    t0 = time.perf_counter()
+
+    sess.start_task("explicit_train")
+    _do_train(new_model, ds, "/tmp/_t1", args.epochs, args.batch)
+    sess.stop_task("explicit_train")
+
+    with sess.task("context_train"):
+        _do_train(new_model, ds, "/tmp/_t2", args.epochs, args.batch)
+
+    @codegreen.task("decorator_train")
+    def fine_tune():
+        _do_train(new_model, ds, "/tmp/_t3", args.epochs, args.batch)
+    fine_tune()
+
+    cg_wall = time.perf_counter() - t0
+    sess.stop()
+
+    rep = json.load(open(args.out))
+    tasks = {t["name"]: t for t in rep["tasks"]}
+    cg_total_tasks = sum(t["energy_j"] for t in rep["tasks"])
+
+    # Per-task delta vs CC baseline (CC ran 1 train; each CG task ran 1 train)
+    print(f"\n{args.model} | IMDB[:{args.n}] | {args.epochs} ep | batch={args.batch}\n")
+    print(f"Phase 1 (CodeCarbon, 1 train)")
+    print(f"  wall {cc_wall:.2f} s   energy {cc_j:.2f} J   power {cc_j/cc_wall:.2f} W   CO2 {co2*1000:.4f} g")
+    print(f"\nPhase 2 (CodeGreen Session, 3 trains sequential)")
+    print(f"  total span energy {rep['total']['energy_j']:.2f} J   power {rep['total']['power_w']:.2f} W   wall {cg_wall:.2f} s")
+    print(f"\n  task                 energy(J)  dur(s)  power(W)   ts   delta-vs-CC")
+    for name in ("explicit_train", "context_train", "decorator_train"):
+        t = tasks[name]
+        ts = len(t.get("time_series", []))
+        d = 100 * (t["energy_j"] - cc_j) / cc_j if cc_j else float("nan")
+        print(f"  {name:<18}  {t['energy_j']:>8.2f}  {t['duration_s']:>6.2f}  {t['power_w']:>7.2f}  {ts:>5}   {d:+7.2f}%")
+    print(f"\n  domains captured: {list(tasks['explicit_train'].get('per_domain', {}).keys())}")
+
+
+if __name__ == "__main__":
+    main()

{codegreen-0.3.16 → codegreen-0.4.0}/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.0"  # 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.0}/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.0}/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.