green-bench 0.2.0__py3-none-any.whl

green_bench/__init__.py

@@ -0,0 +1,3 @@
+"""green-bench: automated green software energy benchmarking experiments."""
+
+__version__ = "0.2.0"

green_bench/__main__.py

@@ -0,0 +1,279 @@
+import re
+import shlex
+import shutil
+import sys
+import time
+from datetime import datetime
+from importlib import resources
+from pathlib import Path
+from typing import Optional
+
+import typer
+import typer.core
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+from rich.text import Text
+
+from green_bench import __version__
+from green_bench.analysis import AnalysisEngine
+from green_bench.environment import EnvironmentManager
+from green_bench.measurement import BenchmarkError, MeasurementWrapper
+from green_bench.orchestrator import ExperimentOrchestrator
+from green_bench.results import FOREIGN, HAS_RESULTS, classify, describe
+
+console = Console()
+
+_SUBCOMMANDS = ("compare", "demo")
+
+
+class _DefaultToCompare(typer.core.TyperGroup):
+    """`green-bench --name ...` is shorthand for `green-bench compare --name ...`."""
+
+    def parse_args(self, ctx, args):
+        if args and args[0] not in _SUBCOMMANDS and args[0] not in ctx.help_option_names:
+            args = ["compare", *args]
+        return super().parse_args(ctx, args)
+
+
+app = typer.Typer(
+    cls=_DefaultToCompare,
+    add_completion=False,
+    help="Green Software Energy Benchmarking CLI Tool.\n\n"
+         "Run `green-bench demo` to try it on a bundled example, or `green-bench compare --help` "
+         "(or just `green-bench --name ...`) to compare two versions of your own project.",
+)
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def _version_callback(value: bool):
+    if value:
+        typer.echo(f"green-bench {__version__}")
+        raise typer.Exit()
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty()
+
+
+def _confirm_overwrite(results_dir: Path, resume: bool, overwrite: bool) -> None:
+    """Decide what to do with an existing results folder (before anything is created or deleted).
+
+    Nothing is deleted here: the orchestrator clears the folder after pre-flight has passed.
+    """
+    if resume:
+        return
+    state = classify(results_dir)
+    if state == FOREIGN:
+        raise BenchmarkError(
+            f"{results_dir} exists but does not look like a GreenBench results folder, so it will "
+            "not be touched. Choose a different --name or --output."
+        )
+    if state != HAS_RESULTS or overwrite:  # missing or empty folders are simply reused
+        return
+    if not _is_interactive():
+        raise BenchmarkError(
+            f"Results folder already exists: {results_dir}. Use --overwrite to replace it "
+            "or --resume to continue the unfinished experiment."
+        )
+    console.print(f"[yellow]Results folder already exists:[/yellow] {escape(str(results_dir.resolve()))}")
+    console.print(f"  contains {describe(results_dir)}")
+    console.print("  (To continue an unfinished experiment instead, answer n and run again with --resume.)")
+    if not typer.confirm("Delete these previous results and start over?", default=False):
+        console.print("Aborted. The existing results were not changed.")
+        raise typer.Exit(1)
+
+
+def _validate_name(value: str) -> str:
+    if not _NAME_RE.match(value):
+        raise typer.BadParameter(
+            "Use letters, digits, '.', '_' or '-' only (it becomes a folder name)."
+        )
+    return value
+
+
+@app.command()
+def compare(
+    name: str = typer.Option(..., "--name", help="Name of the benchmark (used as the results folder name)",
+                             callback=_validate_name),
+    base: Path = typer.Option(..., "--base", "-b", help="Directory containing the baseline version of the project"),
+    compare: Path = typer.Option(..., "--compare", "-c", help="Directory containing the version to test"),
+    setup: str = typer.Option(..., "--setup", help="Shell command run before every measurement (not measured). Use 'true' for none"),
+    cmd: str = typer.Option(..., "--cmd", help="Shell command to measure, e.g. 'python bench.py'. Chaining (a && b, pipes, ;) is rejected: put multi-step workloads in one script"),
+    iterations: int = typer.Option(30, "--iterations", "-n", min=2, help="Runs per version (30+ recommended)"),
+    carbon_intensity: float = typer.Option(475.0, "--intensity", min=0.0, help="Carbon intensity in gCO2e/kWh"),
+    output: Path = typer.Option(Path("green-bench-results"), "--output", "-o", help="Folder where results are saved"),
+    seed: Optional[int] = typer.Option(None, "--seed", help="Seed for the run order (default: random; it is printed so you can reproduce it)"),
+    cooldown: float = typer.Option(10.0, "--cooldown", min=0.0, help="Seconds to wait between setup and each measurement"),
+    interval: int = typer.Option(500, "--interval", min=1, help="EnergiBridge sampling interval in ms"),
+    timeout: Optional[float] = typer.Option(None, "--timeout", min=1.0, help="Abort any single command after this many seconds"),
+    keep_raw: bool = typer.Option(False, "--keep-raw", help="Keep each run's raw EnergiBridge CSV in <results>/raw"),
+    resume: bool = typer.Option(False, "--resume", help="Continue an interrupted experiment with the same name"),
+    overwrite: bool = typer.Option(False, "--overwrite", help="Replace an existing results folder without asking"),
+    no_plots: bool = typer.Option(False, "--no-plots", help="Skip plot generation"),
+    version: Optional[bool] = typer.Option(None, "--version", callback=_version_callback, is_eager=True,
+                                           help="Show the version and exit"),
+):
+    """
+    Automates energy measurement between two versions of a project.
+    """
+    _run_compare(
+        name=name, base=base, compare=compare, setup=setup, cmd=cmd, iterations=iterations,
+        carbon_intensity=carbon_intensity, output=output, seed=seed, cooldown=cooldown,
+        interval=interval, timeout=timeout, keep_raw=keep_raw, resume=resume,
+        overwrite=overwrite, no_plots=no_plots,
+    )
+
+
+def _run_compare(*, name, base, compare, setup, cmd, iterations, carbon_intensity, output, seed,
+                 cooldown, interval, timeout, keep_raw, resume, overwrite, no_plots):
+    console.print("━" * 75, style="dim white")
+    console.print(f"[bold green]GreenBench: Automated Software Energy Benchmarking Engine v{__version__}[/bold green]")
+    console.print("━" * 75, style="dim white")
+
+    results_dir = output / name
+    start_time = datetime.now()
+    start_perf = time.perf_counter()
+
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold white", justify="left", width=20)
+    grid.add_column(style="white")
+    grid.add_row("Project:", escape(name))
+    grid.add_row("Setup:", escape(setup))
+    grid.add_row("Workload:", escape(cmd))
+    grid.add_row("Base:", f"[cyan]{escape(str(base))}[/cyan]")
+    grid.add_row("Compare:", f"[green]{escape(str(compare))}[/green]")
+    grid.add_row("Iterations:", f"{iterations} per version")
+    grid.add_row("Output:", escape(str(results_dir)))
+    grid.add_row("Start Time:", start_time.strftime("%Y-%m-%d %H:%M:%S"))
+    console.print(grid)
+    console.print()
+
+    exit_code = 0
+    try:
+        _confirm_overwrite(results_dir, resume, overwrite)
+        environment = EnvironmentManager(base_path=base, compare_path=compare, output_path=results_dir)
+        orchestrator = ExperimentOrchestrator(environment, MeasurementWrapper(), console=console)
+        summary = orchestrator.run_benchmarks(
+            name=name, base=str(base), compare=str(compare), setup=setup, cmd=cmd,
+            iterations=iterations, seed=seed, cooldown=cooldown, interval_ms=interval,
+            timeout=timeout, keep_raw=keep_raw, resume=resume,
+        )
+        if not summary.completed:
+            exit_code = 1
+
+        console.print("[bold yellow][3/3][/bold yellow] [bold white]Analytical Data & Statistical Processing...[/bold white]")
+        report = AnalysisEngine.compare_results(summary.data_csv_path, grid_intensity=carbon_intensity, console=console)
+
+        plot_dir = None
+        if not no_plots and summary.runs_recorded >= 2:
+            plot_dir = AnalysisEngine.generate_visuals(summary.data_csv_path.parent)
+            if plot_dir is None:
+                console.print(
+                    "  [yellow]Plots skipped: install them with[/yellow] " + escape("pip install 'green-bench[plots]'")
+                )
+            else:
+                console.print("  • Generating plots... [bold green]Done.[/bold green]")
+
+        console.print(report)
+        if plot_dir:
+            console.print(f"[magenta]Artifacts stored at: {escape(str(plot_dir))}[/magenta]")
+        if not summary.completed:
+            console.print("[bold red]The experiment did not finish. The analysis above uses partial data.[/bold red]")
+    except BenchmarkError as err:
+        console.print(f"\n[bold red]Error:[/bold red] {escape(str(err))}")
+        exit_code = 1
+    except KeyboardInterrupt:
+        console.print("\n[bold red]Interrupted.[/bold red] Partial results are kept; continue with --resume.")
+        exit_code = 130
+
+    total = time.perf_counter() - start_perf
+    console.print("-" * 50)
+    console.print(f"Ended at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    console.print(f"Total duration: {int(total // 60):02d}:{int(total % 60):02d} ({total:.1f} s)")
+    raise typer.Exit(exit_code)
+
+
+DEMO_NAME = "nqueens-demo"
+DEMO_DIR = Path("green-bench-demo")
+DEMO_WORKLOAD = "nqueens.py 13"
+
+
+def _copy_demo_programs(dest: Path) -> None:
+    """Copy the bundled naive/optimized N-Queens programs into `dest` so the user can see and reuse them."""
+    source = resources.files("green_bench") / "demo_data" / "nqueens"
+    for version in ("naive", "optimized"):
+        target = dest / version
+        target.mkdir(parents=True, exist_ok=True)
+        for item in (source / version).iterdir():
+            if item.is_file() and item.name.endswith(".py"):
+                (target / item.name).write_bytes(item.read_bytes())
+
+
+def _format_command(*, name: str, base: Path, compare: Path, setup: str, cmd: str, iterations: int,
+                    cooldown: float, output: Path | None = None, seed: int | None = None) -> str:
+    """The `green-bench` invocation as a copy-pasteable, multi-line shell command."""
+    def fmt(value: float) -> str:
+        return f"{value:g}"
+
+    lines = [
+        f"green-bench --name {shlex.quote(name)}",
+        f"-b {shlex.quote(base.as_posix())} -c {shlex.quote(compare.as_posix())}",
+        f"--setup {shlex.quote(setup)} --cmd {shlex.quote(cmd)}",
+        f"-n {iterations} --cooldown {fmt(cooldown)}",
+    ]
+    if output is not None:
+        lines[-1] += f" -o {shlex.quote(output.as_posix())}"
+    if seed is not None:
+        lines[-1] += f" --seed {seed}"
+    return " \\\n  ".join(lines)
+
+
+def _print_command(command: str, title: str) -> None:
+    console.print(f"[bold cyan]{title}[/bold cyan]")
+    console.print(Text(command), soft_wrap=True, highlight=False)
+    console.print()
+
+
+@app.command()
+def demo(
+    iterations: int = typer.Option(5, "--iterations", "-n", min=2, help="Runs per version"),
+    cooldown: float = typer.Option(5.0, "--cooldown", min=0.0, help="Seconds to wait between setup and each measurement"),
+    output: Path = typer.Option(Path("green-bench-results"), "--output", "-o", help="Folder where results are saved"),
+    seed: Optional[int] = typer.Option(None, "--seed", help="Seed for the run order"),
+    overwrite: bool = typer.Option(False, "--overwrite", help="Replace an existing demo results folder without asking"),
+    no_plots: bool = typer.Option(False, "--no-plots", help="Skip plot generation"),
+):
+    """
+    Try GreenBench on a bundled example (naive vs. bitmask N-Queens) and see the exact command it ran.
+    """
+    _copy_demo_programs(DEMO_DIR)
+    python = "python" if sys.platform == "win32" or not shutil.which("python3") else "python3"
+    base, compare, setup, cmd = DEMO_DIR / "naive", DEMO_DIR / "optimized", "true", f"{python} {DEMO_WORKLOAD}"
+    command = _format_command(
+        name=DEMO_NAME, base=base, compare=compare, setup=setup, cmd=cmd, iterations=iterations,
+        cooldown=cooldown, output=None if output == Path("green-bench-results") else output, seed=seed,
+    )
+
+    console.print(f"Demo programs copied to [bold]{escape(str(DEMO_DIR))}/[/bold] (naive/ and optimized/).")
+    _print_command(command, "Running this GreenBench command:")
+
+    try:
+        _run_compare(
+            name=DEMO_NAME, base=base, compare=compare, setup=setup, cmd=cmd, iterations=iterations,
+            carbon_intensity=475.0, output=output, seed=seed, cooldown=cooldown, interval=500,
+            timeout=None, keep_raw=False, resume=False, overwrite=overwrite, no_plots=no_plots,
+        )
+    except typer.Exit:
+        console.print()
+        _print_command(
+            command,
+            "To repeat this on your own project, run the same command with -b/-c pointing at your two "
+            "directories and --cmd at your workload:",
+        )
+        raise
+
+
+if __name__ == "__main__":
+    app()

green_bench/analysis.py

@@ -0,0 +1,296 @@
+"""Energy integration, carbon conversion, statistics and (optional) plots."""
+
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from scipy.stats import mannwhitneyu
+
+from green_bench.measurement import MeasurementError
+
+JOULES_PER_KWH = 3.6e6
+ALPHA = 0.05
+MIN_RECOMMENDED_N = 10
+
+# Energy sources in order of preference. EnergiBridge exposes different columns per
+# platform, so we inspect the header instead of assuming one name.
+#   power columns   -> integrated over time (trapezoidal rule)
+#   energy columns  -> cumulative counters (last sample minus first sample)
+POWER_COLUMNS = ["SYSTEM_POWER (Watts)"]
+ENERGY_COLUMNS = ["PACKAGE_ENERGY (J)", "CPU_ENERGY (J)"]
+TIME_COLUMN = "Time"  # milliseconds
+
+
+class AnalysisEngine:
+    """Data processing, numerical integration, significance testing, carbon maths and plots."""
+
+    # ------------------------------------------------------------------ energy
+    @staticmethod
+    def _pick_column(columns, exact: list[str], suffix: str) -> Optional[str]:
+        for name in exact:
+            if name in columns:
+                return name
+        # Fallback: first column that looks like the right kind of metric, e.g. "FOO_POWER (Watts)".
+        for name in columns:
+            if name.endswith(suffix):
+                return name
+        return None
+
+    @classmethod
+    def calculate_eb_joules(cls, csv_path: Path) -> tuple[float, float]:
+        """Total energy (Joules) and duration (seconds) of one EnergiBridge run.
+
+        Raises MeasurementError (never returns a silent 0) if the file is missing,
+        too short, or has no recognisable energy/power column.
+        """
+        csv_path = Path(csv_path)
+        try:
+            df = pd.read_csv(csv_path)
+        except FileNotFoundError:
+            raise MeasurementError(f"Telemetry file not found: {csv_path}") from None
+        except Exception as err:
+            raise MeasurementError(f"Could not read telemetry file {csv_path.name}: {err}") from err
+
+        if len(df) < 2:
+            raise MeasurementError(
+                f"{csv_path.name} has {len(df)} sample(s); need at least 2. "
+                "The workload may be too short for the sampling interval."
+            )
+        if TIME_COLUMN not in df.columns:
+            raise MeasurementError(f"{csv_path.name} has no '{TIME_COLUMN}' column. Columns: {list(df.columns)}")
+
+        elapsed = (df[TIME_COLUMN] - df[TIME_COLUMN].min()) / 1000.0
+        duration = float(elapsed.max())
+        if duration <= 0:
+            raise MeasurementError(
+                f"{csv_path.name} covers 0 seconds: the workload finished before EnergiBridge could take "
+                "two samples at different times. Use a workload that runs for several seconds."
+            )
+
+        power_col = cls._pick_column(df.columns, POWER_COLUMNS, "(Watts)")
+        if power_col is not None:
+            joules = float(np.trapezoid(df[power_col], x=elapsed))
+        else:
+            energy_col = cls._pick_column(df.columns, ENERGY_COLUMNS, "ENERGY (J)")
+            if energy_col is None:
+                raise MeasurementError(
+                    "No known power or energy column found in EnergiBridge output. "
+                    f"Columns present: {list(df.columns)}"
+                )
+            joules = float(df[energy_col].iloc[-1] - df[energy_col].iloc[0])
+
+        if not np.isfinite(joules) or joules <= 0:
+            raise MeasurementError(
+                f"{csv_path.name} produced an invalid energy value ({joules}). "
+                "EnergiBridge may lack permission to read the energy counters (try an elevated terminal), "
+                "or the platform reports no usable power data."
+            )
+        return joules, duration
+
+    @staticmethod
+    def calculate_kwh(total_joules: float) -> float:
+        """Joules -> kilowatt-hours."""
+        return total_joules / JOULES_PER_KWH
+
+    @staticmethod
+    def calculate_co2_emissions(kwh: float, grid_intensity: float = 475.0) -> float:
+        """Operational emissions in gCO2e for ``kwh`` at ``grid_intensity`` gCO2e/kWh."""
+        return kwh * grid_intensity
+
+    # -------------------------------------------------------------- statistics
+    @staticmethod
+    def _bootstrap_median_change_ci(base: np.ndarray, treat: np.ndarray, n_boot: int = 5000, seed: int = 0):
+        """95% percentile-bootstrap CI for the % change in median energy."""
+        rng = np.random.default_rng(seed)
+        b = rng.choice(base, size=(n_boot, len(base)), replace=True)
+        t = rng.choice(treat, size=(n_boot, len(treat)), replace=True)
+        mb, mt = np.median(b, axis=1), np.median(t, axis=1)
+        changes = (mt - mb) / mb * 100
+        return float(np.percentile(changes, 2.5)), float(np.percentile(changes, 97.5))
+
+    @classmethod
+    def compare_results(cls, data_csv_path: Path, grid_intensity: float = 475.0, console: Optional[Console] = None):
+        """Compare baseline vs treatment and write ``results.csv`` next to the data.
+
+        Returns a rich renderable report, or a plain string if there is too little data.
+        """
+        console = console or Console()
+        data_csv_path = Path(data_csv_path)
+        if not data_csv_path.exists():
+            return "No results were recorded, so there is nothing to analyse."
+        df = pd.read_csv(data_csv_path)
+
+        base = df[df["label"] == "baseline"]["energy_joules"].to_numpy(dtype=float)
+        treat = df[df["label"] == "treatment"]["energy_joules"].to_numpy(dtype=float)
+        n_base, n_treat = len(base), len(treat)
+
+        if n_base < 2 or n_treat < 2:
+            return "Need at least 2 runs per group for statistical analysis."
+
+        u_stat, p_value = mannwhitneyu(base, treat, alternative="two-sided")
+        mean_base, mean_treat = float(base.mean()), float(treat.mean())
+        med_base, med_treat = float(np.median(base)), float(np.median(treat))
+        if mean_base <= 0 or med_base <= 0:
+            raise MeasurementError("Baseline energy is not positive; cannot compute relative change.")
+
+        pct_change = (mean_treat - mean_base) / mean_base * 100
+        pct_change_median = (med_treat - med_base) / med_base * 100
+        ci_low, ci_high = cls._bootstrap_median_change_ci(base, treat)
+        # P(a random treatment run uses less energy than a random baseline run), ties count half.
+        prob_lower = float(u_stat) / (n_base * n_treat)
+
+        co2_base = cls.calculate_co2_emissions(cls.calculate_kwh(mean_base), grid_intensity)
+        co2_treat = cls.calculate_co2_emissions(cls.calculate_kwh(mean_treat), grid_intensity)
+        co2_delta = co2_treat - co2_base
+
+        metrics = {
+            "baseline_n": n_base,
+            "treatment_n": n_treat,
+            "baseline_mean_joules": mean_base,
+            "treatment_mean_joules": mean_treat,
+            "baseline_median_joules": med_base,
+            "treatment_median_joules": med_treat,
+            "treatment_effect_pct_mean": pct_change,
+            "treatment_effect_pct_median": pct_change_median,
+            "median_effect_ci95_low_pct": ci_low,
+            "median_effect_ci95_high_pct": ci_high,
+            "prob_treatment_lower": prob_lower,
+            "grid_intensity_gco2e_kwh": grid_intensity,
+            "delta_gco2e_execution": co2_delta,
+            "mann_whitney_u_stat": float(u_stat),
+            "p_value": float(p_value),
+            "is_statistically_significant": bool(p_value < ALPHA),
+        }
+        results_csv_path = data_csv_path.parent / "results.csv"
+        pd.DataFrame({"metric": list(metrics), "value": list(metrics.values())}).to_csv(results_csv_path, index=False)
+        console.print(f"  • Saved summary CSV to [bold cyan]{results_csv_path}[/bold cyan]")
+
+        return cls.generate_report(metrics)
+
+    @classmethod
+    def generate_report(cls, m: dict) -> Panel:
+        is_significant = m["p_value"] < ALPHA
+        res_color = "green" if is_significant else "yellow"
+        res_text = (
+            "Statistically significant difference detected (reject null hypothesis)"
+            if is_significant
+            else "No statistically significant difference detected (fail to reject null hypothesis)"
+        )
+
+        table = Table(box=None, padding=(0, 2), show_header=False)
+        table.add_column("Metric", style="bold cyan")
+        table.add_column("Value", justify="right")
+
+        table.add_row("Baseline N Size", f"{m['baseline_n']}")
+        table.add_row("Treatment N Size", f"{m['treatment_n']}")
+        table.add_row(
+            "Baseline Median Energy",
+            f"{m['baseline_median_joules']:,.2f} J [dim](mean {m['baseline_mean_joules']:,.2f} J)[/dim]",
+        )
+        table.add_row(
+            "Treatment Median Energy",
+            f"{m['treatment_median_joules']:,.2f} J [dim](mean {m['treatment_mean_joules']:,.2f} J)[/dim]",
+        )
+        style = "green" if m["treatment_effect_pct_median"] < 0 else "red"
+        table.add_row(
+            "Treatment Effect (median)",
+            f"[{style}]{m['treatment_effect_pct_median']:+.2f}%[/{style}] "
+            f"[dim](95% CI {m['median_effect_ci95_low_pct']:+.1f}% to {m['median_effect_ci95_high_pct']:+.1f}%)[/dim]",
+        )
+        table.add_row("Treatment Effect (mean)", f"{m['treatment_effect_pct_mean']:+.2f}%")
+        table.add_row("P(treatment run < baseline run)", f"{m['prob_treatment_lower']:.0%}")
+        table.add_row("Grid Intensity Used", f"{m['grid_intensity_gco2e_kwh']:,.2f} gCO2e/kWh")
+        co2_style = "green" if m["delta_gco2e_execution"] < 0 else "red"
+        table.add_row(
+            "Operational Emissions Delta",
+            f"[{co2_style}]{m['delta_gco2e_execution']:+.6f} gCO2e/exec[/{co2_style}]",
+        )
+        table.add_section()
+        table.add_row("\n[bold white]Hypothesis Test (Mann-Whitney U)[/bold white]", "")
+        table.add_row("  U statistic", f"{m['mann_whitney_u_stat']:,.1f}")
+        table.add_row("  p-value", f"{m['p_value']:.5f} [dim](α = {ALPHA})[/dim]")
+
+        parts = [table]
+        small_n = min(m["baseline_n"], m["treatment_n"])
+        if small_n < MIN_RECOMMENDED_N:
+            parts.append(
+                Text(
+                    f"\n Warning: only {small_n} runs per group; results are unreliable "
+                    f"(>= {MIN_RECOMMENDED_N} recommended, 30 for robust conclusions).",
+                    style="bold yellow",
+                )
+            )
+        parts.append(
+            Text.assemble("\n", (" OUTCOME: ", f"bold {res_color}"), (res_text, "bold white"))
+        )
+        return Panel(
+            Group(*parts),
+            title="[bold white]METRIC EVALUATION & STATISTICAL ANALYSIS[/bold white]",
+            title_align="left",
+            border_style="green" if is_significant else "blue",
+            expand=False,
+            padding=(1, 3),
+        )
+
+    # ------------------------------------------------------------------- plots
+    @staticmethod
+    def plots_available() -> bool:
+        try:
+            import matplotlib  # noqa: F401
+            import seaborn  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    @staticmethod
+    def generate_visuals(results_dir: Path) -> Optional[Path]:
+        """Write the energy plots. Returns None if the optional plotting extra is missing."""
+        if not AnalysisEngine.plots_available():
+            return None
+        import matplotlib
+
+        matplotlib.use("Agg")  # headless-safe
+        import matplotlib.pyplot as plt
+        import seaborn as sns
+
+        results_dir = Path(results_dir)
+        df = pd.read_csv(results_dir / "data.csv")
+        palette = {"baseline": "#007F61", "treatment": "#fb9b60"}
+        with sns.axes_style("whitegrid"):
+            # Plot 1: distribution per group
+            fig, ax = plt.subplots(figsize=(8, 6))
+            sns.boxplot(
+                x="label", y="energy_joules", data=df, ax=ax, orient="v", palette=palette, hue="label",
+                legend=False, width=0.4, boxprops={"edgecolor": "#DDDDDD", "linewidth": 1},
+                whiskerprops={"linewidth": 1.5, "alpha": 0.4}, capprops={"linewidth": 1.5, "alpha": 0.4},
+                medianprops={"linewidth": 1, "alpha": 0.3},
+            )
+            sns.stripplot(x="label", y="energy_joules", data=df, ax=ax, color="black", alpha=0.3, size=5, jitter=0.15)
+            ax.set_title("Energy Consumption Distribution Across Groups", fontsize=12, fontweight="bold", pad=12)
+            ax.set_ylabel("Total Operational Energy (Joules)")
+            ax.set_xlabel("Experimental Group")
+            fig.savefig(results_dir / "energy_distribution.png", dpi=300)
+            plt.close(fig)
+
+            # Plot 2: energy over the course of the experiment
+            df_plot = df.copy()
+            df_plot["sequence_idx"] = df_plot.groupby("label").cumcount() + 1
+            fig, ax = plt.subplots(figsize=(10, 5))
+            sns.lineplot(
+                x="sequence_idx", y="energy_joules", hue="label", data=df_plot, ax=ax,
+                marker="o", markersize=6, linewidth=2, palette=palette,
+            )
+            ax.set_title("Runtime Operational Stability Over Iterations", fontsize=12, fontweight="bold", pad=12)
+            ax.set_ylabel("Total Operational Energy (Joules)")
+            ax.set_xlabel("Sequential Iteration Phase (per group)")
+            ax.legend(title="Experimental Group", frameon=True)
+            sns.despine(ax=ax, trim=True)
+            fig.tight_layout()
+            fig.savefig(results_dir / "energy_stability.png", dpi=300)
+            plt.close(fig)
+        return results_dir

green_bench/demo_data/nqueens/naive/nqueens.py

@@ -0,0 +1,18 @@
+"""Count N-Queens solutions: simple backtracking that copies lists (slow on purpose)."""
+import sys
+
+
+def solve(n, row=0, cols=(), diag1=(), diag2=()):
+    if row == n:
+        return 1
+    total = 0
+    for col in range(n):
+        if col in cols or (row - col) in diag1 or (row + col) in diag2:
+            continue
+        total += solve(n, row + 1, cols + (col,), diag1 + (row - col,), diag2 + (row + col,))
+    return total
+
+
+if __name__ == "__main__":
+    n = int(sys.argv[1]) if len(sys.argv) > 1 else 9
+    print(f"{n}-queens solutions: {solve(n)}")

green_bench/demo_data/nqueens/optimized/nqueens.py

@@ -0,0 +1,20 @@
+"""Count N-Queens solutions: same algorithm using bitmasks (no allocations)."""
+import sys
+
+
+def solve(n, cols=0, diag1=0, diag2=0, full=None):
+    full = (1 << n) - 1 if full is None else full
+    if cols == full:
+        return 1
+    total = 0
+    free = full & ~(cols | diag1 | diag2)
+    while free:
+        bit = free & -free
+        free ^= bit
+        total += solve(n, cols | bit, ((diag1 | bit) << 1) & full, (diag2 | bit) >> 1, full)
+    return total
+
+
+if __name__ == "__main__":
+    n = int(sys.argv[1]) if len(sys.argv) > 1 else 9
+    print(f"{n}-queens solutions: {solve(n)}")