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, perf → Performance, refactor → Changed, docs → Documentation, phys → Physics, test → Tests, chore → Chores.

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

Added

  • 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.

Changed

  • 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.

Added

  • 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.

Changed

  • 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.

Fixed

  • 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.

Added

  • 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.

Changed

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

Added

  • 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

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

  • 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.

Performance

  • 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.

Changed

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

  • 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.

Fixed

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

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

Test

  • 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).

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

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

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

Chores

  • 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.

  • 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).

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.

Performance

  • 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.

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.

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.

Unreleased

Refactored

  • utils/analysis.py has been split into utils/statistics.py (domain-agnostic statistical estimators and NPZ schemas) and utils/observables.py (physics observables and spatial analysis) to separate concerns and improve maintainability without introducing subfolders.