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.pyadds the missingbootstrap_resamplesandnan_or_undefined_count, andtau_metro_tau_int,tau_metro_n_eff,tau_wolff_tau_int, andtau_wolff_n_effas NaN, since a seed-ensemble summary of autocorrelation times has no autocorrelation time of its own. The sharedbuild_single_run_schemainutils/sweep_helpers.pyassembles the fields for single-run sweeps.The temperature sweeps write
tau_int_ci_lowandtau_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.pycheck 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.pygainsconvergence_equilibrate_two_start, which returns aTwoStartOutcomekeeping 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; andprepare_equilibrated_simulation, which bundles the three.convergence_equilibrate_with_statuskeeps its signature and meaning.connected_correlation_lengthinutils/observables.pymeasures the equilibrium correlation length from the connected pair correlation, with the mean spin of each configuration subtracted.--seedonscripts/xy/bkt_transition.py,scripts/xy/helicity_modulus.py, andscripts/ising/correlation_divergence.py(default 0, a replica index intoderive_point_seed); all three were unseeded. Their NPZ files recordseed_index.The Wolff efficiency NPZ files add
wolff_flips_per_sample,converged_metro, andconverged_wolff(additive).DiscreteClockSimulationsupportsupdate='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.pychecks 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_lengthandfit_correlation_exponenthelpers inutils/observables.py. Previously only the Ising script fitted anything, and only the correlation length. The scripts addeta_crit(Ising, against the exact 1/4),eta_low,eta_low_spin_wave,xi_high(XY), andeta_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 sharedutils/efficiency_runner.py. Both models had cluster updates and neither had the measurement that says when to use them. The clock comparison runsDiscreteClockSimulation, 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.ipynbgains 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.ipynbgains 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--discretewould 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--quickfor 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.pynow 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): everyutils/modelsimport 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 previousextend-exclude = ["*.ipynb"]hid them), with prose-layout rules disabled for notebook cells.The three temperature-sweep NPZ files now record
sizeandmeas_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.--seedflag on the threeordering_evolution.pyscripts (previously unseeded, so the figures were not reproducible); default remains unseeded.--n-seedsaccepted as the canonical spelling on the threeordering_kinetics.pyscripts, aligning with the temperature sweeps; the existing--seedsspelling keeps working.--xi-eq-probe,--xi-eq-max,--xi-eq-steps, and--xi-eq-intervalflags onscripts/ising/coarsening_analysis.py, replacing four hardcoded equilibrium-measurement parameters.New shared
simulate_equilibrium_correlationhelper inutils/observables.py, replacing the near-verbatim duplicated per-model workers of the three correlation-comparison scripts.scripts/ising/correlation_comparison.pythereby gains two-start convergence equilibration and a--seedflag (previously unseeded with fixed-step burn-in, the weakest methodology of its triplet); its--eq-stepsflag is replaced by--eq-probe/--eq-max.New shared
derive_point_seedhelper inutils/sweep_helpers.py; the three temperature sweeps,measure_z.py, andwolff_efficiency.pyuse it instead of five inline copies of the seed-spacing formula (values unchanged).--eq-qs-sigma-thresholdand--eq-qs-min-stepsstuck-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-fileflags; runs are now reproducible and the anisotropy is no longer hardcoded.scripts/benchmarks/throughput.py: project-standard logging with--verboseand--log-file(previously bareprint).scripts/ising/wolff_efficiency.pyNPZ output now carriesuncertainty_method(replicate_percentile),confidence_level, andnan_or_undefined_countmetadata (additive).All three temperature sweeps now write the
n_seedsandbootstrap_resamplesNPZ metadata keys required by the uncertainty schema contract; the Clock sweep additionally writesentropy_uncertainty_method(previously Ising/XY only). Existing keys are preserved (additive change).New shared
validate_sweep_uncertainty_argshelper inutils/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_samplesinutils/statistics.pynow returns anerrfield (half the percentile band width) so replicate summaries conform to the standard uncertainty schema. This fixes aKeyErrorcrash inscripts/ising/measure_z.pythat occurred at NPZ save time, after the full sweep had completed.New
UNCERTAINTY_METHOD_REPLICATEconstant ('replicate_percentile').scripts/ising/measure_z.pynow labels its NPZuncertainty_methodmetadata truthfully instead of claiming'blocking'.ClockSimulationemits aUserWarningwhenupdate='wolff'is combined with a non-zero anisotropyA: the Wolff-Evertz reflection ignores the anisotropy term, so detailed balance is exact only forA=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. Savesresults/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. Savesresults/ising/coarsening_analysis.npz.Multi-seed ensemble support in
utils/kinetics_helpers.run_ordering_kinetics: newn_seedsandbase_seedparameters 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.pyscripts (Ising, XY, Clock) now accept--seedsand--base-seedCLI arguments for multi-seed runs.Generated
results/xy/correlation_comparison.npz(\(L = 128\)) from existingscripts/xy/compare_correlations.py.Part II of
notebooks/Correlation_and_Coarsening.ipynbnow 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.ipynbnow 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.ipynbnow 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_pathparameter inutils/kinetics_helpers.run_ordering_kineticsfor persisting kinetics data. All three ordering_kinetics scripts now save NPZ output.Data Pipeline mapping table in
SCRIPTS.mddocumenting 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. Exportscompute_mean_intercept_length(stereological domain-size estimator for scalar-spin lattices) andrun_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. Exportsrun_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. ExportsThermoPoint(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, andbuild_quality_flags.
Changed
Breaking:
parallel=Truewith the checkerboard update raisesValueErroron 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 theprangeloop could update them concurrently. The serial checkerboard sweep remains valid for odd L. Migration: use an even L, orparallel=False.Confidence intervals built on a blocking error use the Student-t quantile with
n_blocks - 1degrees 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 withn_seeds - 1degrees 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_lowand<obs>_ci_highper point).Breaking (NPZ values): a zero-variance window now yields NaN for
err,ci_low, andci_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 throughundefined_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_wolffstays in cluster flips, sotau_wolff_normkeeps its meaning. Cachedwolff_efficiency.npzfiles should be regenerated.scripts/clock/correlation_comparison.pyapplies its default temperatures (0.5, 0.8, 1.2) only to the discrete q = 6 model. For--continuousor another q, whose T1 and T2 differ,--t-ordered,--t-quasi, and--t-disorderedare required,q < 5is rejected because it has no quasi-ordered phase, and the storedT1andT2are 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:
equilibratedin the helicity-modulus and BKT outputs,metro_equilibratedandwolff_equilibratedindynamic_exponent_z.npz, the existingconverged_metroandconverged_wolffin the Wolff efficiency outputs, andbridge_xi_eq_equilibratedincoarsening_analysis.npz. The correlation comparisons store an all-NaN G(r) for such a point, andcompare_discrete_vs_continuous.pyplots a gap.TwoStartOutcome.certifiedtells callers whether a measurement is valid. Migration: check the new flags, or drop NaN points, when reading these files.scripts/xy/correlation_comparison.pyraises the--eq-maxdefault 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_startis opt-in (detect_stuck=Falseby default);convergence_equilibrate_with_statusandconvergence_equilibratekeep 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 ofcompare_discrete_vs_continuous.py, and the coarsening analysis.simulate_equilibrium_correlation,CorrelationPoint,EfficiencyPoint, andrun_wolff_efficiencygain a matching opt-in (detect_stuckorstuck_below), and the ordering temperatures of the discrete clock model move toscripts/clock/_model_choice.pyasORDERED_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 themodels/clock_model.pyexample CLI run the discrete clock model by default. Previously the sweep and the Wolff comparison ranClockSimulationatA = 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.--continuousrestores a continuous run, with--anisodefaulting to 1.0 (sweep, correlation comparison, example CLI) or 0.5 (kinetics, evolution), and--anisowithout--continuousis 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. Cachedresults/clock/*.npzfiles 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')raisesValueErrorforA != 0instead of warning. The cluster update ignores the anisotropy, so the chain sampled the XY model under a clock label; with the constructor defaultA = 1.0this was the outcome of the plain--update wolffflag of the example CLI. Migration: passA=0.0explicitly for an XY-equivalent run, or useDiscreteClockSimulation(update='wolff').Breaking: all simulation classes reject a negative or non-finite coupling
JwithValueError. The Metropolis tables and the Wolff bond probability assume ferromagnetic exchange; withJ < 0the 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 = 0remains 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.lockis now the single source of truth for dependencies: both CI workflows install withuv sync --locked --all-extras, andrequirements.txtis exported fromuv.lockby a pre-commit hook for pip users. A CI step fails if the two files disagree, which closes the gap that letuv.lockkeep pillow 12.2.0 and bleach 6.3.0 afterrequirements.txthad moved on. A new.python-versionpins 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/HEADrather thanblob/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 intodocs/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_Coarseningnow 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_sizesmoves fromIsingSimulationtoMonteCarloSimulation. 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.pynames its entry pointmain, 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.pyaso2_wolff_step_numba, replacing the byte-identicalxy_wolff_step_numbaandclock_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 theClockSimulationwarning 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 carrystrict=True, so parallel arrays cannot silently desynchronise.Docstring format unified repo-wide to numpydoc: every Parameters/Returns/Raises section across
models/,utils/, andscripts/now uses the standardname : typeentry 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 insweep_helpers,measure_z, andwolff_efficiencywere converted); log output is unchanged._propagate_entropy_uncertainty_from_cv_errorsreplaces 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.pyis renamed toscripts/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_loggingcan attach a file handler on a later call: previously the first call withoutlog_filepermanently 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_autocorrcomputes the power spectrum as a real array and normalizes only the lags it consumes (up tomax_lag) instead of the full series length;summarize_entropy_observablebuilds its result dict through a single helper; the chi/Cv fluctuation formulas live once inutils.observables.derived_thermo_estimate, shared bycalculate_thermodynamicsand the derived-observable summarizer.Docstring completeness:
blocking_error,estimate_effective_sample_size,summarize_primary_observable,summarize_derived_observable,summarize_replicate_samples, andsummarize_asymmetric_replicate_uncertaintynow 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-presetsemantics 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 byscripts/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.pyandwolff_efficiency.pyderive their median and 16-84 percentile envelopes from the sharedsummarize_replicate_samplesinstead of duplicated inline helpers (numerically identical).Script cleanups: the runtime
assertinscripts/clock/correlation_comparison.pyis now an explicitRuntimeError; the duplicatednp.savez_compressedblocks and'xi' in locals()control flow in the Ising correlation scripts are replaced by a single kwargs dict with explicitNonechecks;scripts/ising/diag_eq_traces.pycaches its T=2.00 traces instead of re-simulating them for the detail figure; all scripts useparse_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_observableandsummarize_derived_observableaccept optional precomputedblocking/tau_intinputs; newestimate_tau_int_or_nanhelper.summarize_derived_observablealso gains anrng_seedparameter for its block-bootstrap (default 0 preserves the previous stream).convergence_equilibrate_with_statusspaces 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_plotaccepts an explicitfigand acloseflag; 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, andcalculate_correlation_functiononMonteCarloSimulation, pluscalculate_vorticity,get_vortex_density, andget_helicity_datavia a newVectorSpinObservablesMixinon 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, andcompute_mean_intercept_length; all call sites (scripts, tests, notebooks) updated.blocking_errornow 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_evolutionraisesRuntimeErrorinstead of silently skipping a snapshot when the lattice is uninitialized;run_ordering_kineticsvalidatesmax_steps,samples,fit_min, andn_seedsbefore computing step targets.New shared
correlation_length_1ehelper inutils/observables.pyreplaces three divergent inline copies of the 1/e-crossing interpolation (kinetics metrics and two plot helpers),plot_ordering_evolution_snapshotsamong them.docs/check_markdown_links.pynow validates intra-document anchors (#fragment) against heading slugs in both same-file and cross-file links, and gains an opt-in--externalmode that probes external URLs over the network. The Sphinx configuration no longer suppressesmyst.xref_missing, so dead internal cross-references now fail the-Wdocs build.docs/generate_api_docs.pyincludesscripts.benchmarksin 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 usingseed + step. Previously, seedsat sweept + 1consumed exactly the same random stream as seeds + 1at sweept, so replicas seeded with consecutive integers (thebase_seed + kconvention) 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, andlast_cluster_sizeis now initialized on all models inMonteCarloSimulation(previously Ising-only).build_uncertainty_bundlesingle-seed path now applies the Gaussian z-multiplier for the requested confidence level toci_low/ci_high(previously fixed at plus/minus one standard error regardless ofconfidence).README.mddocuments 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 theparallelparameter.Updated pre-commit hook versions to match the locked project environment:
ruff-pre-commitv0.15.0 → v0.15.13 andmirrors-mypyv1.18.2 → v2.1.0. The mypy hook’sadditional_dependenciesare now pinned to the versions fromrequirements.txt, fixing spuriousprangeiteration 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.jsonpostCreateCommand to globally installuvand useuv sync --all-extrasfor deterministic environment provisioning.Pinned and locked all direct and transitive dependencies into
uv.lock.Regenerated standard
requirements.txtusinguv pip compileto ensure backward compatibility.Updated
README.mdto recommenduv syncanduv runcommands 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 fromresults/ising/coarsening_analysis.npzwith 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_stepsreduced from 1000 to 400,samplesincreased from 10 to 25,fit_minreduced from 20 to 5. The regeneratedresults/ising/ordering_kinetics.npzyields 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:tempchanged from 0.1 to 0.5 (well below \(T_{\mathrm{BKT}} \approx 0.893\), better vortex mobility),max_stepsincreased to 1500,samplesincreased to 30,fit_minreduced 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.npzandresults/clock/ordering_kinetics.npzwith new parameters (L=256, T=0.50). The exponent comparison table innotebooks/Correlation_and_Coarsening.ipynbnow shows all three models with finite, physically meaningful values instead of NaN.Regenerated
results/ising/correlation_comparison.npzwith \(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_correlationsfunction innotebooks/Correlation_and_Coarsening.ipynbupdated 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 onmodels.simulation_base.MonteCarloSimulationwith a structuralProtocolclass_Sim, eliminating the utils-to-models import cycle.Refactored
scripts/ising/ordering_kinetics.py,scripts/xy/ordering_kinetics.py, andscripts/clock/ordering_kinetics.pyto delegate the full simulation loop, power-law fitting, and figure generation toutils/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, andscripts/clock/ordering_evolution.pyto delegate the snapshot loop and figure generation toutils/evolution_helpers.run_ordering_evolution. Vorticity capture is controlled by thecapture_vorticityflag (True for XY and Clock, False for Ising).Refactored
scripts/ising/temperature_sweep.py,scripts/xy/temperature_sweep.py, andscripts/clock/temperature_sweep.pyto delegate all worker, uncertainty-bundle, and quality-flag logic toutils/sweep_helpers.Updated integration tests in
tests/integration/test_script_infrastructure.pyto import fromutils.sweep_helpersrather than private script symbols. AddedTestSweepHelpersContractclass covering picklability, required return keys, and bundle schema shapes.Removed deprecated
system_helpers.pyre-exports (ensure_results_dir,adaptive_equilibrate, etc.). All tests and Jupyter notebooks have been updated to explicitly import fromutils.equilibrationandutils.plottingdirectly.Renamed
run_scaling_benchmark()tomain()inscripts/benchmarks/throughput.pyfor consistency with other analysis scripts.Tests: Replaced two placeholder algorithm-integrity tests with empirical kernel tests:
test_ising_detailed_balancenow 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), andtest_xy_proposal_symmetrynow measures the actual proposal distribution at J=0 (previously an emptypassplaceholder).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.pyby exercising optional diagnostics and error-marking paths inplot_temperature_sweep.Tests: Strengthened
utils/statistics.pyvalidation 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-pythonfloor from>=3.9to>=3.12to 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 intests/utility/test_system_helpers.pywithtmp_path/tempfile.mkdtemp()to eliminate leaked test artifacts.Update
jupyter-serverto 2.21.1,urllib3to 2.8.0,anyioto 4.14.2, andvirtualenvto 21.14.2 inrequirements.txtanduv.lock. Replaces Dependabot PR #14, which again raisedjupyterlabto 4.6 against thenotebook7.5 pin;jupyterlabstays on 4.5.Update
notebookto 7.6.3 andjupyterlabto 4.6.4 together. notebook 7.6 requiresjupyterlab>=4.6.4,<4.7, so the two must move as a pair; Dependabot had bumpedjupyterlabalone (#12, #14), whichnotebook7.5 rejects.setuptoolsdrops out ofrequirements.txtbecause only the oldjupyterlabpulled 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 withuv 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_reproducibilitycould 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_ensembleadded 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_flagcompared the confidence interval of the magnetization withtau_int, two quantities in different units, so the flag carried no information. It is now computed from the seed spread oftau_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_observableraisedValueErroron a NaN-containing series; it returns NaN fields likesummarize_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, andCorrelation_and_Coarseningmeasured 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 workersimulate_thermo_point, and the other fallbacks useprepare_equilibrated_simulationor the production helpers. The clock notebooks run the discrete model.scripts/ising/coarsening_analysis.pyadvanced 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. Itsbridge_xi_eqwas the fallbackr[-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 recordsbridge_xi_eq_method. The notebook fallbacks had the same two defects and a localcorrelation_length_1ewithout interpolation; they now use the shared helpers.The parallel-scaling cell of
Performance_Benchmarkstimed 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_Analysisreturned 0.5 for the autocorrelation time of a zero-variance trace; it returns NaN, as its docstring states and the zero-variance policy requires.--discreteonscripts/clock/temperature_sweep.pyhad no effect: since the switch to point-level parallelization the flag only changed a label, andDiscreteClockSimulationwas 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 - pisends both+piand-pito-pi, so an exactly antiparallel bond contributed-piin 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.executioninto 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 intests/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.ipynbfiles, and those had not been regenerated since before the notebooks were repaired:XY_Temperature_Sweepcarried 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 emptyresults/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_Efficiencyannounced 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_seedcould 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 11on a sweep produces replica indices up to 109, and--n-seeds 51onmeasure_zputs 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_offsetbecomes astream_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.txtinstead of resolvingpip install -e ".[dev]"afresh on every run. Unpinned, CI resolved numba 0.67.0 with mypy 2.3.1, wherenumba.prangeno 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 onmasteras well, with the identical four errors.The test suite no longer writes into the repository’s
results/directory. Three temperature-sweep payload tests ranmain()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 patchingmatplotlib.pyplot.savefig, which those helpers never call: they save throughFigure.savefigandsave_plot. All eight now write undertmp_path, and a session-level guard intests/conftest.pyfails the run if any test creates or modifies a file underresults/, 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.analysismodule (pre-existing, from the statistics/observables split); seven notebooks called the equilibration helpers positionally after those became keyword-only; andCorrelation_and_Coarseningimportedplot_ordering_evolution_snapshots, which had been removed as unused. The latter two were introduced by this branch: the caller searches behind them coveredscripts/,tests/,utils/andmodels/but notnotebooks/, and no gate executed or linted notebook code.plot_ordering_evolution_snapshotsis restored (now using the shared 1/e helper rather than its own copy), and the guards described above close the gap.Performance_BenchmarkscaughtValueErrorforZeroVarianceAutocorrelationError, which derives fromRuntimeError; the handler could never fire on the clock models it was written for.scripts/ising/coarsening_analysis.pyno longer raisesNameErrorwhen--quench-fracsis passed an empty list (the savedquench_timesrelied on for-loop variable leakage).--max-seed-attemptshelp text in the three temperature sweeps now says the cap applies per temperature, matching the implementation; themax(n, 10 * n)no-op around the default was simplified.BIBLIOGRAPHY.mdnow includes the Berezinskii (1972) and Nelson & Kosterlitz (1977) references cited innotebooks/BKT_Transition.ipynb, per the Bibliography Inclusion policy.run_ordering_kineticsno longer converts a legitimate fitted exponent or prefactor of exactly 0.0 into NaN in its NPZ output (falsy-zeroorbug); a zero exponent is also logged again.power_fitnow excludes non-positivetvalues 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 inREADME.mdand lowercased citation anchors so[[N]]links resolve to the bibliography on GitHub and in Sphinx; corrected stale module references to the removedutils/physics_helpers.pyandutils/system_helpers.pyinPHYSICS.md,models/clock_model.py,utils/plotting.py, and test docstrings; updated the utility-test-layer listing inAGENTS.md; removedSCRIPTS.mdclaims about nonexistent--updateCLI flags, unimplemented clock entropy normalization, and unwrittentau_int_ci_*NPZ keys.scripts/xy/compare_correlations.py: replaced naive fixed-stepsim.equilibrate(n_steps=2000)withconvergence_equilibrate_with_statusand 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. Regeneratedresults/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.ipynbnow 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_errorandsummarize_primary_observableinutils/statistics.pywhen handling all-NaN time series.Fixed indentation in
tests/style/test_docstring_style.pythat caused test collection failures.Fixed excessive memory allocation in
wolff_step_numbaacross 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
tornadoto 6.5.10 (security fixes in request parsing),mistuneto 3.3.4, andsoupsieveto 2.10 inrequirements.txtanduv.lock. Replaces Dependabot PR #12, whose regenerated lockfile also raisedjupyterlabto 4.6.3, whichnotebook7.5.6 does not accept (jupyterlab<4.6), sopip install -r requirements.txtfailed 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, andDiscreteClockSimulationwith Numba-accelerated checkerboard, random-site, and Wolff cluster update schemes. Each model exposes amain()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 andtau_intasymmetric 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.pyfor 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.pyintoutils/statistics.py(domain-agnostic statistical estimators and schemas) andutils/observables.py(physics observables and spatial tools).ordering_kineticsscripts unified and refactored; renamed fromdomain_growth.ordering_evolutionscripts unified from earlierdomain_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.pyinto dedicatedutils/equilibration.pyandutils/plotting.pymodules; re-exports maintained insystem_helpers.pyfor backward compatibility.Numba JIT (
@njit(cache=True, fastmath=True)) on all simulation kernels;parallel=True+prangeon 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-stepslowered from 200,000 to 20,000 to prevent excessively long equilibration runs.