#!/usr/bin/env python3
"""MQG test 21 runner: which way the two-beam collective-neutrino model leaves the unstable point, and whether the
second beam is slaved to the first. Computes the 36 rows of MQG_TEST_21_PUBLIC_PLAN (rev. 2). It does not score;
the frozen rules are in mqg_test21_score.py.

Model (plan Sec. 2): H = B.(J_A - J_B) + (mu/N)(J^2 - 3N/4), B = (sin 2theta, 0, cos 2theta), beams of spin
j = N/4 starting along flavour +z and -z. The exact solver is the block solver of test 20 (blocks of fixed
M = m_A + m_B in the frame where B is the z axis, tridiagonal in m_A), unchanged; only the observables are new.

Per row (plan Sec. 4), on the grid t = 0, 0.02, ..., 8:
  * exact <|du|^2> = <(J_Ax/j - eps)^2 + (J_Ay/j)^2>  (flavour frame, eps = sin 2theta);
  * t* = first grid time with <|du|^2> >= 0.1; if none, the row is censored;
  * at t*: P+ = Prob(n.J_A > j eps cos phi+), n = (cos phi+, sin phi+, 0), from the eigenvectors of n.J_A
    (eigenvalues m = -j..j; an eigenvalue within 1e-9 of the threshold counts with weight 1/2);
  * at t*: r = <dJ_B+ dJ_A-> / (j^2 <|du|^2>), dJ_A- = J_Ax - j eps - i J_Ay, dJ_B+ = J_Bx + j eps + i J_By;
  * the same from the TWA, M = 8000, RK4 step 0.01, at the TWA's own t*, with the binomial standard error.
Row k uses TWA seed 20272100 + k.

Guards (plan Sec. 6; the run stops if one fails)
  V1 <J> and the covariance of the exact state agree with exact_moments of mqg_step2_robustness.py (SHA-256
     cb13dd79..., Stage-4 block solver) to 1e-8 relative at theta = 0.005, N = 640, mu = 2.0, t <= 5. A test point:
     runs only inside the RUN, after deposit, and computes no P+ or r. The smoke test runs it at its own point.
  V2 at j = 160 and 1280 (theta = 0.30, not a test angle): the n.J_A distribution sums to 1 within 1e-10 for n
     along phi+; for n along the block z axis it reproduces the J_Az distribution within 1e-10; and for n along
     flavour z at t = 0 it gives P(m = j) = 1 within 1e-10 (frame check). The eigenvalues equal m within 1e-8.
  V3 norms conserved to 1e-10 in every row.
  V4 with the same 8000 initial samples, halving the TWA step (0.01 -> 0.005) changes the TWA P+ at
     theta = 0.005, N = 640, mu = 2.0 by less than 0.002. A test point: RUN only.
Refuses to run without --deposit-doi or with the wrong NumPy; writes each row once (a rerun skips finished rows).
Smoke mode (--smoke): theta = 0.01, N = 200, mu = 1.8 (not a test point). It writes the row without printing P+ or r
and, with --step2, runs V1 at that point, printing only the deviation.
"""
from pathlib import Path
import argparse, hashlib, json, math, platform, time
from datetime import datetime, timezone
import numpy as np
from scipy.linalg import eigh_tridiagonal

THETAS = (0.005, 0.015, 0.03)
SIZES = (640, 1280, 2560, 5120)
MUS = (1.5, 2.0, 2.5)
DT_GRID, T_CAP, LEVEL = 0.02, 8.0, 0.1
TWA_STEP, M_TWA, SEED0 = 0.01, 8000, 20272100
WEIGHT_CUT, TIE = 1e-22, 1e-9
REQUIRED_NUMPY = '2.4.6'          # Colab version at the smoke test of 19 Nov 2026
STEP2_SHA256 = 'cb13dd79a8fc74be6a1a89799587f1362c4c45a96f27e67be821b636a0dc96d0'


def sha256(path):
    return hashlib.sha256(Path(path).read_bytes()).hexdigest()


def phi_plus(mu):
    """plan Sec. 2: phi+ = arg[-(1 + i lam)/(lam - i alpha)]."""
    lam, al = math.sqrt(mu - 1), 1 - mu / 2
    return float(np.angle(-(1 + 1j * lam) / (lam - 1j * al)))


def grid():
    return np.round(np.arange(0.0, T_CAP + DT_GRID / 2, DT_GRID), 10)


# ------------------------------------------------------------------------------------- exact solver (test 20)
def beam_amplitudes(j, vth):
    """Components, in the frame where B is z, of flavour |j,+j> (beam A) and |j,-j> (beam B); index 0 is m = -j."""
    m = np.arange(-j, j + 1, dtype=float)
    c, s = math.cos(vth / 2), math.sin(vth / 2)
    lgC = (math.lgamma(2 * j + 1) - np.array([math.lgamma(j + x + 1) + math.lgamma(j - x + 1) for x in m])) / 2
    with np.errstate(divide='ignore'):
        la = lgC + (j + m) * math.log(c) + (j - m) * math.log(s)
        lb = lgC + (j - m) * math.log(c) + (j + m) * math.log(s)
    a = np.exp(la) * np.where(((j - m) % 2) == 0, 1.0, -1.0)
    b = np.exp(lb)
    return a, b


class Blocks:
    """Blocks of fixed M = m_A + m_B (frame where B is z); rows of a block array are m_A ascending."""

    def __init__(self, N, mu, theta, b=+1):
        assert N % 4 == 0
        self.N, self.mu = N, mu
        self.j = j = N // 4
        self.jj = j * (j + 1)
        self.vth = math.atan2(math.sin(2 * theta), b * math.cos(2 * theta))
        a, bb = beam_amplitudes(j, self.vth)
        w = np.convolve(a ** 2, bb ** 2)
        keep = np.nonzero(w > WEIGHT_CUT)[0]
        self.skipped = float(w.sum() - w[keep].sum())
        self.lo, self.hi = int(keep.min() - 2 * j), int(keep.max() - 2 * j)
        self.a, self.bb = a, bb

    def mA(self, M):
        j = self.j
        return np.arange(max(-j, M - j), min(j, M + j) + 1)

    def psi0(self, M):
        if M < self.lo or M > self.hi:
            return np.zeros(len(self.mA(M)))
        mA = self.mA(M)
        return self.a[mA + self.j] * self.bb[M - mA + self.j]

    def tridiag(self, M):
        j, N, mu = self.j, self.N, self.mu
        mA = self.mA(M).astype(float)
        mB = M - mA
        d = (mA - mB) + (mu / N) * (2 * j * (j + 1) + 2 * mA * mB - 0.75 * N)
        e = (mu / N) * np.sqrt(j * (j + 1) - mA[:-1] * (mA[:-1] + 1)) * np.sqrt(j * (j + 1) - mB[:-1] * (mB[:-1] - 1))
        return d, e

    # single-beam ladder operators between blocks ------------------------------------------------------------
    def _ladder(self, M, X, beam, step):
        """beam 'A' or 'B', step +1 or -1, applied to block-M array X; result lives in block M + step."""
        T = M + step
        if abs(T) > 2 * self.j or X is None:
            return None
        mA, mT = self.mA(M), self.mA(T)
        mB = M - mA
        m = mA if beam == 'A' else mB
        c = np.sqrt(np.maximum(self.jj - m * (m + step), 0.0))
        tgt = (mA + step if beam == 'A' else mA) - mT[0]
        ok = (tgt >= 0) & (tgt < len(mT)) & (c > 0)
        out = np.zeros((len(mT),) + X.shape[1:], dtype=complex)
        out[tgt[ok]] = c[ok].reshape((-1,) + (1,) * (X.ndim - 1)) * X[ok]
        return out

    def components(self, M, below, here, above, beam):
        """(J_x psi, J_y psi, J_z psi) of one beam in block M (frame where B is z), from psi in M-1, M, M+1."""
        up = self._ladder(M - 1, below, beam, +1) if below is not None else None     # J+ psi_{M-1}
        dn = self._ladder(M + 1, above, beam, -1) if above is not None else None     # J- psi_{M+1}
        n = len(self.mA(M))
        shape = (n,) + (here.shape[1:] if here is not None else (below if below is not None else above).shape[1:])
        z = np.zeros(shape, complex)
        up = z if up is None else up
        dn = z if dn is None else dn
        jx, jy = (up + dn) / 2, (up - dn) / 2j
        if here is None:
            jz = z
        else:
            mA = self.mA(M).astype(float)
            m = mA if beam == 'A' else (M - mA)
            jz = m.reshape((-1,) + (1,) * (here.ndim - 1)) * here
        return jx, jy, jz


def _ip(x, y):
    """<x|y> summed over the rows of a block (one value per time)."""
    return np.sum(np.conj(x) * y, axis=0)


def exact_series(N, mu, theta, times, moments=False):
    """Sweep the blocks once over the whole time grid. Returns <|du|^2>(t), the slaving numerator and the norm.
    With moments=True also <J> and the covariance of the total J in the frame where B is z (guard V1)."""
    B = Blocks(N, mu, theta)
    j, eps = B.j, math.sin(2 * theta)
    cv, sv = math.cos(B.vth), math.sin(B.vth)
    times = np.asarray(times, float)
    nt = len(times)
    Ms = list(range(max(B.lo - 1, -2 * j), min(B.hi + 1, 2 * j) + 1))

    def evolve(M):
        v = B.psi0(M)
        if not np.any(v):
            return None
        d, e = B.tridiag(M)
        E, V = eigh_tridiagonal(d, e) if len(d) > 1 else (d, np.ones((1, 1)))
        X = np.exp(-1j * np.outer(E, times)) * (V.T @ v)[:, None]
        return V @ X.real + 1j * (V @ X.imag)

    acc = {k: np.zeros(nt, complex) for k in ('norm', 'X', 'Y', 'U', 'V', 'XX', 'YY', 'num')}
    if moments:
        tot = {k: np.zeros(nt, complex) for k in ('x', 'y', 'z', 'xx', 'yy', 'zz', 'xy', 'xz', 'yz')}
    psi = {}
    for M in Ms:
        for MM in (M - 1, M, M + 1):
            if MM in Ms and MM not in psi:
                psi[MM] = evolve(MM)
        for MM in [k for k in psi if k < M - 1]:
            del psi[MM]
        pm, pc, pp = psi.get(M - 1), psi.get(M), psi.get(M + 1)
        if pm is None and pc is None and pp is None:
            continue
        Ax, Ay, Az = B.components(M, pm, pc, pp, 'A')
        Bx, By, Bz = B.components(M, pm, pc, pp, 'B')
        X, Y = cv * Ax + sv * Az, Ay                       # flavour-frame components of J_A psi
        U, V = cv * Bx + sv * Bz, By                       # and of J_B psi
        Am, Bm = X - 1j * Y, U - 1j * V                    # (J_Ax - i J_Ay) psi, (J_Bx - i J_By) psi
        acc['XX'] += _ip(X, X)
        acc['YY'] += _ip(Y, Y)
        acc['num'] += _ip(Bm, Am)                          # <(J_Bx + i J_By)(J_Ax - i J_Ay)>
        if pc is not None:
            acc['norm'] += _ip(pc, pc)
            for k, W in (('X', X), ('Y', Y), ('U', U), ('V', V)):
                acc[k] += _ip(pc, W)
        if moments:
            J = (Ax + Bx, Ay + By, Az + Bz)
            for a, (p, q) in zip(('xx', 'yy', 'zz', 'xy', 'xz', 'yz'), ((0, 0), (1, 1), (2, 2), (0, 1), (0, 2), (1, 2))):
                tot[a] += _ip(J[p], J[q])
            if pc is not None:
                for a, W in zip('xyz', J):
                    tot[a] += _ip(pc, W)
    jx, jy, bx, by = (acc[k].real for k in ('X', 'Y', 'U', 'V'))
    du2 = (acc['XX'].real - 2 * j * eps * jx + (j * eps) ** 2 * acc['norm'].real + acc['YY'].real) / j ** 2
    # <(J_Bx + j eps + i J_By)(J_Ax - j eps - i J_Ay)> = <Bp Am> - j eps <Bp> + j eps <Am> - (j eps)^2
    num = acc['num'] - j * eps * (bx + 1j * by) + j * eps * (jx - 1j * jy) - (j * eps) ** 2 * acc['norm'].real
    out = dict(du2=du2, num=num, norm=acc['norm'].real, skipped=B.skipped, blocks=len(Ms), vth=B.vth,
               norm0=float(sum(np.sum(B.psi0(M) ** 2) for M in Ms)))
    if moments:
        mean = np.stack([tot['x'].real, tot['y'].real, tot['z'].real])
        G = np.empty((nt, 3, 3))
        for a, (p, q) in zip(('xx', 'yy', 'zz', 'xy', 'xz', 'yz'), ((0, 0), (1, 1), (2, 2), (0, 1), (0, 2), (1, 2))):
            G[:, p, q] = G[:, q, p] = tot[a].real - mean[p] * mean[q]
        out['mean'], out['cov'] = mean, G
    return out


def exact_state(N, mu, theta, t):
    """Full amplitude matrix Psi[m_A + j, m_B + j] at one time (frame where B is z)."""
    B = Blocks(N, mu, theta)
    j = B.j
    Psi = np.zeros((2 * j + 1, 2 * j + 1), complex)
    for M in range(B.lo, B.hi + 1):
        v = B.psi0(M)
        if not np.any(v):
            continue
        if t == 0:
            p = v.astype(complex)
        else:
            d, e = B.tridiag(M)
            E, V = eigh_tridiagonal(d, e) if len(d) > 1 else (d, np.ones((1, 1)))
            p = V @ (np.exp(-1j * E * t) * (V.T @ v))
        mA = B.mA(M)
        Psi[mA + j, M - mA + j] = p
    return Psi, B


def ndotJ_distribution(Psi, j, n):
    """Distribution of n.J_A (n a unit vector in the frame where B is z) for the state Psi[m_A, m_B].
    n.J = n_z J_z + w J+ + conj(w) J-, w = (n_x - i n_y)/2; a diagonal phase makes it real tridiagonal.
    Returns the eigenvalues (ascending) and their probabilities."""
    m = np.arange(-j, j + 1, dtype=float)
    w = (n[0] - 1j * n[1]) / 2
    cm = np.sqrt(j * (j + 1) - m[:-1] * (m[:-1] + 1))
    ph = np.exp(1j * np.angle(w) * np.arange(len(m))) if abs(w) > 0 else np.ones(len(m))
    lam, W = eigh_tridiagonal(n[2] * m, abs(w) * cm)
    Uh = (W.T * np.conj(ph)[None, :])                  # U^H with U = diag(ph) W
    Q = Uh @ Psi
    return lam, np.sum(Q.real ** 2 + Q.imag ** 2, axis=1)


def flavour_n_blockframe(vth, phi):
    """n = (cos phi, sin phi, 0) in the flavour frame, written in the frame where B is z."""
    xf = np.array([math.cos(vth), 0.0, math.sin(vth)])
    yf = np.array([0.0, 1.0, 0.0])
    return math.cos(phi) * xf + math.sin(phi) * yf


def p_plus(lam, prob, j, c):
    m = np.arange(-j, j + 1, dtype=float)
    dev = float(np.max(np.abs(lam - m)))
    w = np.where(np.abs(m - c) < TIE, 0.5, (m > c).astype(float))
    return float(np.sum(w * prob)), dev, int(np.sum(np.abs(m - c) < TIE))


# ------------------------------------------------------------------------------------------------ TWA
def twa_row(N, mu, theta, seed, step=TWA_STEP, M=M_TWA):
    """TWA (tests 19/20 sampling): a = J_A/j, b = J_B/j, transverse parts Gaussian with sd sqrt(1/(2j)),
    z components exactly +1 and -1. Returns <|du|^2>(t) on the grid and P+, its SE and r at the TWA's own t*."""
    j, eps = N / 4, math.sin(2 * theta)
    Bv = np.array([eps, 0.0, math.cos(2 * theta)])
    rng = np.random.default_rng(seed)
    sd = math.sqrt(1.0 / (2 * j))
    xa, ya, xb, yb = (rng.normal(0.0, sd, M) for _ in range(4))
    A = np.stack([xa, ya, np.ones(M)], axis=1)
    Bb = np.stack([xb, yb, -np.ones(M)], axis=1)

    def rhs(A, Bb):
        S = 0.5 * mu * (A + Bb)
        return np.cross(Bv + S, A), np.cross(-Bv + S, Bb)

    times = grid()
    per = int(round(DT_GRID / step))
    phi = phi_plus(mu)
    n = np.array([math.cos(phi), math.sin(phi), 0.0])
    c = eps * math.cos(phi)
    du2 = np.zeros(len(times))
    res = None
    for i in range(len(times)):
        if i > 0:
            for _ in range(per):
                k1 = rhs(A, Bb); k2 = rhs(A + 0.5 * step * k1[0], Bb + 0.5 * step * k1[1])
                k3 = rhs(A + 0.5 * step * k2[0], Bb + 0.5 * step * k2[1]); k4 = rhs(A + step * k3[0], Bb + step * k3[1])
                A = A + step / 6 * (k1[0] + 2 * k2[0] + 2 * k3[0] + k4[0])
                Bb = Bb + step / 6 * (k1[1] + 2 * k2[1] + 2 * k3[1] + k4[1])
        du = (A[:, 0] - eps) + 1j * A[:, 1]
        du2[i] = np.mean(np.abs(du) ** 2)
        if res is None and du2[i] >= LEVEL:
            P = float(np.mean(A @ n > c))
            num = np.mean(((Bb[:, 0] + eps) + 1j * Bb[:, 1]) * np.conj(du))
            res = dict(t_star=float(times[i]), P=P, se=math.sqrt(max(P * (1 - P), 0.0) / M),
                       r=[float((num / du2[i]).real), float((num / du2[i]).imag)])
    if res is None:
        res = dict(t_star=None, P=None, se=None, r=None)
    res['censored'] = res['t_star'] is None
    return times, du2, res


# ------------------------------------------------------------------------------------------------ one row
def compute_row(spec, log=print, quiet=False):
    N, mu, th = spec['N'], spec['mu'], spec['theta']
    j, eps = N // 4, math.sin(2 * th)
    t = grid()
    t0 = time.time()
    ex = exact_series(N, mu, th, t)
    dn = float(np.max(np.abs(ex['norm'] - ex['norm0'])))
    if dn > 1e-10:
        raise SystemExit(f"V3 failed in {spec['row']}: norm deviation {dn:.2e}")
    hit = np.nonzero(ex['du2'] >= LEVEL)[0]
    row = dict(spec, norm_dev=dn, skipped_weight=ex['skipped'], blocks=ex['blocks'])
    if len(hit) == 0:
        row.update(censored=True, t_star=None, P=None, r=None, eig_dev=None, ties=None)
    else:
        i = int(hit[0])
        ts = float(t[i])
        r = ex['num'][i] / (j ** 2 * ex['du2'][i])
        Psi, B = exact_state(N, mu, th, ts)
        phi = phi_plus(mu)
        lam, prob = ndotJ_distribution(Psi, j, flavour_n_blockframe(B.vth, phi))
        P, edev, ties = p_plus(lam, prob, j, j * eps * math.cos(phi))
        if edev > 1e-8 or abs(prob.sum() - 1) > 1e-10:
            raise SystemExit(f"V2 failed in {spec['row']}: eigenvalue dev {edev:.1e}, sum-1 {prob.sum() - 1:.1e}")
        row.update(censored=False, t_star=ts, P=P, r=[float(r.real), float(r.imag)], eig_dev=edev, ties=ties,
                   prob_sum_dev=float(prob.sum() - 1))
    t1 = time.time()
    _, du2_twa, tw = twa_row(N, mu, th, spec['seed'])
    t2 = time.time()
    row.update(twa=tw, time_exact_s=round(t1 - t0, 1), time_twa_s=round(t2 - t1, 1))
    if not quiet:
        log(f"  {spec['row']} theta={th} N={N} mu={mu}: exact {t1 - t0:.0f} s ({ex['blocks']} blocks), TWA {t2 - t1:.0f} s, "
            f"norm dev {dn:.1e}, {'censored' if row['censored'] else 'measured'}")
    return row, dict(t=t, du2=ex['du2'], num=ex['num'], du2_twa=du2_twa)


def rows():
    k = 0
    for th in THETAS:
        for N in SIZES:
            for mu in MUS:
                k += 1
                yield dict(row=f'MQG21-{k:02d}', k=k, theta=th, N=N, mu=mu, seed=SEED0 + k)


# ------------------------------------------------------------------------------------------------ guards
def load_step2(path):
    import importlib.util
    if path is None or sha256(path) != STEP2_SHA256:
        raise SystemExit(f'V1: mqg_step2_robustness.py missing or altered (expected SHA-256 {STEP2_SHA256})')
    spec = importlib.util.spec_from_file_location('mqg_step2_ref', path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def v1_deviation(ref, N, mu, theta, T):
    """<J> and covariance (frame where B is z) against the reference exact_moments; no P+ or r is computed."""
    times = np.round(np.arange(0.0, T + DT_GRID / 2, DT_GRID), 10)
    keep = ref.measures
    ref.measures = lambda rA, rB, Jmean, Jcov, N: {'mean': np.array(Jmean), 'cov': np.array(Jcov)}
    try:
        r = ref.exact_moments(ref.block_structure(N), mu, [ref.alpha_of(1, theta)], times)[0]
    finally:
        ref.measures = keep
    mine = exact_series(N, mu, theta, times, moments=True)
    return float(max(np.max(np.abs(mine['mean'].T - r['mean'])) / np.max(np.abs(r['mean'])),
                     np.max(np.abs(mine['cov'] - r['cov'])) / np.max(np.abs(r['cov']))))


def v2_check(log):
    """plan V2, at theta = 0.30 (not a test angle)."""
    worst = 0.0
    for N, ts in ((640, 1.0), (5120, 0.0)):
        j = N // 4
        Psi, B = exact_state(N, 2.0, 0.30, ts)
        lam, p = ndotJ_distribution(Psi, j, flavour_n_blockframe(B.vth, phi_plus(2.0)))
        d1 = abs(p.sum() - 1)
        d1e = float(np.max(np.abs(lam - np.arange(-j, j + 1))))
        lam, p = ndotJ_distribution(Psi, j, np.array([0.0, 0.0, 1.0]))
        d2 = float(np.max(np.abs(p - np.sum(np.abs(Psi) ** 2, axis=1))))
        Psi0, B0 = exact_state(N, 2.0, 0.30, 0.0)
        zf = np.array([-math.sin(B0.vth), 0.0, math.cos(B0.vth)])
        lam, p = ndotJ_distribution(Psi0, j, zf)
        d3 = abs(p[-1] - 1)
        worst = max(worst, d1, d2, d3, d1e * 1e-2)
        log(f'  V2  j={j}: sum-1 {d1:.1e}, eigenvalues {d1e:.1e}, z-check {d2:.1e}, frame check {d3:.1e}')
    return dict(max_dev=float(worst), ok=worst < 1e-10)


def run_guards(step2_path, log):
    res = {'V2': v2_check(log)}
    th, N, mu = 0.005, 640, 2.0
    t = grid()
    ex = exact_series(N, mu, th, t)
    dn = float(np.max(np.abs(ex['norm'] - ex['norm0'])))
    res['V3'] = dict(max_dev=dn, ok=dn < 1e-10)
    log(f'  V3  N=640 mu=2.0: norm deviation {dn:.1e}')
    a = twa_row(N, mu, th, SEED0, step=TWA_STEP)[2]
    b = twa_row(N, mu, th, SEED0, step=TWA_STEP / 2)[2]
    d = abs(a['P'] - b['P']) if not (a['censored'] or b['censored']) else float('inf')
    res['V4'] = dict(diff=float(d), ok=d < 0.002)
    log(f'  V4  N=640 mu=2.0: TWA P+ changes by {d:.4f} on halving the step (same samples)')
    ref = load_step2(step2_path)
    dv = v1_deviation(ref, N, mu, th, 5.0)
    res['V1'] = dict(max_rel=dv, ok=dv < 1e-8)
    log(f'  V1  N=640 mu=2.0 t<=5: largest difference / largest entry {dv:.1e}')
    return res


# ------------------------------------------------------------------------------------------------ main
def _jsonable(x):
    if isinstance(x, (np.floating, np.integer)):
        return x.item()
    raise TypeError(type(x))


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('--deposit-doi')
    ap.add_argument('--output-dir', default='mqg_test21')
    ap.add_argument('--step2', help='path of mqg_step2_robustness.py (reference for V1)')
    ap.add_argument('--smoke', action='store_true')
    ap.add_argument('--guards-only', action='store_true')
    args = ap.parse_args()
    out = Path(args.output_dir); out.mkdir(parents=True, exist_ok=True)
    logf = open(out / 'run_log.txt', 'a')

    def log(s):
        print(s, flush=True); logf.write(s + '\n'); logf.flush()

    me = sha256(__file__)
    log(f'MQG test 21 runner  sha256 {me}  {datetime.now(timezone.utc).isoformat()}')
    log(f'Python {platform.python_version()}  NumPy {np.__version__}')
    if args.smoke:
        spec = dict(row='SMOKE', k=0, theta=0.01, N=200, mu=1.8, seed=SEED0)
        row, ser = compute_row(spec, log=log)
        json.dump(row, open(out / 'smoke_row.json', 'w'), indent=1, default=_jsonable)      # written, not printed
        np.savez(out / 'smoke_series.npz', **ser)
        g = v2_check(log)
        log(f"SMOKE V2 {'ok' if g['ok'] else 'FAIL'}")
        if args.step2:
            dv = v1_deviation(load_step2(args.step2), 200, 1.8, 0.01, 8.0)
            log(f"SMOKE V1 theta=0.01 N=200 mu=1.8 t<=8: largest difference / largest entry {dv:.1e} ({'ok' if dv < 1e-8 else 'FAIL'})")
        log(f"SMOKE OK: {row['blocks']} blocks, skipped weight {row['skipped_weight']:.1e}, norm dev {row['norm_dev']:.1e}, "
            f"censored {row['censored']}, TWA censored {row['twa']['censored']}")
        return
    if np.__version__ != REQUIRED_NUMPY:
        raise SystemExit(f'NumPy {np.__version__}; the plan requires {REQUIRED_NUMPY}')
    if not args.guards_only and not args.deposit_doi:
        raise SystemExit('refusing to run without --deposit-doi (the DOI of the deposited public plan)')
    log('Guards:')
    g = run_guards(args.step2, log)
    json.dump(g, open(out / 'guards.json', 'w'), indent=1, default=_jsonable)
    if not all(v['ok'] for v in g.values()):
        raise SystemExit('a guard failed: the run is void (plan Section 5)')
    if args.guards_only:
        log('ALL GUARDS OK'); return
    rdir = out / 'rows'; rdir.mkdir(exist_ok=True)
    for spec in rows():
        f = rdir / f"{spec['row']}.json"
        if f.exists():
            log(f"  {spec['row']} already written, skipped"); continue
        row, ser = compute_row(spec, log=log)
        row.update(runner_sha256=me, deposit_doi=args.deposit_doi, numpy=np.__version__,
                   finished=datetime.now(timezone.utc).isoformat())
        np.savez(rdir / f"{spec['row']}_series.npz", **ser)
        json.dump(row, open(f, 'w'), indent=1, default=_jsonable)
    log('ALL 36 ROWS WRITTEN')


if __name__ == '__main__':
    main()
