physverify 0.1.0__py3-none-any.whl

physverify/stochastic/ising.py

@@ -0,0 +1,170 @@
+"""Seeded-bug benchmark for Ising samplers (docs/plan_ising.md, section 5).
+
+Each bug lives in one algorithm of physverify.stochastic.sampler.IsingSampler.
+The predicted checks and the expected symptom were written down before any
+bug was run. Unlike the deterministic benchmark, the test suite does not force
+the predictions to come true: results/ising_matrix.md records predicted and
+observed side by side, and wrong predictions are reported as such.
+
+The equivalent mutant `reject_zero_de` is a negative control: it changes the
+dynamics but keeps the Boltzmann distribution, so the distribution checks
+should not flag it and the dynamics checks should.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import checks as K
+from .sampler import IsingSampler
+
+NAME = "ising"
+VARIANTS = ("metropolis", "heatbath", "checkerboard", "wolff")
+
+
+@dataclass(frozen=True)
+class IsingBug:
+    algorithm: str
+    description: str
+    predicted: frozenset
+    symptom: str
+    negative_control: bool = False
+
+
+def _f(*names):
+    return frozenset(names)
+
+
+BUGS = {
+    "j_sign_flipped": IsingBug(
+        "metropolis", "coupling J = -1 (antiferromagnet) in the dynamics and the measurement",
+        _f("bookkeeping", "scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "on an even lattice the energy distribution is unchanged (sublattice flip maps AF to FM), "
+        "but |m| collapses and bond correlations change sign",
+    ),
+    "delta_e_missing_factor_2": IsingBug(
+        "metropolis", "energy change of a flip computed as s * phi instead of 2 s * phi",
+        _f("bookkeeping", "scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "samples at twice the temperature; the tracked energy drifts from the lattice",
+    ),
+    "exp_de_times_t": IsingBug(
+        "metropolis", "acceptance exp(-dE * T) instead of exp(-dE / T)",
+        _f("scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "samples at temperature 1 / T^2",
+    ),
+    "missing_wrap_x": IsingBug(
+        "metropolis", "no periodic wrap in the x direction, in the dynamics and the measurement",
+        _f("bookkeeping", "scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "a cylinder instead of a torus: wrap bonds uncorrelated, energies shifted",
+    ),
+    "same_neighbour_twice": IsingBug(
+        "metropolis", "the neighbour below is used twice and the one above not at all (dynamics only)",
+        _f("bookkeeping", "scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "wrong local fields: wrong distribution, tracked energy drifts",
+    ),
+    "energy_double_counted": IsingBug(
+        "metropolis", "energy measurement counts every bond twice (dynamics right)",
+        _f("bookkeeping", "exact_distribution", "moments"),
+        "reported energies doubled; the lattice evolution is correct",
+    ),
+    "m_normalised_by_L": IsingBug(
+        "metropolis", "magnetization per spin divides by L instead of L^2 (reporting only)",
+        _f("exact_distribution", "moments"),
+        "reported m is L times too large; nothing else changes",
+    ),
+    "sweep_skips_last_row": IsingBug(
+        "metropolis", "random sites drawn from the first L - 1 rows only",
+        _f("exact_distribution", "moments", "symmetry"),
+        "the last row never changes; replay with the same site draws agrees",
+    ),
+    "same_random_number": IsingBug(
+        "metropolis", "one uniform used both to choose the site (int(u N)) and to accept",
+        _f("scripted_rng", "exact_distribution", "moments", "symmetry"),
+        "site-dependent acceptance: sites with high index rarely flip uphill; detailed balance broken",
+    ),
+    "seed_ignored": IsingBug(
+        "metropolis", "the generator is always seeded with the same constant",
+        _f("reproducibility"),
+        "every seed gives the same run; each run is still a correct sample",
+    ),
+    "acceptance_table_off_by_one": IsingBug(
+        "metropolis", "acceptance looked up one energy class too high (exp(-(dE + 4) / T))",
+        _f("scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "uphill moves accepted too rarely; the lattice is too ordered",
+    ),
+    "incremental_energy_not_updated": IsingBug(
+        "metropolis", "the tracked energy is not updated after a flip",
+        _f("bookkeeping"),
+        "only the tracked energy is wrong; reported (measured) values are right",
+    ),
+    "no_burn_in": IsingBug(
+        "metropolis", "no burn-in: measurement starts from the initial lattice",
+        _f("equilibration"),
+        "hot and cold starts disagree over the first sweeps; long averages are barely biased",
+    ),
+    "naive_error_bars": IsingBug(
+        "metropolis", "error bar of the mean computed as std / sqrt(n), ignoring autocorrelation",
+        _f("error_bars"),
+        "reported error bars too small by about sqrt(2 tau)",
+    ),
+    "field_sign_wrong": IsingBug(
+        "metropolis", "the field enters the dynamics with the wrong sign (measurement right)",
+        _f("bookkeeping", "scripted_rng", "moments", "acceptance"),
+        "invisible at h = 0; in a field m has the wrong sign",
+    ),
+    "spins_zero_one": IsingBug(
+        "metropolis", "spins stored as {0, 1} and used in the +-1 formulas",
+        _f("bookkeeping", "scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "a different model: energies and magnetizations off the allowed levels",
+    ),
+    "reject_zero_de": IsingBug(
+        "metropolis", "moves with dE = 0 are rejected instead of accepted (equivalent mutant)",
+        _f("scripted_rng", "acceptance"),
+        "same stationary distribution, different dynamics: only the dynamics checks should see it",
+        negative_control=True,
+    ),
+    "heatbath_missing_2": IsingBug(
+        "heatbath", "heat-bath probability 1 / (1 + exp(-phi / T)) instead of exp(-2 phi / T)",
+        _f("scripted_rng", "exact_distribution", "moments", "acceptance", "symmetry"),
+        "samples at twice the temperature",
+    ),
+    "synchronous_update": IsingBug(
+        "checkerboard", "all sites updated at once from the old lattice instead of two sublattices",
+        _f("bookkeeping", "exact_distribution", "moments"),
+        "neighbours flip together; wrong distribution, tracked energy wrong",
+    ),
+    "checkerboard_wrong_parity": IsingBug(
+        "checkerboard", "both half-sweeps update the even sublattice",
+        _f("exact_distribution", "moments", "symmetry"),
+        "the odd sublattice never changes",
+    ),
+    "wolff_probability": IsingBug(
+        "wolff", "cluster bond probability 1 - exp(-J / T) instead of 1 - exp(-2 J / T)",
+        _f("exact_distribution", "moments"),
+        "clusters too small; samples a different distribution",
+    ),
+}
+
+
+def variant_checks(sampler) -> list:
+    """The checks that apply to one sampler, with run lengths suited to its speed."""
+    if sampler.algorithm == "wolff":  # one cluster update per 'sweep', looped in Python per chain
+        return K.ising_checks(
+            sampler,
+            exact_distribution={"n_chains": 128, "n_sweeps": 600},
+            moments={"n_chains": 128, "n_sweeps": 800},
+            symmetry={"n_chains": 128},
+            equilibration={"n_chains": 256},
+            error_bars={"n_chains": 64, "n_sweeps": 600},
+        )
+    return K.ising_checks(sampler)
+
+
+def checks(bugs=frozenset(), algorithm=None):
+    """Checks for the sampler with the given bugs (all in one algorithm), or a bug-free variant."""
+    bugs = frozenset(bugs)
+    algorithms = {BUGS[b].algorithm for b in bugs}
+    if len(algorithms) > 1:
+        raise ValueError("bugs from different algorithms")
+    algorithm = algorithms.pop() if algorithms else (algorithm or "metropolis")
+    return variant_checks(IsingSampler(algorithm, bugs))

physverify/stochastic/matrix.py

@@ -0,0 +1,151 @@
+"""Run every Ising check on every seeded bug; write the table, the prediction scorecard and the messages.
+
+    python -m physverify.stochastic.matrix results/ising_matrix.md
+
+A check "flags" a bug when it returns FAIL or ERROR. INCONCLUSIVE is shown as
+such and is neither a catch nor a pass. Takes several minutes (plain NumPy).
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+from ..checks import ERROR, FAIL, INCONCLUSIVE, run_check
+from . import ising
+from .checks import FAMILIES
+
+SHORT = {"PASS": "ok", "EXACT": "ok", FAIL: "FAIL", ERROR: "ERROR", INCONCLUSIVE: "inconcl."}
+
+
+def run_row(bug=None, algorithm=None):
+    bugs = frozenset([bug]) if bug else frozenset()
+    out = []
+    for check in ising.checks(bugs, algorithm):
+        start = time.perf_counter()
+        result = run_check(check)
+        out.append((check, result, time.perf_counter() - start))
+    return out
+
+
+def run_all(progress=False):
+    rows = []
+    for alg in ising.VARIANTS:
+        rows.append((alg, None, run_row(None, alg)))
+        if progress:
+            print(f"baseline {alg} done", file=sys.stderr)
+    for bug, info in ising.BUGS.items():
+        rows.append((info.algorithm, bug, run_row(bug)))
+        if progress:
+            print(f"{bug} done", file=sys.stderr)
+    return rows
+
+
+def flagged(results):
+    return {c.family for c, r, _ in results if r.status in (FAIL, ERROR)}
+
+
+def to_markdown(rows) -> str:
+    head = "| Algorithm | Bug | " + " | ".join(FAMILIES) + " |\n|---|---|" + "---|" * len(FAMILIES) + "\n"
+    lines = []
+    for alg, bug, results in rows:
+        by_family = {c.family: r for c, r, _ in results}
+        predicted = ising.BUGS[bug].predicted if bug else frozenset()
+        cells = []
+        for fam in FAMILIES:
+            r = by_family.get(fam)
+            cell = SHORT.get(r.status, r.status) if r else "n/a"
+            if bug and fam in predicted:
+                cell += " (p)"
+            cells.append(cell)
+        lines.append(f"| {alg} | {bug or '(none)'} | " + " | ".join(cells) + " |")
+    bug_rows = [r for r in rows if r[1]]
+    controls = [r for r in bug_rows if ising.BUGS[r[1]].negative_control]
+    real = [r for r in bug_rows if not ising.BUGS[r[1]].negative_control]
+    caught = [r for r in real if flagged(r[2])]
+    baseline_alarms = [r for r in rows if not r[1] and flagged(r[2])]
+    baseline_inconclusive = sum(1 for r in rows if not r[1] for _, res, _ in r[2] if res.status == INCONCLUSIVE)
+    hit = miss = surprise = 0
+    for _, bug, results in bug_rows:
+        p, f = ising.BUGS[bug].predicted, flagged(results)
+        hit += len(p & f)
+        miss += len(p - f)
+        surprise += len(f - p)
+    summary = [
+        "",
+        "(p) marks a check predicted, before running, to flag the bug. ok = PASS or EXACT; inconcl. = INCONCLUSIVE; "
+        "n/a = the check does not apply to the algorithm (scripted_rng and acceptance need single-site updates).",
+        "",
+        f"Seeded bugs: {len(real)}, plus {len(controls)} equivalent mutant (negative control). "
+        f"Flagged by at least one check: {len(caught)} of {len(real)}"
+        + (" (missed: " + ", ".join(r[1] for r in real if not flagged(r[2])) + ")" if len(caught) < len(real) else "")
+        + ".",
+        f"Bug-free baselines with a FAIL: {len(baseline_alarms)} of {len(rows) - len(bug_rows)}; "
+        f"statistical INCONCLUSIVE on baselines: {baseline_inconclusive}.",
+        f"Predictions: {hit} predicted detections happened, {miss} predicted detections did not, "
+        f"{surprise} detections were not predicted (details in the scorecard).",
+        "Each statistical check has a false-alarm rate of at most 0.001 (Bonferroni within the check); "
+        "with 6 statistical checks per sampler the rate per sampler is at most 0.006.",
+    ]
+    return head + "\n".join(lines) + "\n" + "\n".join(summary) + "\n"
+
+
+def scorecard(rows) -> str:
+    out = [
+        "# Ising seeded bugs: predictions against outcomes",
+        "",
+        "Predictions and symptoms were committed (src/physverify/stochastic/ising.py, commit 0297ffe) before any",
+        "bug was run, and have not been changed since.",
+        "",
+        "One check was changed after a result was seen. `scripted_rng` and `acceptance` first ran only in a field",
+        "(h = 0.25), where no single flip has dE = 0, so the equivalent mutant `reject_zero_de` was invisible to",
+        "both: a unit test showed this before the first full matrix run. Both checks now also run at h = 0. Their",
+        "detection of `reject_zero_de` below is therefore not a blind result.",
+        "",
+    ]
+    for alg, bug, results in rows:
+        if not bug:
+            continue
+        info = ising.BUGS[bug]
+        f = flagged(results)
+        out += [
+            f"## {bug} ({alg}){' — negative control' if info.negative_control else ''}",
+            "",
+            f"- Change: {info.description}",
+            f"- Expected symptom: {info.symptom}",
+            f"- Predicted: {', '.join(sorted(info.predicted)) or 'nothing'}",
+            f"- Flagged: {', '.join(sorted(f)) or 'nothing'}",
+            f"- Predicted but not flagged: {', '.join(sorted(info.predicted - f)) or '-'}",
+            f"- Flagged but not predicted: {', '.join(sorted(f - info.predicted)) or '-'}",
+            "",
+        ]
+    return "\n".join(out)
+
+
+def details(rows) -> str:
+    out = []
+    for alg, bug, results in rows:
+        out.append(f"### {alg} / {bug or '(baseline)'}")
+        for c, r, secs in results:
+            out.append(f"- {c.family} [{c.label}] {r.status} ({secs:.1f} s): {r.message}")
+        out.append("")
+    return "\n".join(out)
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    rows = run_all(progress=True)
+    text = to_markdown(rows)
+    print(text)
+    if argv:
+        path = Path(argv[0])
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        path.with_name("ising_scorecard.md").write_text(scorecard(rows), encoding="utf-8")
+        path.with_name("ising_details.md").write_text(details(rows), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

physverify/stochastic/reference.py

@@ -0,0 +1,67 @@
+"""A trusted reference: one Ising chain in plain Python, written for clarity, not speed.
+
+Used to replay a recorded random-number stream (the `scripted_rng` check) and as
+the independent energy and magnetization functions for `bookkeeping`. The
+vectorised sampler in `physverify.stochastic.sampler` must reproduce it exactly
+when given the same random numbers; a test checks that.
+
+Random-number protocol for single-site updates (Metropolis and heat bath): per
+attempt, one integer site index k in [0, L*L) (row-major: i = k // L, j = k % L),
+then one uniform u in [0, 1).
+"""
+
+from __future__ import annotations
+
+import math
+
+J = 1.0
+
+
+def neighbour_sum(spins, i, j):
+    L = len(spins)
+    return spins[(i + 1) % L][j] + spins[(i - 1) % L][j] + spins[i][(j + 1) % L] + spins[i][(j - 1) % L]
+
+
+def energy(spins, h=0.0):
+    """H = -J sum over right and down bonds of s_i s_j - h sum s_i."""
+    L = len(spins)
+    bonds = 0.0
+    for i in range(L):
+        for j in range(L):
+            bonds += spins[i][j] * (spins[i][(j + 1) % L] + spins[(i + 1) % L][j])
+    return -J * bonds - h * magnetization(spins)
+
+
+def magnetization(spins):
+    return float(sum(sum(row) for row in spins))
+
+
+def metropolis_attempt(spins, k, u, T, h=0.0):
+    """One Metropolis attempt at site k with uniform u; flips in place. Returns True if accepted."""
+    L = len(spins)
+    i, j = divmod(int(k), L)
+    s = spins[i][j]
+    dE = 2.0 * s * (J * neighbour_sum(spins, i, j) + h)
+    if dE <= 0.0 or u < math.exp(-dE / T):
+        spins[i][j] = -s
+        return True
+    return False
+
+
+def heat_bath_attempt(spins, k, u, T, h=0.0):
+    """One heat-bath update at site k: the spin is set up with probability 1 / (1 + exp(-2 phi / T))."""
+    L = len(spins)
+    i, j = divmod(int(k), L)
+    phi = J * neighbour_sum(spins, i, j) + h
+    p_up = 1.0 / (1.0 + math.exp(-2.0 * phi / T))
+    spins[i][j] = 1 if u < p_up else -1
+    return True
+
+
+def replay(spins, draws, T, h, algorithm="metropolis"):
+    """Apply a list of (site, u) draws in order; returns the final lattice (a copy)."""
+    spins = [list(row) for row in spins]
+    attempt = metropolis_attempt if algorithm == "metropolis" else heat_bath_attempt
+    for k, u in draws:
+        attempt(spins, k, u, T, h)
+    return spins

physverify/stochastic/sampler.py

@@ -0,0 +1,253 @@
+"""The Ising sampler interface, and a vectorised sampler with switchable seeded bugs.
+
+Interface a code under test provides (see docs/ising.md):
+
+black box
+    sample(L, T, h, n_sweeps, seed, n_chains=1, start="hot") -> (e, m)
+        per-spin energy H / N and magnetization M / N after every sweep, arrays of
+        shape (n_chains, n_sweeps), after the code's own burn-in
+    error_bar(series) -> float
+        the code's error bar for the mean of one chain's series (optional)
+
+white box (optional; checks that need a method the code lacks are skipped)
+    init(L, n_chains, start, rng) -> state      state.spins (n_chains, L, L), state.E, state.M
+    sweep(state, T, h, rng)                      one sweep, updating state.E and state.M incrementally
+    step(state, sites, u, T, h)                  one single-site update per chain at the given
+                                                 sites (flat index) with the given uniforms
+    measure(state, h) -> (E, M)                  totals computed from the lattice
+
+`rng` follows numpy's Generator: the code may call only rng.integers(low, high,
+size) and rng.random(size). For single-site algorithms the expected order is one
+site array, then one uniform array, per attempt (physverify.stochastic.reference).
+
+Many chains are run at once (arrays over the first axis), which makes the
+statistical checks affordable in plain NumPy. The chains are independent.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .stats import blocked_error
+
+ALGORITHMS = ("metropolis", "heatbath", "checkerboard", "wolff")
+
+
+class State:
+    def __init__(self, spins, E, M):
+        self.spins, self.E, self.M = spins, E, M
+
+
+class IsingSampler:
+    """Metropolis (random site), heat bath (random site), checkerboard Metropolis or Wolff.
+
+    `bugs` switches on seeded bugs by name (see physverify.stochastic.ising.BUGS).
+    With no bugs this sampler reproduces physverify.stochastic.reference exactly.
+    """
+
+    def __init__(self, algorithm="metropolis", bugs=frozenset(), burn_in=100):
+        if algorithm not in ALGORITHMS:
+            raise ValueError(algorithm)
+        self.algorithm = algorithm
+        self.bugs = frozenset(bugs)
+        self.burn_in = 0 if "no_burn_in" in self.bugs else burn_in
+        self.J = -1.0 if "j_sign_flipped" in self.bugs else 1.0
+        self.zero_one = "spins_zero_one" in self.bugs
+
+    # --- representation ---
+
+    def _up(self):
+        return 1.0
+
+    def _down(self):
+        return 0.0 if self.zero_one else -1.0
+
+    def _flipped(self, s):
+        return 1.0 - s if self.zero_one else -s
+
+    # --- lattice sums ---
+
+    def _tables(self, L):
+        """Neighbour indices (N, 4) and weights (N, 4) of every site, with the code's bugs applied."""
+        key = ("tables", L)
+        if key not in self.__dict__:
+            idx = np.empty((L * L, 4), dtype=np.intp)
+            w = np.ones((L * L, 4))
+            for i in range(L):
+                for j in range(L):
+                    k = i * L + j
+                    down, up = ((i + 1) % L) * L + j, ((i - 1) % L) * L + j
+                    right, left = i * L + (j + 1) % L, i * L + (j - 1) % L
+                    if "same_neighbour_twice" in self.bugs:
+                        up = down
+                    idx[k] = (down, up, right, left)
+                    if "missing_wrap_x" in self.bugs:
+                        w[k, 2] = 1.0 if j + 1 < L else 0.0
+                        w[k, 3] = 1.0 if j - 1 >= 0 else 0.0
+            self.__dict__[key] = (idx, w)
+        return self.__dict__[key]
+
+    def _neighbour_sum(self, flat, sites, L):
+        """Sum of the four neighbours of the given site in every chain (flat: (n_chains, N))."""
+        idx, w = self._tables(L)
+        n_chains = flat.shape[0]
+        base = np.arange(n_chains) * (L * L)
+        values = flat.ravel()
+        total = 0.0
+        for d in range(4):
+            v = values[base + idx[sites, d]]
+            total = total + (v if "missing_wrap_x" not in self.bugs else v * w[sites, d])
+        return total
+
+    def _neighbour_sum_all(self, spins):
+        s = spins
+        down, up = np.roll(s, -1, axis=1), np.roll(s, 1, axis=1)
+        right, left = np.roll(s, -1, axis=2), np.roll(s, 1, axis=2)
+        return down + up + right + left
+
+    def measure(self, state, h=0.0):
+        s = state.spins
+        if "energy_double_counted" in self.bugs:
+            bonds = (s * self._neighbour_sum_all(s)).sum(axis=(1, 2))
+        else:
+            right = np.roll(s, -1, axis=2)
+            if "missing_wrap_x" in self.bugs:
+                right = right.copy()
+                right[:, :, -1] = 0.0
+            bonds = (s * (right + np.roll(s, -1, axis=1))).sum(axis=(1, 2))
+        M = s.sum(axis=(1, 2))
+        return -self.J * bonds - h * M, M
+
+    # --- set-up ---
+
+    def init(self, L, n_chains, start, rng, h=0.0):
+        if start == "cold":
+            spins = np.full((n_chains, L, L), self._up())
+        else:
+            spins = np.where(rng.random((n_chains, L, L)) < 0.5, self._up(), self._down())
+        state = State(spins, None, None)
+        state.E, state.M = self.measure(state, h)
+        return state
+
+    # --- single-site updates ---
+
+    def step(self, state, sites, u, T, h):
+        spins = state.spins
+        n_chains, L, _ = spins.shape
+        flat = spins.reshape(n_chains, L * L)  # a view: writes go to state.spins
+        rows = np.arange(n_chains)
+        sites = np.asarray(sites, dtype=np.intp)
+        s = flat[rows, sites]
+        h_dyn = -h if "field_sign_wrong" in self.bugs else h
+        phi = self.J * self._neighbour_sum(flat, sites, L) + h_dyn
+        if self.algorithm == "heatbath":
+            factor = 1.0 if "heatbath_missing_2" in self.bugs else 2.0
+            p_up = 1.0 / (1.0 + np.exp(-factor * phi / T))
+            new = np.where(u < p_up, self._up(), self._down())
+            dE_track = -(new - s) * phi
+        else:
+            dE = (1.0 if "delta_e_missing_factor_2" in self.bugs else 2.0) * s * phi
+            with np.errstate(over="ignore"):
+                if "exp_de_times_t" in self.bugs:
+                    p = np.exp(-dE * T)
+                elif "acceptance_table_off_by_one" in self.bugs:
+                    p = np.exp(-(dE + 4.0) / T)  # table entry for the next energy class
+                else:
+                    p = np.exp(-dE / T)
+            accept = u < np.minimum(1.0, p)
+            if "reject_zero_de" in self.bugs:
+                accept &= dE != 0.0
+            new = np.where(accept, self._flipped(s), s)
+            dE_track = dE  # the code tracks the energy with its own local energy change
+        changed = new != s
+        if "incremental_energy_not_updated" not in self.bugs:
+            state.E = state.E + np.where(changed, dE_track, 0.0)
+        state.M = state.M + (new - s)
+        flat[rows, sites] = new
+
+    # --- sweeps ---
+
+    def sweep(self, state, T, h, rng):
+        if self.algorithm in ("metropolis", "heatbath"):
+            n_chains, L, _ = state.spins.shape
+            N = L * L
+            for _ in range(N):
+                if "same_random_number" in self.bugs:
+                    u = rng.random(n_chains)
+                    sites = np.minimum((u * N).astype(int), N - 1)
+                else:
+                    high = N - L if "sweep_skips_last_row" in self.bugs else N
+                    sites = rng.integers(0, high, size=n_chains)
+                    u = rng.random(n_chains)
+                self.step(state, sites, u, T, h)
+        elif self.algorithm == "checkerboard":
+            self._checkerboard_sweep(state, T, h, rng)
+        else:
+            self._wolff_update(state, T, h, rng)
+
+    def _checkerboard_sweep(self, state, T, h, rng):
+        s = state.spins
+        n_chains, L, _ = s.shape
+        ii, jj = np.meshgrid(np.arange(L), np.arange(L), indexing="ij")
+        if "synchronous_update" in self.bugs:
+            masks = [np.ones((L, L), dtype=bool)]
+        elif "checkerboard_wrong_parity" in self.bugs:
+            masks = [(ii + jj) % 2 == 0, (ii + jj) % 2 == 0]
+        else:
+            masks = [(ii + jj) % 2 == 0, (ii + jj) % 2 == 1]
+        for mask in masks:
+            phi = self.J * self._neighbour_sum_all(s) + h
+            dE = 2.0 * s * phi
+            u = rng.random((n_chains, L, L))
+            accept = mask & (u < np.minimum(1.0, np.exp(-dE / T)))
+            state.E = state.E + np.where(accept, dE, 0.0).sum(axis=(1, 2))
+            state.M = state.M + np.where(accept, -2.0 * s, 0.0).sum(axis=(1, 2))
+            s = np.where(accept, -s, s)
+        state.spins[...] = s
+
+    def _wolff_update(self, state, T, h, rng):
+        """One Wolff cluster flip per chain (h must be 0). A 'sweep' here is one cluster update."""
+        if h != 0.0:
+            raise ValueError("the Wolff update is implemented for h = 0 only")
+        n_chains, L, _ = state.spins.shape
+        k = 1.0 if "wolff_probability" in self.bugs else 2.0
+        p_add = 1.0 - np.exp(-k * self.J / T)
+        for c in range(n_chains):
+            s = state.spins[c]
+            seed = int(rng.integers(0, L * L))
+            i0, j0 = divmod(seed, L)
+            sign = s[i0, j0]
+            cluster = {(i0, j0)}
+            stack = [(i0, j0)]
+            while stack:
+                i, j = stack.pop()
+                for a, b in (((i + 1) % L, j), ((i - 1) % L, j), (i, (j + 1) % L), (i, (j - 1) % L)):
+                    if (a, b) not in cluster and s[a, b] == sign and rng.random() < p_add:
+                        cluster.add((a, b))
+                        stack.append((a, b))
+            for a, b in cluster:
+                s[a, b] = -s[a, b]
+        state.E, state.M = self.measure(state, h)
+
+    # --- black box ---
+
+    def sample(self, L, T, h, n_sweeps, seed, n_chains=1, start="hot"):
+        rng = np.random.default_rng(12345 if "seed_ignored" in self.bugs else seed)
+        state = self.init(L, n_chains, start, rng, h)
+        for _ in range(self.burn_in):
+            self.sweep(state, T, h, rng)
+        e = np.empty((n_chains, n_sweeps))
+        m = np.empty((n_chains, n_sweeps))
+        N = L * L
+        for t in range(n_sweeps):
+            self.sweep(state, T, h, rng)
+            E, M = self.measure(state, h)
+            e[:, t] = E / N
+            m[:, t] = M / (L if "m_normalised_by_L" in self.bugs else N)
+        return e, m
+
+    def error_bar(self, series):
+        x = np.asarray(series, dtype=float)
+        if "naive_error_bars" in self.bugs:
+            return float(x.std() / np.sqrt(len(x)))
+        return blocked_error(x)