From b25168178b5ae2543e91cc5e2f2780912a908698 Mon Sep 17 00:00:00 2001
From: FBumann <117816358+FBumann@users.noreply.github.com>
Date: Fri, 5 Jun 2026 22:21:27 +0200
Subject: [PATCH 1/2] =?UTF-8?q?refactor(benchmarks):=20lean=20up=20?=
 =?UTF-8?q?=E2=80=94=20trim=20docstrings/comments,=20dedupe=20plotting?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Behavior-preserving readability pass:
- plotting.py: extract _metric_label (4x) and _diverging_kwargs (3x); cut
  comments that restate code, keep the plotly-quirk ones; tighten docstrings.
- memory/bench/registry/snapshot: trim the 21-34 line module docstrings to
  essentials (keep the non-obvious why); fix stale lp_write -> to_lp refs.
- sweep.py: trim restate comments (orchestration left as-is — no test coverage).

No logic/API/CLI change; -84 lines. Verified: mypy clean, smoke 172 passed,
_tests 14 passed, walkthrough notebook renders all plots.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 benchmarks/bench.py    |  34 +++----
 benchmarks/memory.py   |  39 +++-----
 benchmarks/plotting.py | 198 ++++++++++++++++-------------------------
 benchmarks/registry.py |  23 +++--
 benchmarks/snapshot.py |  36 ++++----
 benchmarks/sweep.py    |  12 +--
 6 files changed, 129 insertions(+), 213 deletions(-)

diff --git a/benchmarks/bench.py b/benchmarks/bench.py
index 17d74bcbc..212b22165 100644
--- a/benchmarks/bench.py
+++ b/benchmarks/bench.py
@@ -1,36 +1,24 @@
 """
 Ad-hoc benchmarking of arbitrary callables on the *current* linopy tree.
 
-Where the pytest suite measures the fixed registry grid and ``sweep``
-measures across installed linopy versions, ``bench`` is for the
-interactive middle: time or memory-profile any callable — a registry
-builder, a phase verb applied to a model you built by hand, or a one-off
-lambda — get a result object back, and either inspect it as a DataFrame
-or drop it into a snapshot the existing ``plot`` / ``compare`` machinery
-already understands::
+Where the pytest suite measures the fixed registry grid and ``sweep`` measures
+across installed linopy versions, ``bench`` is the interactive middle: time or
+memory-profile any callable, get a result object, inspect it as a DataFrame or
+drop it into a snapshot the ``plot`` / ``compare`` machinery already reads::
 
     from benchmarks import bench, REGISTRY
 
     r = bench.time(REGISTRY["basic"].build, 100)
-    r                                  # rich repr in a notebook
     r.to_snapshot("a.json", spec="basic", size=100, phase="build")
-
     bench.compare({"v1": f1, "v2": f2}).to_snapshot("cmp.json")
 
-This plugs into the *output* side of the pipeline (snapshot JSON read by
-``snapshot.load_long_df``), not into ``sweep``: a sweep runs pytest inside
-per-version venvs as subprocesses, so it can only measure importable
-registry models — an in-process callable can't cross that boundary. To
-sweep a custom model across versions, promote it to ``benchmarks/models/``.
-
-**Methodology.** Timing is built on :class:`timeit.Timer`: an
-``autorange`` calibration picks the inner iteration count (so timer
-resolution doesn't dominate fast callables), then the per-iteration time
-is sampled across rounds with the suite's min-of-N convention (the
-fastest sample approximates the no-noise floor). It is *not*
-pytest-benchmark's calibrated timer, so absolute numbers are not
-interchangeable with suite snapshots — compare ``bench`` to ``bench`` and
-suite to suite.
+It feeds the output side (snapshot JSON), not ``sweep`` — a sweep runs pytest in
+per-version venvs, so only importable registry models cross that boundary;
+promote a custom model to ``benchmarks/models/`` to sweep it.
+
+Timing uses :class:`timeit.Timer` (``autorange`` picks the inner iteration count
+so resolution doesn't dominate) with the suite's min-of-N convention. It is *not*
+pytest-benchmark's timer, so compare ``bench`` to ``bench``, suite to suite.
 """
 
 from __future__ import annotations
diff --git a/benchmarks/memory.py b/benchmarks/memory.py
index 83d13897a..7f5c69a01 100644
--- a/benchmarks/memory.py
+++ b/benchmarks/memory.py
@@ -1,37 +1,22 @@
 """
 Measure and compare peak memory across the registry × phase grid.
 
-Each measurement uses ``memray.Tracker`` directly so the model construction
-(setup) lives *outside* the tracked region and the peak reflects only the
-phase work itself::
+Each measurement runs the phase work inside ``memray.Tracker`` with model
+construction *outside* it, so the peak reflects only the phase::
 
     m = spec.build(size)            # setup, not tracked
     with memray.Tracker(bin_path):
         wrapper(m)                  # tracked
-    peak = FileReader(bin_path).metadata.peak_memory
-
-This module exposes ``save(label, ...)`` and ``compare(label_a, label_b)`` as
-plain functions; user-facing invocation goes through the typer CLI::
-
-    python -m benchmarks memory save <label> [--quick] [--phase build] ...
-    python -m benchmarks memory compare <a> <b>
-
-Results land in ``.benchmarks/memory/`` as JSON keyed by full pytest-style
-test IDs (``benchmarks/test_<phase>.py::test_<phase>[<spec>-<axis>=<value>]``,
-where ``<axis>`` is ``n`` for a model or ``severity`` for a pattern) so
-cross-snapshot diffs work uniformly regardless of which phases were run.
-
-The per-phase peaks above are *marginal* — each tracker only sees allocations
-made inside its phase, so the resident model and the build transient are
-excluded (clean for cross-phase / cross-version comparison). The end-to-end
-peak a real build-then-export session hits cannot be recovered by summing or
-maxing those marginals (they share an unmeasured resident baseline and don't
-capture cross-phase accumulation), so it is *measured* directly: the
-``pipeline`` phase runs build → matrices → lp_write in a single tracker and
-reports that one high-water mark — the OOM ceiling. It re-runs those three, so
-it is opt-in (``--phase pipeline``), not in the default set — run it standalone
-to avoid duplicating the per-phase work. Memory-only (no timing twin), keyed by
-a bare ``pipeline[<spec>-<axis>=<value>]`` id.
+
+``save(label, ...)`` / ``compare(a, b)`` back the ``python -m benchmarks memory``
+CLI. Results land in ``.benchmarks/memory/`` as JSON keyed by full pytest-style
+test ids, so cross-snapshot diffs line up with the timing snapshots.
+
+The per-phase peaks are *marginal* (each tracker sees only its own phase's
+allocations), so the end-to-end OOM ceiling can't be recovered from them: the
+opt-in ``pipeline`` phase (``--phase pipeline``) instead measures
+build → matrices → to_lp under one tracker, keyed by a bare
+``pipeline[<spec>-<axis>=<value>]`` id.
 """
 
 from __future__ import annotations
diff --git a/benchmarks/plotting.py b/benchmarks/plotting.py
index 0f821d12f..c31054b85 100644
--- a/benchmarks/plotting.py
+++ b/benchmarks/plotting.py
@@ -1,23 +1,17 @@
 """
 Interactive plotly views over pytest-benchmark JSON snapshots.
 
-Three opinionated views, all returning the number of tests rendered:
-
-- :func:`plot_compare` (2 snapshots) — sorted-by-delta bar chart.
-- :func:`plot_sweep` (3+ snapshots) — heatmap of per-test ratio
-  relative to the first snapshot. Useful for cross-version sweeps.
-- :func:`plot_scaling` (1 snapshot) — cost vs the sweep dial for
-  parametrized tests, faceted by phase. Log-log for model ``size``;
-  linear for pattern ``severity`` (0–100).
-
-All three accept a ``metric`` argument selecting which pytest-benchmark
-stat drives the plot. Default is ``min`` — the fastest observed sample
-approximates the no-noise floor (GC, scheduling, cache thrash can only
-add time). ``median`` is more robust to a single weirdly-fast warmup
-round; ``mean`` and ``max`` are also accepted.
-
-plotly is imported lazily by the dispatcher so the rest of the benchmark
-suite still works without it.
+Four views, each returning the number of tests rendered:
+
+- :func:`plot_compare` (2 snapshots) — bar chart of per-test delta.
+- :func:`plot_scatter` (2+) — baseline cost vs ratio; the top-right corner is
+  the regressed one. 3+ snapshots animate across versions.
+- :func:`plot_sweep` (3+) — heatmap of per-test ratio vs the first snapshot.
+- :func:`plot_scaling` (1) — cost vs the sweep dial, faceted by phase.
+
+``metric`` selects the pytest-benchmark stat (default ``min``, the no-noise
+floor; ``median``/``mean``/``max`` also accepted). plotly is imported lazily so
+the rest of the suite works without it.
 """
 
 from __future__ import annotations
@@ -36,8 +30,21 @@
 FacetBy = Literal["phase", "spec"]
 
 
+def _metric_label(metric: Metric, unit: str) -> str:
+    """Title/axis label for ``metric`` — ``"peak"`` for memory, else the stat."""
+    return metric if unit == "s" else "peak"
+
+
+def _diverging_kwargs(midpoint: float = 0.0) -> dict:
+    """green→white→red continuous colour scale centred on ``midpoint``."""
+    return {
+        "color_continuous_scale": ["green", "white", "red"],
+        "color_continuous_midpoint": midpoint,
+    }
+
+
 def _axis_kwargs(unit: str) -> dict:
-    """Return ``update_xaxes`` kwargs for a given unit."""
+    """``update_xaxes`` kwargs for a given unit."""
     if unit == "s":
         return {"tickformat": ".2s", "ticksuffix": "s"}
     return {"ticksuffix": f" {unit}"}
@@ -45,12 +52,11 @@ def _axis_kwargs(unit: str) -> dict:
 
 def _hide_non_leftmost_yticks(fig: Figure, wrap: int) -> None:
     """
-    Hide y-axis tick labels on every facet except the leftmost column.
+    Hide y-tick labels on every facet except the leftmost column.
 
-    Plotly express lays facets out left-to-right, top-to-bottom: with
-    ``facet_col_wrap=N`` the leftmost facets are at indices 0, N, 2N…
-    Hiding tick labels on the rest keeps the row labels visible only
-    once per row instead of repeating at every subplot's left edge.
+    Plotly lays facets out left-to-right, top-to-bottom; with ``facet_col_wrap=N``
+    the leftmost are at indices 0, N, 2N… Hiding the rest shows row labels once
+    per row instead of at every subplot's left edge.
     """
     yaxes = []
     fig.for_each_yaxis(lambda y: yaxes.append(y))
@@ -61,13 +67,11 @@ def _hide_non_leftmost_yticks(fig: Figure, wrap: int) -> None:
 
 def _share_axis_labels(fig: Figure, y_label: str, x_label: str) -> None:
     """
-    Replace per-facet axis titles with one shared label per axis.
+    Replace plotly's per-facet axis titles with one shared label per axis.
 
-    Plotly express renders the x/y titles on every facet by default,
-    which is noisy when faceting wraps a 5+ subplot grid. This clears
-    them and adds two ``paper``-coordinate annotations: one on the
-    left (rotated) for ``y_label``, one on the bottom for ``x_label``.
-    Leave either blank to skip that side.
+    Per-facet titles get noisy across a 5+ subplot grid; this clears them and
+    adds two ``paper``-coordinate annotations (left/rotated for y, bottom for x).
+    Leave either label blank to skip that side.
     """
     fig.for_each_yaxis(lambda yaxis: yaxis.update(title_text=""))
     fig.for_each_xaxis(lambda xaxis: xaxis.update(title_text=""))
@@ -92,8 +96,7 @@ def _share_axis_labels(fig: Figure, y_label: str, x_label: str) -> None:
             showarrow=False,
             font={"size": 13},
         )
-    # Give the annotations room.
-    fig.update_layout(margin={"l": 90, "b": 70})
+    fig.update_layout(margin={"l": 90, "b": 70})  # room for the annotations
 
 
 def plot_compare(
@@ -103,40 +106,24 @@ def plot_compare(
     facets: FacetBy | None = None,
 ) -> tuple[Figure, int]:
     """
-    Bar chart of delta per test, in alphabetical test-id order.
-
-    ``sort`` chooses the bar *dimension*: ``absolute`` (default) plots
-    ``b - a`` in the data's native unit; ``relative`` plots the percent
-    change. Bars are not reordered by magnitude — alphabetical ids keep
-    related tests visually grouped. Use the scatter view for hunting
-    outliers.
-
-    ``facets`` splits the chart into subplots:
-
-    - ``None`` (default): one flat bar chart.
-    - ``"phase"``: facet by the test file (``test_build``,
-      ``test_to_lp``, ...). Best for "everything in this phase moved
-      together?".
-    - ``"spec"``: facet by the spec name (``basic``, ``knapsack``, ...).
-      Best for "what happened across all the basic-sized variants?".
-
-    Tests whose IDs don't match the standard ``[<spec>-n=<size>]``
-    parametrize shape (e.g. PyPSA carbon-management) land in an
-    ``other`` facet.
+    Bar chart of per-test delta, in alphabetical test-id order.
+
+    ``sort`` picks the bar dimension: ``absolute`` (default) plots ``b - a`` in
+    the native unit, ``relative`` plots percent change. Bars stay in id order
+    (related tests grouped) — use the scatter view to hunt outliers. ``facets``
+    splits into subplots by ``"phase"`` (test file) or ``"spec"`` (problem); ids
+    not matching ``[<spec>-n=<size>]`` land in an ``other`` facet.
     """
     import sys
 
     import plotly.express as px
 
     df_long, unit = load_long_df(snapshots[:2], metric)
-    metric_label = metric if unit == "s" else "peak"
+    metric_label = _metric_label(metric, unit)
 
     labels = df_long["snapshot"].drop_duplicates().tolist()
     a_label, b_label = labels[0], labels[1]
 
-    # Pivot to wide: one row per test, baseline + candidate as columns,
-    # phase / spec / size carried through. Then compute deltas
-    # vectorised — no per-row dict construction.
     wide = (
         df_long.pivot(
             index=["test_id", "phase", "spec", "size", "axis"],
@@ -180,9 +167,7 @@ def plot_compare(
             f"{len(only_b)} only in {b_label}</sub>"
         )
 
-    # Inside a facet the y-axis labels whatever *varies* — drop the
-    # facetted dimension from the label, keep the rest. Flat ⇒ the full
-    # test_id so each bar is self-identifying.
+    # In a facet the y-axis labels whatever varies; flat ⇒ the full test_id.
     facet_kwargs: dict = {}
     if facets is None:
         y_col = "test_id"
@@ -204,8 +189,7 @@ def plot_compare(
         y=y_col,
         orientation="h",
         color=x_col,
-        color_continuous_scale=["green", "white", "red"],
-        color_continuous_midpoint=0,
+        **_diverging_kwargs(),
         title=title,
         labels={x_col: x_label, y_col: ""},
         text_auto=text_fmt,
@@ -219,23 +203,17 @@ def plot_compare(
         **facet_kwargs,
     )
     if sort == "absolute":
-        # SI-prefixed time on the x-axis (e.g. 24 ms, 2.4 ms, 240 µs) for
-        # timing snapshots; plain MiB for memory.
         fig.update_xaxes(**_axis_kwargs(unit))
-    # Render the value text outside the bar (default is inside) so the
-    # number stays readable even when a bar is very short.
     fig.update_traces(textposition="outside", cliponaxis=False)
     if facets is not None:
-        # Each facet keeps its own y category list (no shared rows full
-        # of empty bars), but we hide tick labels on non-leftmost facets
-        # within each row so labels appear once per row.
+        # Per-facet y categories (no shared empty rows); hide non-leftmost tick
+        # labels so each row's labels appear once.
         fig.update_yaxes(matches=None)
         wrap = facet_kwargs["facet_col_wrap"]
         _hide_non_leftmost_yticks(fig, wrap=wrap)
         _share_axis_labels(fig, y_label="test", x_label=x_label)
-        # Keep plotly's default equal-share row layout: shorter facets show
-        # empty space below their bars, but the header annotations stay put
-        # (a manual ``domain`` override would scramble them).
+        # Keep plotly's equal-share rows: shorter facets show empty space, but a
+        # manual ``domain`` override would scramble the header annotations.
         rows_per_facet = df.groupby(facets)[y_col].nunique().max()
         n_wrap_rows = (df[facets].nunique() + wrap - 1) // wrap
         height = max(500, int(n_wrap_rows * rows_per_facet * 24) + 100)
@@ -252,24 +230,14 @@ def plot_scatter(
     facets: FacetBy | None = None,
 ) -> tuple[Figure, int]:
     """
-    Two-axis scatter — baseline cost on log-x, ratio on y.
-
-    Designed as the single best exploratory plot for regression hunting
-    across tests of wildly different magnitudes: a point lights up as
-    "fix this" only if it sits in the top-right corner — slow tests
-    that got slower. Top-left (big ratio, tiny absolute) is a cheap
-    test with noisy ratio swings — not a real change. Bottom-right (big
-    absolute, tiny ratio) is already-slow-but-unchanged. The combined
-    position resolves the tension that pure relative or pure absolute
-    sort each blind-spot.
-
-    The first snapshot is the baseline. With 2 snapshots, a static
-    scatter is drawn; with 3+, every subsequent snapshot becomes an
-    ``animation_frame`` — use the slider / play button to step through
-    versions and watch points drift across releases.
-
-    A horizontal reference at ``ratio = 1`` makes "no change" trivial
-    to see; the colour encodes absolute Δ as a third channel.
+    Baseline cost (log-x) vs candidate/baseline ratio (y) — the exploratory
+    regression-hunting view.
+
+    A point is "fix this" only in the top-right (slow *and* slower); top-left is
+    a cheap test with a noisy ratio, bottom-right is already-slow-but-unchanged.
+    The first snapshot is the baseline; with 3+, the rest become an
+    ``animation_frame``. A dashed line at ``ratio = 1`` marks no change; colour
+    encodes absolute Δ.
     """
     import numpy as np
     import plotly.express as px
@@ -278,16 +246,13 @@ def plot_scatter(
         raise ValueError("scatter needs at least 2 snapshots (baseline + 1)")
 
     df_long, unit = load_long_df(snapshots, metric)
-    metric_label = metric if unit == "s" else "peak"
+    metric_label = _metric_label(metric, unit)
 
     labels = df_long["snapshot"].drop_duplicates().tolist()
     baseline_label = labels[0]
 
-    # Attach the baseline value to every row via a per-test groupby (each
-    # test's baseline = its value on the first snapshot). Tests with no
-    # baseline row (only in non-baseline snapshots) are dropped. Tests
-    # with non-positive baseline are dropped because the ratio is
-    # undefined for them.
+    # Baseline = each test's value on the first snapshot; tests absent there or
+    # with non-positive baseline (undefined ratio) are dropped.
     baseline_vals = df_long.loc[
         df_long["snapshot"] == baseline_label, ["test_id", "value"]
     ].rename(columns={"value": "baseline_time"})
@@ -304,21 +269,17 @@ def plot_scatter(
     df["delta_abs"] = df["candidate_time"] - df["baseline_time"]
     df["delta_pct"] = df["delta_abs"] / df["baseline_time"] * 100.0
     df = df.rename(columns={"test_id": "test"})
-    # Fix the axis ranges so the animation doesn't jitter; pad by a small
-    # margin so points on the edges aren't clipped.
+    # Fixed ranges so the animation doesn't jitter; pad to avoid edge clipping.
     x_lo, x_hi = df["baseline_time"].min(), df["baseline_time"].max()
-    # y-range uses min/max but is centered symmetrically around 1.0 (the
-    # "no change" line), so regressions above and improvements below are
-    # equally readable. Asymmetric data still resolves — the larger side
-    # just dictates how wide the symmetric window is.
+    # y-range centred symmetrically on 1.0 so regressions and improvements read
+    # equally; the larger side sets the window width.
     y_lo, y_hi = df["ratio"].min(), df["ratio"].max()
     max_dist = max(abs(1.0 - y_lo), abs(y_hi - 1.0), 0.05)
     pad_y = max(0.05, max_dist * 0.05)
     y_range = [1.0 - max_dist - pad_y, 1.0 + max_dist + pad_y]
 
-    # Clip the colour scale to the 95th-percentile absolute Δ so a single
-    # huge regression doesn't wash everything else to white. Outliers
-    # saturate at the bound, the rest stays readable.
+    # Clip the colour scale to the p95 absolute Δ so one huge regression doesn't
+    # wash the rest to white; outliers saturate at the bound.
     clip = float(np.percentile(df["delta_abs"].abs(), 95)) if len(df) > 0 else 0.0
     if clip == 0.0:
         max_abs = float(df["delta_abs"].abs().max())
@@ -338,8 +299,7 @@ def plot_scatter(
         x="baseline_time",
         y="ratio",
         color="delta_abs",
-        color_continuous_scale=["green", "white", "red"],
-        color_continuous_midpoint=0,
+        **_diverging_kwargs(),
         range_color=[-clip, clip],
         log_x=True,
         range_x=[x_lo * 0.5, x_hi * 2],
@@ -389,13 +349,11 @@ def plot_sweep(
     import plotly.express as px
 
     df_long, unit = load_long_df(snapshots, metric)
-    metric_label = metric if unit == "s" else "peak"
+    metric_label = _metric_label(metric, unit)
     versions = df_long["snapshot"].drop_duplicates().tolist()
     baseline_label = versions[0]
 
-    # Pivot absolutes (rows=tests, cols=versions), then drop tests with
-    # no baseline reading and divide every column by the baseline column
-    # to get ratios in one shot.
+    # Pivot to absolutes, drop tests missing the baseline, divide by it for ratios.
     abs_df = df_long.pivot(index="test_id", columns="snapshot", values="value").reindex(
         columns=versions
     )
@@ -408,14 +366,13 @@ def plot_sweep(
 
     fig = px.imshow(
         df,
-        color_continuous_scale=["green", "white", "red"],
-        color_continuous_midpoint=1.0,
+        **_diverging_kwargs(1.0),
         aspect="auto",
         title=f"{metric_label} ratio relative to baseline ({versions[0]})",
         labels={"x": "version", "y": "test", "color": "ratio"},
         text_auto=".2f",
     )
-    # Inject absolute values as customdata so hover shows both.
+    # Absolute values as customdata so hover shows both ratio and value.
     fig.update_traces(
         customdata=abs_df.values,
         hovertemplate=(
@@ -430,8 +387,8 @@ def plot_sweep(
     return fig, len(df)
 
 
-# How each sweep axis renders: (x-axis label, log-scaled?). Size is
-# multiplicative → log-log; severity is a 0–100 % dial → linear.
+# Per sweep axis: (x label, log-scaled?). Size is multiplicative → log; severity
+# is a 0–100% dial → linear.
 _AXIS_DISPLAY: dict[str, tuple[str, bool]] = {
     "n": ("n", True),
     "severity": ("severity (%)", False),
@@ -447,17 +404,14 @@ def plot_scaling(
     """
     Cost vs the sweep dial for parametrized tests, faceted by phase.
 
-    Handles both axes the registry sweeps: model ``size`` (``axis="n"``) and
-    pattern ``severity``. Models scale multiplicatively, so a model-only
-    snapshot is drawn log-log; a severity sweep is linear (it starts at 0 and
-    is a 0–100 percentage, so a log x-axis would be meaningless). A mixed
-    snapshot falls back to linear x. The x-axis label is taken from the data's
-    ``axis`` column rather than hard-coded.
+    Model ``size`` (``axis="n"``) scales multiplicatively → log-log; pattern
+    ``severity`` is a 0–100 dial → linear; a mixed snapshot falls back to linear
+    x. The x-axis label comes from the data's ``axis`` column.
     """
     import plotly.express as px
 
     df_long, unit = load_long_df(snapshots[:1], metric)
-    metric_label = metric if unit == "s" else "peak"
+    metric_label = _metric_label(metric, unit)
     df = (
         df_long.dropna(subset=["size"])
         .rename(columns={"value": metric})
@@ -471,7 +425,7 @@ def plot_scaling(
     axes = sorted(df["axis"].unique())
     axis = axes[0] if len(axes) == 1 else "sweep value"
     x_label, log_axis = _AXIS_DISPLAY.get(axis, (axis, False))
-    # Log only makes sense for multiplicative size sweeps that stay > 0.
+    # Log only suits multiplicative size sweeps that stay > 0.
     log_x = log_axis and bool((df["size"] > 0).all())
 
     metric_word = {"min": "minimum", "max": "maximum"}.get(metric, metric)
diff --git a/benchmarks/registry.py b/benchmarks/registry.py
index bee62a85b..5c3a78025 100644
--- a/benchmarks/registry.py
+++ b/benchmarks/registry.py
@@ -1,23 +1,20 @@
 """
 Reusable registry of benchmark models.
 
-A :class:`ModelSpec` captures everything needed to drive a model through the
-benchmark suite *and* to use it from any other test or script:
+A :class:`ModelSpec` captures everything to drive a model through the suite and
+to reuse it elsewhere:
 
-- ``build(size) -> linopy.Model``  the actual builder
-- ``sizes``                        canonical sizes the model has been tuned for
-- ``features``                     what kinds of variables / constraints it uses
-- ``phases``                       which benchmark phases apply (lp_write, to_highspy, ...)
-- ``quick_threshold``              max size to keep under ``pytest --quick``
-- ``requires``                     extra modules to ``pytest.importorskip``
+- ``build(size) -> linopy.Model``  the builder
+- ``sizes``                        canonical tuned sizes
+- ``features``                     variable / constraint kinds it uses
+- ``phases``                       applicable phases (to_lp, to_highspy, …)
+- ``quick_threshold``              max size under ``pytest --quick``
+- ``requires``                     modules to ``pytest.importorskip``
 
-Pattern for downstream use::
+::
 
-    from benchmarks import REGISTRY
+    from benchmarks import REGISTRY, filter_by, QUADRATIC
     model = REGISTRY["basic"].build(100)
-
-    # Or pick a subset by feature/phase:
-    from benchmarks import filter_by, QUADRATIC
     qp_specs = filter_by(has_feature=QUADRATIC)
 """
 
diff --git a/benchmarks/snapshot.py b/benchmarks/snapshot.py
index 8d274a8f3..07b231e06 100644
--- a/benchmarks/snapshot.py
+++ b/benchmarks/snapshot.py
@@ -1,24 +1,20 @@
 """
-The benchmark snapshot contract — one owner for the on-disk JSON shapes,
-the test-id grammar, and the long-DataFrame loader.
-
-Dependency-free within the package (stdlib plus a lazily-imported
-pandas), so every writer (pytest-benchmark via file, :func:`memory.save`,
-:mod:`benchmarks.bench`) and every reader (:mod:`benchmarks.plotting`,
-:func:`memory.compare`) can sit on it without import cycles.
-
-Two snapshot shapes, auto-detected on load:
-
-- **timing** — ``{"benchmarks": [{"fullname": <id>, "stats": {"min":…,
-  "median":…, "mean":…, "max":…}}]}`` → value in **seconds** (the shape
-  pytest-benchmark writes).
-- **memory** — ``{"label": <str>, "peak_mib": {<id>: <float>}}`` → value
-  in **MiB**.
-
-Test ids follow ``…[<spec>-<axis>=<value>]`` where ``<axis>`` is the sweep
-dial — ``n`` for a model (size) or ``severity`` for a pattern — and ``<value>``
-is the integer swept. :func:`parse_test_id` splits one into
-``(phase, spec, value, axis)`` and :func:`synth_test_id` builds one.
+The benchmark snapshot contract — one owner for the on-disk JSON shapes, the
+test-id grammar, and the long-DataFrame loader.
+
+Dependency-free (stdlib + lazy pandas) so every writer (pytest-benchmark,
+:func:`memory.save`, :mod:`benchmarks.bench`) and reader
+(:mod:`benchmarks.plotting`, :func:`memory.compare`) shares it without cycles.
+
+Two shapes, auto-detected on load:
+
+- **timing** — ``{"benchmarks": [{"fullname": <id>, "stats": {…}}]}`` → seconds
+  (what pytest-benchmark writes).
+- **memory** — ``{"label": <str>, "peak_mib": {<id>: <float>}}`` → MiB.
+
+Test ids are ``…[<spec>-<axis>=<value>]`` where ``<axis>`` is the sweep dial
+(``n`` for size, ``severity`` for a pattern). :func:`parse_test_id` splits one;
+:func:`synth_test_id` builds one.
 """
 
 from __future__ import annotations
diff --git a/benchmarks/sweep.py b/benchmarks/sweep.py
index 58d4c4675..7015604f0 100644
--- a/benchmarks/sweep.py
+++ b/benchmarks/sweep.py
@@ -163,10 +163,8 @@ def _provision_venvs(
             vpy = _venv_python(venv)
             spec = _linopy_install_spec(version)
 
-            # Single install pass: pinned infra from pyproject + linopy.
-            # Direct pins in [benchmarks] are sufficient for sweep
-            # reproducibility — uv resolves the same input deterministically
-            # into each per-version venv.
+            # One install pass: pinned infra + linopy; uv resolves the pinned
+            # inputs deterministically into each per-version venv.
             install_args = [
                 "uv",
                 "pip",
@@ -183,8 +181,7 @@ def _provision_venvs(
                 yield _ProvisionedVenv(version, None, None, None, "install")
                 continue
 
-            # Isolated import root (see the docstring): a filtered copy of
-            # ``benchmarks/``, skipping sweep-irrelevant heavy artifacts.
+            # Isolated import root: a filtered copy of ``benchmarks/`` (docstring).
             import_dir = Path(tmp) / "iso"
             import_dir.mkdir()
             shutil.copytree(
@@ -193,8 +190,7 @@ def _provision_venvs(
                 ignore=shutil.ignore_patterns("__pycache__", "*.ipynb", ".DS_Store"),
             )
 
-            # Drop PYTHONPATH so the repo's ``linopy/`` can't shadow the
-            # venv's installed copy (see the docstring).
+            # Drop PYTHONPATH so the repo's ``linopy/`` can't shadow the venv copy.
             env = os.environ.copy()
             env.pop("PYTHONPATH", None)
 

From 5d1cac7890d12e19371eee2ae78b8c427e5c5e6e Mon Sep 17 00:00:00 2001
From: FBumann <117816358+FBumann@users.noreply.github.com>
Date: Fri, 5 Jun 2026 22:29:25 +0200
Subject: [PATCH 2/2] ci(codspeed): run memory before simulation in the
 combined run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mode: memory,simulation — memory (fast, always-on) is measured first, so its
baseline lands even if the slow cachegrind pass is interrupted.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/codspeed.yml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/codspeed.yml b/.github/workflows/codspeed.yml
index 75757d96c..201a657ad 100644
--- a/.github/workflows/codspeed.yml
+++ b/.github/workflows/codspeed.yml
@@ -1,10 +1,11 @@
-name: CodSpeed (simulation + memory)
+name: CodSpeed (memory + simulation)
 
-# CPU instruction counts (cachegrind) AND heap allocations in ONE upload.
+# Heap allocations AND CPU instruction counts (cachegrind) in ONE upload.
 # They must share a run: CodSpeed records one run per (commit, environment),
 # and a second upload to the same environment overwrites the first — the other
 # instrument's benchmarks then show as "skipped". So both are measured serially
-# via ``mode: simulation,memory`` (CodSpeedHQ/action >= 4.12).
+# via ``mode: memory,simulation`` — memory first so the fast, always-on signal
+# lands even if the slow cachegrind pass is interrupted (CodSpeedHQ/action >= 4.12).
 #
 # Cadence: master push (establish/update both baselines) + manual dispatch +
 # opt-in per-PR via the ``trigger:benchmark`` label — which keeps the PR context
@@ -25,7 +26,7 @@ concurrency:
 
 jobs:
   codspeed:
-    name: CodSpeed simulation + memory
+    name: CodSpeed memory + simulation
     # Always on master push / dispatch; on PRs only when explicitly labelled.
     if: >-
       ${{ github.event_name != 'pull_request' ||
@@ -52,10 +53,10 @@ jobs:
         python -m pip install uv
         uv pip install --system -e ".[dev,benchmarks]"
 
-    - name: Run benchmarks under CodSpeed (simulation + memory)
+    - name: Run benchmarks under CodSpeed (memory + simulation)
       uses: CodSpeedHQ/action@v4
       with:
-        mode: simulation,memory
+        mode: memory,simulation
         run: |
           pytest benchmarks/ --quick --codspeed