Changelog

All notable changes to VibeSpin are documented here. The format follows Keep a Changelog. Version types align with Conventional Commits: feat → Added, fix → Fixed, and perf, refactor, docs, phys, test, and chore → Changed (or Removed, Deprecated, Security where that fits better). Only the six Keep a Changelog groups are used: Added, Changed, Deprecated, Removed, Fixed, Security.

Policy: Update the [Unreleased] section for every commit that changes user-facing behavior (physics, CLI, NPZ schema, public API, or documentation). When cutting a release, move [Unreleased] entries to a dated version block.


Unreleased

0.2.0 - 2026-10-04

Added

  • The NPZ outputs of scripts/xy/helicity_modulus.py, scripts/xy/bkt_transition.py, scripts/ising/correlation_divergence.py, and the three Wolff efficiency scripts write the standardized uncertainty fields and metadata of AGENTS.md section 8 (additive; legacy keys unchanged). The helicity modulus and vortex density get blocking errors from their per-sweep series, the correlation length a blocked error from fits to 16 contiguous sample blocks, and the efficiency quantities their replicate bands under the standard names. scripts/ising/measure_z.py adds the missing bootstrap_resamples and nan_or_undefined_count, and tau_metro_tau_int, tau_metro_n_eff, tau_wolff_tau_int, and tau_wolff_n_eff as NaN, since a seed-ensemble summary of autocorrelation times has no autocorrelation time of its own. The shared build_single_run_schema in utils/sweep_helpers.py assembles the fields for single-run sweeps.

  • The temperature sweeps write tau_int_ci_low and tau_int_ci_high, the 16th and 84th percentiles of the per-seed autocorrelation times (NaN for a single seed). CODE.md had documented these keys, but no script wrote them.

  • Calibration tests in tests/utility/test_statistics.py check the blocking interval coverage on autoregressive series, the seed-ensemble error against the scatter of the seed mean, the entropy error propagation against perturbed integrals, and that the bootstrap interval brackets its point estimate. Seven of the eight fail against the previous implementation.

  • utils/equilibration.py gains convergence_equilibrate_two_start, which returns a TwoStartOutcome keeping a stuck exit apart from genuine convergence; select_measurement_simulation, which measures the random start only after convergence; ordered_start_seed, which gives the ordered start its own seed; and prepare_equilibrated_simulation, which bundles the three. convergence_equilibrate_with_status keeps its signature and meaning.

  • connected_correlation_length in utils/observables.py measures the equilibrium correlation length from the connected pair correlation, with the mean spin of each configuration subtracted.

  • --seed on scripts/xy/bkt_transition.py, scripts/xy/helicity_modulus.py, and scripts/ising/correlation_divergence.py (default 0, a replica index into derive_point_seed); all three were unseeded. Their NPZ files record seed_index.

  • The Wolff efficiency NPZ files add wolff_flips_per_sample, converged_metro, and converged_wolff (additive).

  • DiscreteClockSimulation supports update='wolff'. Clusters are reflected about the q mirror axes of the clock, s -> (m - s) mod q, so every move stays in the discrete state space and detailed balance holds for the full discrete Hamiltonian. tests/algorithm/test_algorithm_integrity.py checks this on the exact transition matrix of a 2x2 lattice for q = 3 and 4, and compares the compiled kernel against one row of that matrix.

  • get_spin_field() on every simulation class returns the lattice in its physical representation: scalar spins for Ising, (L, L, 2) unit vectors for the planar models. The kinetics metrics and the ordering-evolution snapshots read the lattice through it, because the discrete clock model stores integer state indices that these helpers would otherwise treat as scalar spins.

  • All three correlation comparisons now fit their curves with the form each phase is expected to take, through the new shared fit_correlation_length and fit_correlation_exponent helpers in utils/observables.py. Previously only the Ising script fitted anything, and only the correlation length. The scripts add eta_crit (Ising, against the exact 1/4), eta_low, eta_low_spin_wave, xi_high (XY), and eta_quasi, eta_quasi_spin_wave, xi_disordered (clock) to their NPZ files, and log each fit next to its theoretical value. Measured at L=96 with 4 000 steps: Ising eta = 0.231 against the exact 0.25, XY eta = 0.055 against the spin-wave 0.064, clock eta = 0.144 against 0.127, all consistent with finite-size corrections at that lattice.

  • tests/style/test_notebook_prose.py: the writing rules AGENTS.md applies to notebook markdown are now checked, covering em dashes, unordered bullet lists, and the requirement that every code cell be introduced by a markdown cell. Ordered lists are left to review, since no test can tell a procedure from a roadmap that should have been a paragraph. All three guards were validated by reintroducing each violation.

  • Wolff efficiency comparison for the XY and clock models (scripts/xy/wolff_efficiency.py, scripts/clock/wolff_efficiency.py), built on the new shared utils/efficiency_runner.py. Both models had cluster updates and neither had the measurement that says when to use them. The clock comparison runs DiscreteClockSimulation, whose Wolff update reflects spins about the q mirror axes and is exact for the clock Hamiltonian, so both algorithms sample the same model.

  • notebooks/Wolff_Efficiency.ipynb gains a cross-model section contrasting the Z2 cluster flip with the O(2) reflection, plotting the sampling-rate advantage and the mean cluster fraction against each model’s own reduced temperature. The Ising advantage is sharply peaked at T_c, as a diverging power-law correlation length implies, while the XY curve is broad because the entire low-temperature phase is critical.

  • notebooks/Ising_Relaxation_and_Autocorrelation_Analysis.ipynb gains a section measuring why the ordered-start fallback is enabled for the Ising sweep and not for the vector sweeps. At T=0.1 with L=32 and eight seeds, four Ising and five discrete-clock random starts strand on a plateau below the ordered one while no XY start does: metastable trapping needs a discrete order parameter, since a continuous one lets the domain wall unwind. The section also notes, without acting on it, that a clock sweep run with --discrete would trap the way Ising does and does not enable the fallback.

  • scripts/generate_all.py: one command that regenerates all sixteen cached datasets the notebooks read, reporting each output and its runtime. It runs at production defaults by default and offers --quick for a full-pipeline smoke test in about a minute, plus --only, --skip, --skip-existing, --dry-run, --list, and --fail-fast. Until now a fresh checkout could only reach published-quality figures by running fourteen scripts by hand from the pipeline table, and nothing checked that the table was complete. tests/integration/test_generate_all.py now holds the two to each other, so a new data-producing script cannot be added to one and forgotten in the other.

  • Notebook contract tests (tests/style/test_notebook_contracts.py): every utils/models import in a notebook must resolve, and no notebook may pass positional arguments to a keyword-only project helper. Both checks were validated against the real regressions they are meant to catch. Ruff now lints notebooks as well (the previous extend-exclude = ["*.ipynb"] hid them), with prose-layout rules disabled for notebook cells.

  • The three temperature-sweep NPZ files now record size and meas_steps, so a figure can state the lattice it came from. The notebooks print this for the cached path and print their own parameters on the fallback path.

  • --seed flag on the three ordering_evolution.py scripts (previously unseeded, so the figures were not reproducible); default remains unseeded.

  • --n-seeds accepted as the canonical spelling on the three ordering_kinetics.py scripts, aligning with the temperature sweeps; the existing --seeds spelling keeps working.

  • --xi-eq-probe, --xi-eq-max, --xi-eq-steps, and --xi-eq-interval flags on scripts/ising/coarsening_analysis.py, replacing four hardcoded equilibrium-measurement parameters.

  • New shared simulate_equilibrium_correlation helper in utils/observables.py, replacing the near-verbatim duplicated per-model workers of the three correlation-comparison scripts. scripts/ising/correlation_comparison.py thereby gains two-start convergence equilibration and a --seed flag (previously unseeded with fixed-step burn-in, the weakest methodology of its triplet); its --eq-steps flag is replaced by --eq-probe/--eq-max.

  • New shared derive_point_seed helper in utils/sweep_helpers.py; the three temperature sweeps, measure_z.py, and wolff_efficiency.py use it instead of five inline copies of the seed-spacing formula (values unchanged).

  • --eq-qs-sigma-threshold and --eq-qs-min-steps stuck-detection flags on the XY and Clock temperature sweeps (previously Ising-only, with the values hardcoded elsewhere).

  • scripts/clock/compare_discrete_vs_continuous.py: new --aniso, --seed, and --log-file flags; runs are now reproducible and the anisotropy is no longer hardcoded.

  • scripts/benchmarks/throughput.py: project-standard logging with --verbose and --log-file (previously bare print).

  • scripts/ising/wolff_efficiency.py NPZ output now carries uncertainty_method (replicate_percentile), confidence_level, and nan_or_undefined_count metadata (additive).

  • All three temperature sweeps now write the n_seeds and bootstrap_resamples NPZ metadata keys required by the uncertainty schema contract; the Clock sweep additionally writes entropy_uncertainty_method (previously Ising/XY only). Existing keys are preserved (additive change).

  • New shared validate_sweep_uncertainty_args helper in utils/sweep_helpers.py: the XY and Clock sweeps now reject invalid --confidence-level, --n-seeds, strict-mode thresholds, and bootstrap configurations up front, exactly like the Ising sweep (previously they failed deep inside worker statistics or silently produced empty sweeps).

  • summarize_replicate_samples in utils/statistics.py now returns an err field (half the percentile band width) so replicate summaries conform to the standard uncertainty schema. This fixes a KeyError crash in scripts/ising/measure_z.py that occurred at NPZ save time, after the full sweep had completed.

  • New UNCERTAINTY_METHOD_REPLICATE constant ('replicate_percentile'). scripts/ising/measure_z.py now labels its NPZ uncertainty_method metadata truthfully instead of claiming 'blocking'.

  • ClockSimulation emits a UserWarning when update='wolff' is combined with a non-zero anisotropy A: the Wolff-Evertz reflection ignores the anisotropy term, so detailed balance is exact only for A=0.

  • New script scripts/clock/correlation_comparison.py: computes equilibrium \(G(r)\) for the \(q = 6\) clock model in ordered, quasi-ordered, and disordered phases using convergence equilibration. Saves results/clock/correlation_comparison.npz.

  • New script scripts/ising/coarsening_analysis.py: precomputes quench-depth sensitivity, equilibrium-to-coarsening crossover (\(\xi_{\mathrm{eq}}\) measurement), and stochastic ensemble data for the Ising model. Saves results/ising/coarsening_analysis.npz.

  • Multi-seed ensemble support in utils/kinetics_helpers.run_ordering_kinetics: new n_seeds and base_seed parameters produce median trajectories with IQR error bars. Per-seed arrays stored as additive NPZ keys (R_sk_seeds, R_xi_seeds, third_metric_seeds, R_sk_err, R_xi_err, third_metric_err).

  • All three ordering_kinetics.py scripts (Ising, XY, Clock) now accept --seeds and --base-seed CLI arguments for multi-seed runs.

  • Generated results/xy/correlation_comparison.npz (\(L = 128\)) from existing scripts/xy/compare_correlations.py.

  • Part II of notebooks/Correlation_and_Coarsening.ipynb now renders the ordering-evolution snapshot figure inline via a live simulation cell (L=128, T=0.1), showing spin configurations, structure factor, and correlation length \(\xi\) at \(t = 1, 10, 100, 1000\) Monte Carlo sweeps. The figure is no longer loaded from a pre-generated PNG; it is generated reproducibly within the notebook kernel on each run.

  • Part II of notebooks/Correlation_and_Coarsening.ipynb now includes a new “Vortex Spacing vs Structure Factor and Correlation Length” subsection for the XY and Clock models, showing \(R_v = n_v^{-1/2}\) (mean vortex spacing) alongside \(R_{S(k)}\) and \(R_\xi\) on log-log axes with Allen-Cahn reference, mirroring the Ising MIL comparison. All three estimators show exponents \(n \approx 0.4\)–\(0.5\).

  • Part II of notebooks/Correlation_and_Coarsening.ipynb now includes a “Domain Coarsening vs Boundary-Wall Decay” subsection with a unified log-log comparison plot overlaying all three coarsening-length estimators (\(R_{S(k)}\), \(R_\xi\), \(R_{\mathrm{MIL}}\)) against the Allen-Cahn \(t^{1/2}\) reference line.

  • Kinetics loading cell now exposes pre_third (the MIL power-law prefactor) so the boundary-wall proxy fit line can be drawn in the comparison plot.

  • New notebook notebooks/XY_Temperature_Sweep.ipynb: full thermodynamic sweep across the BKT crossover for the XY model, with data loading/fallback, convergence diagnostics, and autocorrelation analysis.

  • New notebook notebooks/Clock_Temperature_Sweep.ipynb: temperature sweep for the q-state clock model showing the two-crossover regime structure, with entropy reference at ln(q).

  • New notebook notebooks/BKT_Transition.ipynb: dedicated notebook examining vortex density, helicity modulus, and correlation function across the BKT transition.

  • New notebook notebooks/Correlation_and_Coarsening.ipynb: combined notebook covering equilibrium correlation functions (Ising, XY) and non-equilibrium coarsening dynamics across all three models.

  • NPZ output for scripts/xy/bkt_transition.py, scripts/xy/helicity_modulus.py, scripts/xy/compare_correlations.py, scripts/ising/correlation_comparison.py, scripts/ising/correlation_divergence.py.

  • Optional npz_path parameter in utils/kinetics_helpers.run_ordering_kinetics for persisting kinetics data. All three ordering_kinetics scripts now save NPZ output.

  • Data Pipeline mapping table in SCRIPTS.md documenting the script-to-NPZ-to-notebook data flow.

  • utils/kinetics_helpers.py: new shared module providing the ordering-kinetics simulation loop for the Ising, XY, and Clock scripts. Exports compute_mean_intercept_length (stereological domain-size estimator for scalar-spin lattices) and run_ordering_kinetics (loop over logarithmically spaced step targets, power-law fitting, and figure generation).

  • utils/evolution_helpers.py: new shared module providing the ordering-evolution snapshot loop for the Ising, XY, and Clock scripts. Exports run_ordering_evolution, which captures spin configurations, correlation functions, and (for vector-spin models) vorticity maps at each target step, then writes the multi-panel figure.

  • utils/sweep_helpers.py: new shared module providing the two-layer temperature-sweep worker infrastructure used by all three model sweep scripts. Exports ThermoPoint (typed NamedTuple worker payload), RawThermoData (raw measurement arrays), simulate_at_temperature (Layer 1: physics and equilibration), compute_thermo_observables (Layer 2: statistical summarization), simulate_thermo_point (convenience wrapper), build_uncertainty_bundle, and build_quality_flags.

Changed

  • Breaking: parallel=True with the checkerboard update raises ValueError on odd lattice sizes. With odd L the periodic boundary joins same-parity sites, so rows 0 and L - 1 are neighbours on the same sublattice and the prange loop could update them concurrently. The serial checkerboard sweep remains valid for odd L. Migration: use an even L, or parallel=False.

  • Confidence intervals built on a blocking error use the Student-t quantile with n_blocks - 1 degrees of freedom instead of the Gaussian one. The plateau rule often settles on a handful of large blocks for strongly correlated series, and the nominal 68 % interval then covered the true mean in only 54 to 69 % of autoregressive test runs (tau_int 1 to 100, 2 000 to 20 000 samples); with t it covers 64 to 71 %. The standard errors themselves are unchanged. Seed-ensemble intervals use t with n_seeds - 1 degrees of freedom, and single-seed sweeps, as well as temperatures where only one seed returned a finite value, keep the t interval of the blocking estimate (the workers now also emit <obs>_ci_low and <obs>_ci_high per point).

  • Breaking (NPZ values): a zero-variance window now yields NaN for err, ci_low, and ci_high (and for the derived observables), as AGENTS.md section 8 requires; it previously yielded 0. Frozen low-temperature points were already excluded from the notebook plots through undefined_autocorr_flag.

  • Breaking (NPZ values): the Wolff efficiency comparison gives both algorithms the same budget in sweep units. Wolff now records one sample every round(L^2 / <C>) cluster flips instead of one per flip, and the mean cluster size comes from a pass on the measured run instead of a third equilibrated pair. With one sample per flip, Wolff received a few sweeps of work in the paramagnet (L = 64, T = 3.2: 2000 flips covered about 4 sweeps), which produced a spurious 25-fold Wolff advantage there and a susceptibility that disagreed with Metropolis (0.62 against 1.00). With equal budgets the two agree (1.00 against 0.98) and Metropolis is about ten times more efficient in the paramagnet, as expected. tau_wolff stays in cluster flips, so tau_wolff_norm keeps its meaning. Cached wolff_efficiency.npz files should be regenerated.

  • scripts/clock/correlation_comparison.py applies its default temperatures (0.5, 0.8, 1.2) only to the discrete q = 6 model. For --continuous or another q, whose T1 and T2 differ, --t-ordered, --t-quasi, and --t-disordered are required, q < 5 is rejected because it has no quasi-ordered phase, and the stored T1 and T2 are NaN.

  • Breaking (NPZ values): a point whose two starts reach the equilibration cap without converging is no longer measured. Previously the scripts measured the ordered start anyway, although neither start had been shown to relax, which replaced the initialization bias of the random start with that of the ordered one. The point is now stored as NaN and flagged: equilibrated in the helicity-modulus and BKT outputs, metro_equilibrated and wolff_equilibrated in dynamic_exponent_z.npz, the existing converged_metro and converged_wolff in the Wolff efficiency outputs, and bridge_xi_eq_equilibrated in coarsening_analysis.npz. The correlation comparisons store an all-NaN G(r) for such a point, and compare_discrete_vs_continuous.py plots a gap. TwoStartOutcome.certified tells callers whether a measurement is valid. Migration: check the new flags, or drop NaN points, when reading these files.

  • scripts/xy/correlation_comparison.py raises the --eq-max default from 50 000 to 200 000 sweeps. At T = 0.4 the random start sheds its vortex pairs only after 46 000 to 58 000 sweeps on L = 128; it used to be cut short by the stuck detector and replaced by the ordered start, and with the cap left at 50 000 the point would now be stored as NaN for some seeds. The notebook fallbacks at L = 64 raise their cap from 6 000 to 60 000 sweeps for the same reason (about 35 000 needed).

  • Stuck detection in convergence_equilibrate_two_start is opt-in (detect_stuck=False by default); convergence_equilibrate_with_status and convergence_equilibrate keep stopping on a stuck state. The detector cannot tell a stranded random start from a slowly relaxing one, so near a transition it ended runs on a random start that was still relaxing, and the ordered start was then measured without the two starts ever having agreed. The scripts enable it only below the ordering temperature of the Ising and discrete clock models: the sweeps, the Wolff efficiency comparisons, the ordered-phase point of the Ising and clock correlation comparisons, the discrete half of compare_discrete_vs_continuous.py, and the coarsening analysis. simulate_equilibrium_correlation, CorrelationPoint, EfficiencyPoint, and run_wolff_efficiency gain a matching opt-in (detect_stuck or stuck_below), and the ordering temperatures of the discrete clock model move to scripts/clock/_model_choice.py as ORDERED_BELOW_DISCRETE.

  • The temperature sweeps enable stuck detection only where a stuck state is accepted (Ising and the discrete clock model below their ordering temperature). Elsewhere a stuck exit only discarded the point, and at L = 32 the detector fired on every one of ten XY runs at T = 0.9 and T = 0.5 after 1500 sweeps, although each pair converged within 2400 to 9400 sweeps when allowed to continue. XY points near T_BKT are therefore no longer lost to retries.

  • Breaking: the clock scripts (temperature_sweep.py, correlation_comparison.py, ordering_kinetics.py, ordering_evolution.py, wolff_efficiency.py) and the models/clock_model.py example CLI run the discrete clock model by default. Previously the sweep and the Wolff comparison ran ClockSimulation at A = 0, which is the XY model, while labelling the output as a q = 6 clock model with its T1 and T2 overlay; the other scripts ran continuous spins at A = 1.0 or 0.5. --continuous restores a continuous run, with --aniso defaulting to 1.0 (sweep, correlation comparison, example CLI) or 0.5 (kinetics, evolution), and --aniso without --continuous is now a usage error. Migration: add --continuous --aniso <A> to reproduce a continuous run; note that the old sweep default corresponds to --continuous --aniso 0, which is the XY model. Cached results/clock/*.npz files from earlier versions describe the old models and should be regenerated.

  • The clock temperature sweep enables the ordered-start fallback for the discrete model below its lowest ordering temperature (exact for q = 2, 3, 4; T1 = 0.68 for q = 6), as the Ising sweep does below T_c. Random starts strand in domain-wall states there, as the relaxation notebook had already shown for the discrete clock model.

  • Breaking: ClockSimulation(update='wolff') raises ValueError for A != 0 instead of warning. The cluster update ignores the anisotropy, so the chain sampled the XY model under a clock label; with the constructor default A = 1.0 this was the outcome of the plain --update wolff flag of the example CLI. Migration: pass A=0.0 explicitly for an XY-equivalent run, or use DiscreteClockSimulation(update='wolff').

  • Breaking: all simulation classes reject a negative or non-finite coupling J with ValueError. The Metropolis tables and the Wolff bond probability assume ferromagnetic exchange; with J < 0 the Ising kernels accepted every uphill move and the Wolff updates flipped single spins unconditionally, so the chains sampled the wrong distribution (4x4 Ising at T = 2.5: exact energy -22.07, checkerboard result +4.0). J = 0 remains allowed.

  • AGENTS.md: the writing-style rules now open with their purpose (sober scientific prose without the register of AI-generated text), and the Python conventions state theirs (a consistent professional style across the codebase). The changelog rule is stated once instead of three times, a duplicated sentence in the writing role and the “(Additive)” heading suffixes are removed, and the tone rule no longer refers to a CLI environment. The instruction to “fulfill the user’s request thoroughly” is removed, since it addressed the agent rather than the writing style; all writing-style rules and Python conventions are kept.

  • Development runs in a local uv-managed virtual environment instead of a devcontainer. uv.lock is now the single source of truth for dependencies: both CI workflows install with uv sync --locked --all-extras, and requirements.txt is exported from uv.lock by a pre-commit hook for pip users. A CI step fails if the two files disagree, which closes the gap that let uv.lock keep pillow 12.2.0 and bleach 6.3.0 after requirements.txt had moved on. A new .python-version pins Python 3.12 for uv. The README describes the setup, including WSL on Windows.

  • The cross-file links in README.md, BIBLIOGRAPHY.md, and CODE.md use blob/HEAD rather than blob/master, so they follow the repository’s default branch instead of breaking if it is renamed. They stay absolute because the documentation symlinks these files into docs/source/, and MyST resolves a relative link against the symlink’s target in the repository root rather than against the documentation tree, which makes every such link a dead cross-reference under the strict Sphinx build.

  • The XY and clock correlation comparisons run their temperatures across the worker pool, as the Ising one already did, through a shared pickleable worker that replaces the Ising script’s local copy. Measured at L=96: XY drops from 14 to 10 seconds, clock from 55 to 29 on four cores. Every pre-existing NPZ key is bit-identical to the serial output for all three models.

  • The correlation fits now bound their window at L/4 rather than at a hardcoded index, since beyond that distance the periodic images of a site are nearer than the nominal separation and flatten the tail for reasons unrelated to the decay. The Ising correlation length is unchanged by this, because the positivity cut already ended its window at the same distance.

  • Notebook prose brought under the project writing rules, which had reached the documentation but not the notebooks, since nothing read notebook markdown at the time. Twenty-six bullet-list lines and thirty-four em dashes across four notebooks are rewritten as flowing prose; the one genuinely procedural list, the four steps of the two-start convergence test, stays a list as AGENTS.md allows. Five of the nine notebooks were already clean, so this is a parity fix rather than a rewrite.

  • The XY and clock correlation sections of Correlation_and_Coarsening now introduce their plot cells with prose, as the Ising section already did. They were the only two places in any notebook where a code cell followed another code cell with nothing said in between.

  • run_with_cluster_sizes moves from IsingSimulation to MonteCarloSimulation. It only ever used base-class state, and all three models run cluster updates, so having it on Ising alone was an accident of where it was first needed.

  • scripts/ising/correlation_divergence.py names its entry point main, as the other twenty scripts already did; it was the only one calling something else (run_divergence_analysis) under __main__, and nothing imported the old name.

  • The three temperature-sweep scripts now share utils/sweep_runner.py, which carries the argument surface, the seed-retry collection loop, the uncertainty bundles, the NPZ schema, and the figure call. The mains shrink from about 380 lines each to roughly 70 and now show only what actually differs between the models: the simulation class, the defaults, the transition overlay, and whether an ordered start is preferred below a critical temperature. A change to the uncertainty schema now reaches all three models at once instead of drifting between them. Verified by running old and new implementations on the same arguments: all 54 NPZ keys and every value are identical for all three models.

  • The Wolff-Evertz cluster reflection moves to models/simulation_base.py as o2_wolff_step_numba, replacing the byte-identical xy_wolff_step_numba and clock_wolff_step_numba. The bond construction only ever sees the exchange term, so it is the same update for every O(2) model here; the anisotropy caveat it carried for the clock model is stated in the shared docstring, next to the ClockSimulation warning that enforces it. Trajectories are unchanged: magnetisation, energy, and the full sequence of cluster sizes match the previous implementation exactly for both models.

  • Production data quality: the three temperature sweeps raise their defaults to 60 temperature points, 20 000 measurement steps and 5 seed replicas (Ising and XY at L=64, Clock at L=48). The seed count is the decisive change: with the previous single-seed default the cached data carried no between-seed uncertainty, so the hierarchical estimator the schema was built around never ran on production data. Measured cost on four cores is roughly 3 minutes (Ising), 11 minutes (XY) and 16 minutes (Clock).

  • Notebook fallback quality: fallback parameters raised within an interactive runtime budget, per model rather than uniformly. Ising goes to L=40, 25 temperature points and 10 000 steps (measured: curve roughness 19.9 % to 8.4 %, susceptibility-peak localisation from 0.131 to 0.048 in temperature, 10.6 s). XY and Clock keep L=32 and spend their budget on temperature resolution and statistics instead, because for the vector models a larger lattice increases critical slowing down faster than the statistics improve (Clock roughness 42.4 % to 20.0 %). The correlation fallbacks move from L=40 to L=64 with 6 000 steps.

  • The three hand-written correlation fallbacks now call the shared simulate_equilibrium_correlation, which falls back to the ordered start when the two-start criterion is not met. Without that fallback a random start stranded by the stuck detector distorted G(r) badly at larger lattices: at L=128 the fitted spin-wave exponent came out as 1.53 against a theoretical 0.064. This is what previously capped those fallbacks at L=40.

  • The XY correlation fallback now uses the same temperatures as scripts/xy/correlation_comparison.py (0.4 and 1.5) instead of 0.5 and 1.5 times T_BKT. The old values cost no runtime and merely made the surrounding prose, which quotes the spin-wave prediction at T=0.4, wrong on the path that actually executes.

  • Notebook zip() calls carry strict=True, so parallel arrays cannot silently desynchronise.

  • Docstring format unified repo-wide to numpydoc: every Parameters/Returns/Raises section across models/, utils/, and scripts/ now uses the standard name : type entry layout with the type taken from the signature annotation, and prose-only Returns sections carry an explicit return-type line. Rendered API pages now show typed parameter lists uniformly; docstring content is unchanged.

  • Logging call style unified to f-strings (the three remaining lazy %-style logger calls in sweep_helpers, measure_z, and wolff_efficiency were converted); log output is unchanged.

  • _propagate_entropy_uncertainty_from_cv_errors replaces its Python backwards loop with a reversed cumulative sum. The NaN-poisoning semantics are preserved exactly (a non-finite segment invalidates its own and all lower-temperature points while higher temperatures stay exact); verified against the previous implementation across finite, partially NaN, all-NaN, unsorted, and edge-size inputs, and covered by a new regression test.

  • Breaking (script path): scripts/xy/compare_correlations.py is renamed to scripts/xy/correlation_comparison.py, matching its Ising and Clock siblings; outputs are unchanged. Invocations of the old path must switch to the new name.

  • scripts/ising/coarsening_analysis.py: the crossover (“bridge”) traces now use a seed block offset by 300 from the quench-depth traces, which previously shared identical (temperature, seed) pairs at quench fraction 0.5 and therefore produced identical trajectories; its correlation-length extraction now delegates to the shared interpolating 1/e helper (values shift slightly from grid-snapped to interpolated estimates).

  • utils/__init__ now exports the utilities scripts and notebooks actually consume (equilibration entry points, observables, statistics summarizers, sweep helpers, system infrastructure) instead of a stale eleven-name subset.

  • setup_logging can attach a file handler on a later call: previously the first call without log_file permanently blocked any subsequent call from adding one; console and file handlers are now guarded independently and duplicate file handlers for the same path are skipped.

  • calculate_autocorr computes the power spectrum as a real array and normalizes only the lags it consumes (up to max_lag) instead of the full series length; summarize_entropy_observable builds its result dict through a single helper; the chi/Cv fluctuation formulas live once in utils.observables.derived_thermo_estimate, shared by calculate_thermodynamics and the derived-observable summarizer.

  • Docstring completeness: blocking_error, estimate_effective_sample_size, summarize_primary_observable, summarize_derived_observable, summarize_replicate_samples, and summarize_asymmetric_replicate_uncertainty now carry full Parameters/Returns sections.

  • Documentation prose brought in line with the project’s own writing rules: em dashes and the flagged filler words (robust, comprehensive, utilize) removed from README.md, PHYSICS.md, CODE.md, SCRIPTS.md, and the Performance_Benchmarks and Ising_Temperature_Sweep notebook markdown; two non-procedural bullet lists rewritten as prose.

  • --transition-preset semantics in the Ising and XY sweeps: the default 'auto' now shows the known theoretical transition overlay (previously it behaved identically to 'none'); 'none' still disables it. The Clock sweep gains the same flag, marking the approximate q=6 crossover temperatures T1=0.68 and T2=0.92 already used as phase boundaries by scripts/clock/correlation_comparison.py (overlay is skipped for other q).

  • The XY and Clock sweeps restore the dropped-seed warning the Ising sweep already had, and their strict-mode error messages match the Ising wording.

  • measure_z.py and wolff_efficiency.py derive their median and 16-84 percentile envelopes from the shared summarize_replicate_samples instead of duplicated inline helpers (numerically identical).

  • Script cleanups: the runtime assert in scripts/clock/correlation_comparison.py is now an explicit RuntimeError; the duplicated np.savez_compressed blocks and 'xi' in locals() control flow in the Ising correlation scripts are replaced by a single kwargs dict with explicit None checks; scripts/ising/diag_eq_traces.py caches its T=2.00 traces instead of re-simulating them for the detail figure; all scripts use parse_args_compat; stale “4-panel plots” docstrings in the sweeps corrected.

  • Sweep workers compute blocking analysis and autocorrelation once per time series and share the results between the primary and derived summarizers (previously two blocking scans and two FFTs per series per point). summarize_primary_observable and summarize_derived_observable accept optional precomputed blocking/tau_int inputs; new estimate_tau_int_or_nan helper. summarize_derived_observable also gains an rng_seed parameter for its block-bootstrap (default 0 preserves the previous stream).

  • convergence_equilibrate_with_status spaces its convergence checks geometrically (25% growth) once the accumulated trace outgrows a chunk, bounding total analysis cost at O(max_steps) instead of O(max_steps^2/chunk). Convergence occurring between two checks is caught at the next check, so measured equilibration step counts can be slightly larger than before, never smaller.

  • save_plot accepts an explicit fig and a close flag; the temperature-sweep, kinetics, and evolution plot helpers now pass their figure explicitly and close it after saving, so long sweeps no longer accumulate open figures in pyplot’s global registry.

  • Public model observable API: get_magnetization, get_energy, and calculate_correlation_function on MonteCarloSimulation, plus calculate_vorticity, get_vortex_density, and get_helicity_data via a new VectorSpinObservablesMixin on the XY and Clock models. Utility protocols, helper modules, scripts, and notebooks now use these public methods instead of the private underscore methods.

  • Keyword-only arguments on public analysis entry points: estimate_relaxation_time_two_start, convergence_equilibrate, convergence_equilibrate_with_status, parse_args_compat, and compute_mean_intercept_length; all call sites (scripts, tests, notebooks) updated.

  • blocking_error now treats any NaN-containing series like the all-NaN case and returns the graceful NaN result dict (previously a partially NaN series silently produced a meaningless plateau selection).

  • run_ordering_evolution raises RuntimeError instead of silently skipping a snapshot when the lattice is uninitialized; run_ordering_kinetics validates max_steps, samples, fit_min, and n_seeds before computing step targets.

  • New shared correlation_length_1e helper in utils/observables.py replaces three divergent inline copies of the 1/e-crossing interpolation (kinetics metrics and two plot helpers), plot_ordering_evolution_snapshots among them.

  • docs/check_markdown_links.py now validates intra-document anchors (#fragment) against heading slugs in both same-file and cross-file links, and gains an opt-in --external mode that probes external URLs over the network. The Sphinx configuration no longer suppresses myst.xref_missing, so dead internal cross-references now fail the -W docs build.

  • docs/generate_api_docs.py includes scripts.benchmarks in the generated API reference (the throughput benchmark was previously missing from the docs site).

  • Breaking (seeded trajectories): per-sweep Numba reseeding now mixes (seed, step) through a SplitMix64 finalizer (models.simulation_base._derive_step_seed) instead of using seed + step. Previously, seed s at sweep t + 1 consumed exactly the same random stream as seed s + 1 at sweep t, so replicas seeded with consecutive integers (the base_seed + k convention) were not statistically independent. Seeded trajectories differ from those produced by earlier versions; unseeded behavior is unchanged.

  • Clock continuous Wolff kernel (clock_wolff_step_numba) now uses the pre-allocated cluster buffers and reflects only tracked cluster members instead of allocating fresh arrays per call and scanning the full lattice. It returns the cluster size, and last_cluster_size is now initialized on all models in MonteCarloSimulation (previously Ising-only).

  • build_uncertainty_bundle single-seed path now applies the Gaussian z-multiplier for the requested confidence level to ci_low/ci_high (previously fixed at plus/minus one standard error regardless of confidence).

  • README.md documents that the optional parallel checkerboard kernels are not seed-reproducible (Numba seeds only the calling thread’s RNG); model docstrings state the same caveat on the parallel parameter.

  • Updated pre-commit hook versions to match the locked project environment: ruff-pre-commit v0.15.0 → v0.15.13 and mirrors-mypy v1.18.2 → v2.1.0. The mypy hook’s additional_dependencies are now pinned to the versions from requirements.txt, fixing spurious prange iteration errors caused by version drift between the isolated hook environment and the project venv.

  • Transitioned project package and virtual environment management to use uv.

  • Configured .devcontainer/devcontainer.json postCreateCommand to globally install uv and use uv sync --all-extras for deterministic environment provisioning.

  • Pinned and locked all direct and transitive dependencies into uv.lock.

  • Regenerated standard requirements.txt using uv pip compile to ensure backward compatibility.

  • Updated README.md to recommend uv sync and uv run commands for local installation and test suites.

  • notebooks/Correlation_and_Coarsening.ipynb: quench-depth (cell 31), crossover (cell 34), and stochastic ensemble (cell 39) cells now load precomputed data from results/ising/coarsening_analysis.npz with inline computation as fallback only. Clock correlation cell (cell 13) and XY correlation cell (cell 8) similarly load from cached NPZ files. Methodology section updated to describe multi-seed ensemble averaging.

  • Improved Ising ordering kinetics generation defaults in scripts/ising/ordering_kinetics.py: max_steps reduced from 1000 to 400, samples increased from 10 to 25, fit_min reduced from 20 to 5. The regenerated results/ising/ordering_kinetics.npz yields fitted exponents \(n \approx 0.490\) (\(R_{S(k)}\)), \(0.487\) (\(R_\xi\)), \(0.517\) (\(R_{\mathrm{MIL}}\)), close to the Allen-Cahn prediction \(n = 1/2\).

  • Improved XY ordering kinetics generation defaults in scripts/xy/ordering_kinetics.py: temp changed from 0.1 to 0.5 (well below \(T_{\mathrm{BKT}} \approx 0.893\), better vortex mobility), max_steps increased to 1500, samples increased to 30, fit_min reduced to 5. Fitted exponents: \(n \approx 0.448\) (\(R_{S(k)}\)), \(0.477\) (\(R_\xi\)).

  • Improved Clock ordering kinetics generation defaults in scripts/clock/ordering_kinetics.py: same parameter changes as XY. Fitted exponents: \(n \approx 0.413\) (\(R_{S(k)}\)), \(0.449\) (\(R_\xi\)).

  • Regenerated results/xy/ordering_kinetics.npz and results/clock/ordering_kinetics.npz with new parameters (L=256, T=0.50). The exponent comparison table in notebooks/Correlation_and_Coarsening.ipynb now shows all three models with finite, physically meaningful values instead of NaN.

  • Regenerated results/ising/correlation_comparison.npz with \(L=128\) (64 radial points, \(r \in [0, 63]\)) and 10 000 measurement steps. The previous production cache had been overwritten by the test suite with \(L=16\) and only 5 steps. The Part I Ising correlation plot now shows clear separation between the three temperature regimes over more than a decade in \(r\).

  • Fallback _compute_ising_correlations function in notebooks/Correlation_and_Coarsening.ipynb updated to use \(L=128\) and 2 000 measurement steps (was \(L=40\), 1 500 steps).

  • \(r^{-1/4}\) guide in the Ising \(G(r)\) plot is now anchored dynamically to the critical data at \(r = 2\) and spans the full data range; previously it was hardcoded to \([1, 15]\) regardless of \(L\).

  • Domain Growth Curves figure: y-axis relabelled from “Domain size \(R(t)\)” to “Characteristic length \(R(t)\) (lattice units)” and suptitle changed from “Coarsening: domain growth after infinite-temperature quench” to “Coarsening kinetics after infinite-temperature quench”. For the XY model, \(R(t)\) tracks the vortex-antivortex spacing, not a domain size.

  • Part II prose updated throughout to replace “domain size” and “domain-size proxies” with physically accurate language (“coarsening length scale”, “coarsening-length estimators”) that applies to both the Ising (domain-wall) and XY (vortex annihilation) regimes.

  • utils/observables.py: replaced upward dependency on models.simulation_base.MonteCarloSimulation with a structural Protocol class _Sim, eliminating the utils-to-models import cycle.

  • Refactored scripts/ising/ordering_kinetics.py, scripts/xy/ordering_kinetics.py, and scripts/clock/ordering_kinetics.py to delegate the full simulation loop, power-law fitting, and figure generation to utils/kinetics_helpers.run_ordering_kinetics. Each script is now a thin argument-parsing wrapper.

  • Refactored scripts/ising/ordering_evolution.py, scripts/xy/ordering_evolution.py, and scripts/clock/ordering_evolution.py to delegate the snapshot loop and figure generation to utils/evolution_helpers.run_ordering_evolution. Vorticity capture is controlled by the capture_vorticity flag (True for XY and Clock, False for Ising).

  • Refactored scripts/ising/temperature_sweep.py, scripts/xy/temperature_sweep.py, and scripts/clock/temperature_sweep.py to delegate all worker, uncertainty-bundle, and quality-flag logic to utils/sweep_helpers.

  • Updated integration tests in tests/integration/test_script_infrastructure.py to import from utils.sweep_helpers rather than private script symbols. Added TestSweepHelpersContract class covering picklability, required return keys, and bundle schema shapes.

  • Removed deprecated system_helpers.py re-exports (ensure_results_dir, adaptive_equilibrate, etc.). All tests and Jupyter notebooks have been updated to explicitly import from utils.equilibration and utils.plotting directly.

  • Renamed run_scaling_benchmark() to main() in scripts/benchmarks/throughput.py for consistency with other analysis scripts.

  • Tests: Replaced two placeholder algorithm-integrity tests with empirical kernel tests: test_ising_detailed_balance now verifies the random-site Metropolis kernel against the exactly enumerated Boltzmann distribution of a 2x2 lattice (previously it compared the Metropolis formula against itself without calling the kernel), and test_xy_proposal_symmetry now measures the actual proposal distribution at J=0 (previously an empty pass placeholder).

  • Tests: Increased project test coverage from 63% to 75% by adding integration tests for the main() entry points of numerous analysis scripts (ordering kinetics, evolution, throughput, BKT transition, and helicity modulus).

  • Tests: Expanded coverage of utils/plotting.py by exercising optional diagnostics and error-marking paths in plot_temperature_sweep.

  • Tests: Strengthened utils/statistics.py validation by adding tests for invalid parameter ranges and edge-case physical conditions.

  • Tests: Enforced NumPy-style docstring sections and docstring presence for all public core modules in tests/style/test_docstring_style.py.

  • Raise requires-python floor from >=3.9 to >=3.12 to match Ruff, mypy, and runtime targets.

  • Add scripts/ to pytest coverage tracking (--cov=scripts) and [tool.coverage.run] source list.

  • Replace hard-coded test_results/ fixture path in tests/utility/test_system_helpers.py with tmp_path / tempfile.mkdtemp() to eliminate leaked test artifacts.

  • Update jupyter-server to 2.21.1, urllib3 to 2.8.0, anyio to 4.14.2, and virtualenv to 21.14.2 in requirements.txt and uv.lock. Replaces Dependabot PR #14, which again raised jupyterlab to 4.6 against the notebook 7.5 pin; jupyterlab stays on 4.5.

  • Update notebook to 7.6.3 and jupyterlab to 4.6.4 together. notebook 7.6 requires jupyterlab>=4.6.4,<4.7, so the two must move as a pair; Dependabot had bumped jupyterlab alone (#12, #14), which notebook 7.5 rejects. setuptools drops out of requirements.txt because only the old jupyterlab pulled it in at runtime; the build backend still fetches it in its isolated build environment.

Removed

  • .devcontainer/ (container definition, SSH-agent check, and JupyterLab auto-start). Start JupyterLab with uv run jupyter lab.

  • Remove stale notebooks/results/ directory (leftover from an older notebook version; canonical path is ../results/).

  • Remove orphaned development result directories (results/ising_n5/, results/ising_replacement_demo/, results/ising_replacement_stress/) and unreferenced test images (results/_smoke.png, results/_test.png, results/ising_simulation.png).

  • Remove test_results/ from .gitignore (no longer written by any test).

Fixed

  • test_markov_property_reproducibility could not fail: both simulations were seeded, so the per-step reseeding overwrote the manual reseeds, and the final assertion only compared two states that already differed. It now checks, for five model and update combinations, that a configuration reached along a different history evolves identically under the same random stream, and that a single changed spin changes the trajectory.

  • The stored outputs of all nine notebooks were regenerated with an empty results/ directory after the sampling and statistics fixes, and the interpretive prose was rewritten against them. Several sections had described figures that no longer matched or did not exist: the clock sweep now shows monotonic |M| and E with e = -2J in the ground state, the helicity modulus falls monotonically and crosses 2T/pi near T = 0.93 at L = 32, the Wolff comparison shows Metropolis ahead in the paramagnet, sections whose cached kinetics data is absent no longer quote fitted exponents, and relaxation times censored at the run length are reported as lower bounds. Physics statements were corrected: the 2D XY coarsening law is (t / ln t)^{1/2} with n_v ~ ln t / t, eta = T/(2 pi J) is only the low-temperature limit of T/(2 pi Upsilon_R), q = 3 and q = 4 clock models are not Ising-like, and the universal helicity jump is credited to Nelson and Kosterlitz.

  • PHYSICS.md now defines the observables it describes (it previously contained only reference sentences in section 3), states that the sweeps report the entropy relative to T_max rather than with S_ref = ln q, corrects the Wolff cluster-size scaling to xi^{gamma/nu}, and describes the blocking plateau correctly (the block-mean variance falls; the standard-error estimate rises).

  • References: the Huang citation no longer links Cardy’s CFT lectures, Bray’s coarsening review no longer links an unrelated density-functional paper, the Lapilli and Baek-Minnhagen links point to the right preprints, the Madras-Sokal pivot paper is no longer cited for critical slowing down, the q = 6 temperatures 0.68 / 0.92 are attributed to Challa and Landau rather than Jose et al., and unverified “Open Access” labels on publisher links are removed. BIBLIOGRAPHY.md gains Tomita-Okabe, Flyvbjerg-Petersen, Nightingale-Blote, Coddington-Baillie, Bray, Bray-Briant-Jervis, Baek-Minnhagen, and Challa-Landau.

  • summarize_seed_ensemble added the mean within-seed variance to the between-seed variance of the seed mean. The scatter of independent seed estimates already contains their statistical noise, so the reported error was too large by a factor near sqrt(2) when the seeds agreed (measured 1.39 for five i.i.d. seeds). It now reports the standard error of the seed mean, and the within-seed error only for a single seed.

  • The entropy error propagated from the specific-heat errors treated the two trapezoids that share a temperature point as independent, dropping their covariance; the propagated error was about 0.73 of the Monte Carlo value. Each point now enters once with the combined weight of both trapezoids.

  • tau_interval_unstable_flag compared the confidence interval of the magnetization with tau_int, two quantities in different units, so the flag carried no information. It is now computed from the seed spread of tau_int.

  • The block-bootstrap interval of the derived observables was centred on the mean of the per-block estimates, which is biased low, and could exclude the point estimate (chi = 1.115 with interval [0.937, 1.077]). The interval now places the bootstrap spread around the full-series value.

  • summarize_derived_observable raised ValueError on a NaN-containing series; it returns NaN fields like summarize_primary_observable.

  • The random and ordered starts of every two-start equilibration used the same seed. Because the per-sweep RNG streams depend only on the seed and the step, both starts drew identical random numbers and the chains coupled: at L = 16 and T = 2.0 the |m| traces of the two starts were perfectly correlated in eight of eight runs, so the cross-band test passed without the starts having relaxed independently. The ordered start now uses ordered_start_seed(seed) in the sweeps, the correlation helper, the efficiency runner, and all scripts and notebooks that pair the two starts.

  • After an accepted stuck state the sweep worker measured the random start unless the ordered start’s magnetisation exceeded it by more than 0.2, so a random start stranded at |m| = 0.75 against 0.9 was measured. The worker now always measures the ordered start after a stuck exit. scripts/xy/bkt_transition.py, scripts/xy/helicity_modulus.py, scripts/ising/measure_z.py, scripts/clock/compare_discrete_vs_continuous.py, scripts/ising/coarsening_analysis.py, and the efficiency runner always measured the random start, whatever the equilibration reported; they now measure the start the equilibration certified.

  • The notebook fallbacks of Ising_Temperature_Sweep, XY_Temperature_Sweep, Clock_Temperature_Sweep, BKT_Transition, Wolff_Efficiency, Dynamic_Critical_Exponents, and Correlation_and_Coarsening measured the random start even when the stuck detector had flagged it as stranded, which produced the unphysical low-temperature curves stored in the clock, XY, and BKT notebooks (clock |M| = 0.07 at T = 0.1, negative helicity modulus). The sweep fallbacks now call the production worker simulate_thermo_point, and the other fallbacks use prepare_equilibrated_simulation or the production helpers. The clock notebooks run the discrete model.

  • scripts/ising/coarsening_analysis.py advanced the lattice by an extra sweep before every measurement (get_averaged_correlation(total_steps=1) steps first), so recorded times were short by a factor (interval + 1) / interval: 1.2 for the quench and crossover runs, 1.5 for the ensemble. Its bridge_xi_eq was the fallback r[-1] rather than a correlation length, because the disconnected G(r) plateaus at m^2 below T_c and never crosses 1/e; it now uses the connected correlation (0.65 lattice spacings at 0.5 T_c instead of 31) and records bridge_xi_eq_method. The notebook fallbacks had the same two defects and a local correlation_length_1e without interpolation; they now use the shared helpers.

  • The parallel-scaling cell of Performance_Benchmarks timed 100 serial sweeps but divided by 50, and 50 parallel sweeps but divided by 100, which inflated the plotted speedup fourfold. Its summary table subtracted the measurement time from a sweep time that never contained it; the table now reports the kernel time, the measurement time, and their sum.

  • Ising_Relaxation_and_Autocorrelation_Analysis returned 0.5 for the autocorrelation time of a zero-variance trace; it returns NaN, as its docstring states and the zero-variance policy requires.

  • --discrete on scripts/clock/temperature_sweep.py had no effect: since the switch to point-level parallelization the flag only changed a label, and DiscreteClockSimulation was never instantiated. The flag now selects the discrete model, which is also the default.

  • Vorticity no longer has a net sign on the torus. The plaquette loop wrapped each traversal of a bond separately, and (d + pi) mod 2pi - pi sends both +pi and -pi to -pi, so an exactly antiparallel bond contributed -pi in both directions. Continuous spins never hit the tie, but in the discrete clock model with even q it is common, and a random q = 6 lattice showed mostly negative windings. Each bond is now wrapped once in its lattice direction and negated when traversed backwards, with the tie resolved to +pi, so the winding numbers sum to zero exactly.

  • Committed notebooks no longer carry per-cell execution timestamps or absolute filesystem paths in their stored outputs. Executing a notebook writes metadata.execution into every code cell, which turns a figure refresh into a diff against every cell and makes merges conflict for nothing; the setup cells also printed the repository root and an absolute cache path, publishing one contributor’s directory layout on the documentation site. The root line is dropped, the cache path is printed relative to the root, and both are held there by new guards in tests/style/test_notebook_contracts.py, each validated against the violation it exists to catch. Found by the Copilot review on the pull request, which named one absolute path; the scan behind it found five notebooks affected.

  • The notebooks on the documentation site show current figures again. The Sphinx build sets nbsphinx_execute = 'never', so the site renders whatever outputs are stored in the .ipynb files, and those had not been regenerated since before the notebooks were repaired: XY_Temperature_Sweep carried no stored outputs at all and had been rendering as bare code since April, and the two cross-model sections added in this release rendered without their figures. All nine notebooks were executed with an empty results/ directory, so the stored outputs are what a fresh checkout produces, and each one states in its own output which parameters it fell back to. The documentation build now emits sixty figures where it previously emitted far fewer, at a cost of 0.5 MB across the notebooks.

  • Wolff_Efficiency announced its inline fallback as taking two to four minutes. The whole notebook, that fallback included, executes in under ten seconds; the estimate had simply never been revisited and was about to be frozen onto the documentation site.

  • derive_point_seed could return the same seed for different grid points. Its three indices were packed into one additive expression, so a replica index of 100 reached into the next temperature’s block, and the additive stream offset shared its range with the replica axis, making replica 50 of one stream collide with replica 0 of the next. Both are a plausible flag away: --n-seeds 11 on a sweep produces replica indices up to 109, and --n-seeds 51 on measure_z puts its Wolff stream on top of the Metropolis one. The three indices now scale three nested blocks instead of being summed into a shared range, stream_offset becomes a stream_index, and an index past its block’s capacity raises rather than silently reusing a neighbour’s seeds. Verified exhaustively over 400 grid points, 1 000 replicas, and 4 streams. Found by the Copilot review on the pull request.

  • Both GitHub Actions workflows install the locked dependency set from requirements.txt instead of resolving pip install -e ".[dev]" afresh on every run. Unpinned, CI resolved numba 0.67.0 with mypy 2.3.1, where numba.prange no longer type-checks as iterable, and the type-check step failed with four errors in the model kernels; the locked set is numba 0.65.1 with mypy 2.1.0. The pre-commit hooks were already pinned this way, so a contributor’s local run and CI now check the same versions. This failure was present on master as well, with the identical four errors.

  • The test suite no longer writes into the repository’s results/ directory. Three temperature-sweep payload tests ran main() without an output directory and left a two-point, L=8, twenty-step NPZ under the production filename, and five kinetics and evolution helper tests wrote production-named PNGs there while believing they had suppressed the write by patching matplotlib.pyplot.savefig, which those helpers never call: they save through Figure.savefig and save_plot. All eight now write under tmp_path, and a session-level guard in tests/conftest.py fails the run if any test creates or modifies a file under results/, naming the files. The sweep notebooks were not misled, because they check the cached point count and fall back with a stated reason, but nothing had guaranteed that.

  • All nine notebooks were unrunnable and now execute end to end. Three independent causes: five notebooks imported the deleted utils.analysis module (pre-existing, from the statistics/observables split); seven notebooks called the equilibration helpers positionally after those became keyword-only; and Correlation_and_Coarsening imported plot_ordering_evolution_snapshots, which had been removed as unused. The latter two were introduced by this branch: the caller searches behind them covered scripts/, tests/, utils/ and models/ but not notebooks/, and no gate executed or linted notebook code. plot_ordering_evolution_snapshots is restored (now using the shared 1/e helper rather than its own copy), and the guards described above close the gap.

  • Performance_Benchmarks caught ValueError for ZeroVarianceAutocorrelationError, which derives from RuntimeError; the handler could never fire on the clock models it was written for.

  • scripts/ising/coarsening_analysis.py no longer raises NameError when --quench-fracs is passed an empty list (the saved quench_times relied on for-loop variable leakage).

  • --max-seed-attempts help text in the three temperature sweeps now says the cap applies per temperature, matching the implementation; the max(n, 10 * n) no-op around the default was simplified.

  • BIBLIOGRAPHY.md now includes the Berezinskii (1972) and Nelson & Kosterlitz (1977) references cited in notebooks/BKT_Transition.ipynb, per the Bibliography Inclusion policy.

  • run_ordering_kinetics no longer converts a legitimate fitted exponent or prefactor of exactly 0.0 into NaN in its NPZ output (falsy-zero or bug); a zero exponent is also logged again. power_fit now excludes non-positive t values before the log-log fit instead of silently corrupting it.

  • Documentation integrity: removed the verbatim duplicated ‘Sweep Worker Infrastructure’ section in CODE.md; consolidated the fragmented [Unreleased] changelog section (duplicate category headings, repeated entries, stray second [Unreleased] block); renamed the reference-policy stub heading in README.md and lowercased citation anchors so [[N]] links resolve to the bibliography on GitHub and in Sphinx; corrected stale module references to the removed utils/physics_helpers.py and utils/system_helpers.py in PHYSICS.md, models/clock_model.py, utils/plotting.py, and test docstrings; updated the utility-test-layer listing in AGENTS.md; removed SCRIPTS.md claims about nonexistent --update CLI flags, unimplemented clock entropy normalization, and unwritten tau_int_ci_* NPZ keys.

  • scripts/xy/compare_correlations.py: replaced naive fixed-step sim.equilibrate(n_steps=2000) with convergence_equilibrate_with_status and ordered-start fallback. At \(T = 0.4\) (deep BKT phase) the random-start simulation was stuck in a metastable state; the script now detects this and falls back to the ordered start. Regenerated results/xy/correlation_comparison.npz: \(G(50) \approx 0.67\) (was 0.017), fitted \(\eta \approx 0.07\) (was 0.57, theory: 0.064).

  • XY and Clock correlation plots in notebooks/Correlation_and_Coarsening.ipynb now apply an \(r \leq L/4\) cutoff to exclude periodic-boundary wrap-around artefacts, matching the established practice in the Clock plot.

  • Part I notebook prose rewritten for all three models: XY and Clock sections now state the spin-wave formula \(\eta(T) = T/(2\pi J)\) with explicit numerical predictions at the plotted temperatures (\(\eta \approx 0.064\) at \(T = 0.4\) for XY, \(\eta \approx 0.13\) at \(T = 0.8\) for Clock \(q = 6\)). Clock section specifies the exponent bounds \(4/q^2 = 1/9\) at \(T_1\) and \(1/4\) at \(T_2\). Removed stale references to the old two-panel XY layout and incorrect claim of \(\eta \approx 0.65\) from broken data.

  • Improved robustness of blocking_error and summarize_primary_observable in utils/statistics.py when handling all-NaN time series.

  • Fixed indentation in tests/style/test_docstring_style.py that caused test collection failures.

  • Fixed excessive memory allocation in wolff_step_numba across Ising, XY, and Clock models by pre-allocating the cluster mask and stack buffers once per simulation run, significantly lowering garbage collection overhead during large sweeps.

Security

  • Update tornado to 6.5.10 (security fixes in request parsing), mistune to 3.3.4, and soupsieve to 2.10 in requirements.txt and uv.lock. Replaces Dependabot PR #12, whose regenerated lockfile also raised jupyterlab to 4.6.3, which notebook 7.5.6 does not accept (jupyterlab<4.6), so pip install -r requirements.txt failed in CI.


0.1.0 - 2026-03-25

This is the baseline release capturing the full initial development history. The entries below summarize the major milestones grouped by category.

Added

  • Models: IsingSimulation, XYSimulation, ClockSimulation, and DiscreteClockSimulation with Numba-accelerated checkerboard, random-site, and Wolff cluster update schemes. Each model exposes a main() CLI entry point.

  • Equilibration: Two-Start Convergence protocol with mutual cross-band criterion and Quasi-Steady Stuck Detection for low-temperature metastable trapping. Adaptive equilibration fallback for lightweight use cases.

  • Parallelization: Granular point-level parallelization: every (T, seed) pair is an independent worker task, maximizing CPU utilization even for single-seed sweeps.

  • Uncertainty schema: Standardized NPZ contract for all temperature-sweep outputs: <obs>_value, <obs>_err, <obs>_ci_low, <obs>_ci_high, <obs>_tau_int, <obs>_n_eff, <obs>_samples, plus entropy and tau_int asymmetric interval extras. Legacy keys preserved for backward compatibility.

  • Scripts (Ising): temperature_sweep.py, ordering_kinetics.py, ordering_evolution.py, correlation_divergence.py, correlation_comparison.py, wolff_efficiency.py, measure_z.py, diag_eq_traces.py.

  • Scripts (XY): temperature_sweep.py, ordering_kinetics.py, ordering_evolution.py, bkt_transition.py, helicity_modulus.py, compare_correlations.py.

  • Scripts (Clock): temperature_sweep.py, ordering_kinetics.py, ordering_evolution.py, compare_discrete_vs_continuous.py.

  • Scripts (Benchmarks): throughput.py for cross-model scaling and per-call analysis cost profiling.

  • Notebooks: Ising_Temperature_Sweep.ipynb, Ising_Relaxation_and_Autocorrelation_Analysis.ipynb, Dynamic_Critical_Exponents.ipynb, Wolff_Efficiency.ipynb, Performance_Benchmarks.ipynb.

  • Documentation: README.md, PHYSICS.md, CODE.md, SCRIPTS.md, BIBLIOGRAPHY.md, AGENTS.md, Sphinx HTML docs with nbsphinx notebook rendering and API autodoc.

  • CI: GitHub Actions workflows for tests (tests.yml) and documentation (docs.yml). Pre-commit hooks for ruff, mypy, markdown link validation, API docs sync, Sphinx build, and docstring style.

  • Seed management: Deterministic seeding for full reproducibility of all stochastic trajectories.

  • Transition presets, diagnostics overlays, and quality summary panels for temperature-sweep plots.

  • Entropy uncertainty via replicate aggregation, block-bootstrap, and single-seed propagation from specific-heat errors.

  • Hierarchical multi-seed uncertainty combining within-seed blocking error with between-seed spread.

Changed

  • Refactored utils/analysis.py into utils/statistics.py (domain-agnostic statistical estimators and schemas) and utils/observables.py (physics observables and spatial tools).

  • ordering_kinetics scripts unified and refactored; renamed from domain_growth.

  • ordering_evolution scripts unified from earlier domain_snapshots.

  • Test suite reorganized from a flat layout into five layer directories: algorithm/, model/, utility/, style/, integration/.

  • Equilibration and plotting logic extracted from utils/system_helpers.py into dedicated utils/equilibration.py and utils/plotting.py modules; re-exports maintained in system_helpers.py for backward compatibility.

  • Numba JIT (@njit(cache=True, fastmath=True)) on all simulation kernels; parallel=True + prange on checkerboard kernels.

  • Pre-calculated neighbor index arrays (idx_next, idx_prev) replace modulo for periodic boundary conditions.

  • Discrete state representation for Clock models replaces per-site trigonometric evaluations with lookup tables (~2.5x speedup).

  • Vectorized angle extraction for vorticity calculation; radial mask pre-computation for correlation functions.

Fixed

  • Diagnostics header/title overlap in temperature-sweep diagnostic plots.

  • Restored notebook JSON after corruption; ensured stuck-detection prose and figures are consistent.

  • Low-temperature sweep relaxation logic now correctly accepts stable ordered starts as converged.

  • Default --eq-max-steps lowered from 200,000 to 20,000 to prevent excessively long equilibration runs.