Scripts Catalog: VibeSpin

VibeSpin provides a suite of entry-point scripts for conducting physics experiments. These are organized by model family in the scripts/ directory.

1. Ising Model (scripts/ising/)

  • temperature_sweep.py: Conducts a full thermodynamic sweep across a range of temperatures. Reports \(|M|\), \(E\), \(\chi\), \(C_v\), entropy \(S(T)\) from \(C_v/T\) integration, and integrated autocorrelation time \(\tau_{\mathrm{int}}\). Supports --n-seeds for seeded ensembles and uncertainty controls including --confidence-level, --derived-uncertainty-method, --derived-bootstrap-resamples, --entropy-uncertainty-method, and --entropy-bootstrap-resamples. Convergence diagnostics can be tuned via --eq-qs-sigma-threshold and --eq-qs-min-steps to detect and stop early on low-temperature stuck states. Strict quality control is available via --strict-uncertainty with threshold controls for undefined and unstable points. For n_seeds=1, primary and derived observables use single-trajectory blocking, while entropy uncertainty falls back to propagation from the specific-heat uncertainty. For n_seeds>1, uncertainty combines between-seed spread and within-seed blocking error. Saves a standardized NPZ file results/ising/temperature_sweep_data.npz containing both legacy scalar arrays and per-observable uncertainty schema keys (<obs>_value, <obs>_err, <obs>_ci_low, <obs>_ci_high, <obs>_tau_int, <obs>_n_eff, <obs>_samples) plus additive extras (entropy_* and per-temperature quality flags). The plotting output is split into a thermodynamics summary figure and a companion diagnostics figure, where entropy and \(\tau_{\mathrm{int}}\) intervals are shown as ribbons and unavailable uncertainty is marked explicitly.

  • diag_eq_traces.py: Generates a 4x6 diagnostic visualization of two-start equilibration traces (random vs. ordered start) covering 6 representative seeds across 4 temperatures. Pre-screens seeds at low temperature to identify and highlight trajectories that become stuck in metastable states (marked with a star). The script also produces a detailed 2x3 panel for \(T=2.00\) showing mutual cross-bands and automatic convergence markers for each seed. Results are saved as PNG figures in the output directory.

  • ordering_kinetics.py: Quenches the system to \(T < T_c\) and tracks the growth of domain size \(R(t)\) over time. Supports --seeds N and --base-seed for multi-seed ensemble averaging with IQR-based error bars. Saves per-seed arrays and median trajectory to results/ising/ordering_kinetics.npz.

  • ordering_evolution.py: Generates visual snapshots of the lattice configuration, structure factor, and correlation functions during a quench.

  • correlation_divergence.py: Extracts the critical exponent \(\nu\) by fitting the correlation length divergence near \(T_c\). --seed (default 0) selects a reproducible seed per temperature. The error of each \(\xi\) comes from fitting 16 contiguous blocks of correlation samples separately; the NPZ adds xi_value, xi_err, xi_ci_low, xi_ci_high (Student-t interval around the full-run fit), xi_tau_int and xi_n_eff (NaN, undefined for a fitted length), xi_samples, and the schema metadata.

  • correlation_comparison.py: Compares the functional form of \(G(r)\) in the ferromagnetic, critical, and paramagnetic phases. Uses two-start convergence equilibration (--eq-probe, --eq-max) with a --seed flag for reproducible runs, matching the XY and Clock correlation scripts. Each temperature is fitted with the form it is expected to take: the anomalous dimension \(\eta\) at \(T_c\), where the exact value is \(1/4\), and the correlation length \(\xi\) above it. Saves results/ising/correlation_comparison.npz including eta_crit and xi_para.

  • coarsening_analysis.py: Precomputes supplementary coarsening analyses for the Correlation_and_Coarsening.ipynb notebook: quench-depth sensitivity (3 temperatures, multi-seed), a comparison of the coarsening length with the equilibrium correlation length \(\xi_{\mathrm{eq}}\) (from the connected correlation function, stored with bridge_xi_eq_method; below \(T_c\) it is a fraction of a lattice spacing, and the domains grow far beyond it), and a stochastic ensemble (8 seeds) visualizing run-to-run variability. Saves all data to results/ising/coarsening_analysis.npz.

  • wolff_efficiency.py: Compares the Metropolis checkerboard and Wolff cluster algorithms across the critical regime. Reports integrated autocorrelation time \(\tau_{\mathrm{int}}\), independent samples per second (ISS), mean cluster size fraction \(\langle C \rangle/N^2\), and susceptibility \(\chi(T)\) for both algorithms. Both receive the same budget in sweep units: Metropolis records one sample per sweep, Wolff one sample every \(\mathrm{round}(L^2/\langle C \rangle)\) cluster flips, with tau_wolff still reported in cluster flips. The XY and clock variants share this runner. The NPZ files add wolff_flips_per_sample, converged_metro, and converged_wolff, and for every reported quantity the standardized <key>_value, _err, _ci_low, _ci_high (seed median and 16-84 % band), _tau_int and _n_eff (NaN), plus bootstrap_resamples. Saves results to results/ising/wolff_efficiency.npz for re-use by notebooks/Wolff_Efficiency.ipynb and a 4-panel summary figure to results/ising/wolff_efficiency.png.

  • measure_z.py: Specifically measures the dynamical critical exponent \(z\) at the critical temperature \(T_c\). Sweeps lattice sizes \(L\) to extract the scaling law \(\tau_{\mathrm{int}} \propto L^z\) for both Metropolis and Wolff algorithms. Runs --n-seeds independent replicas per (algorithm, \(L\)) point and saves per-seed sample arrays alongside median and 16–84% percentile summaries to results/ising/dynamic_exponent_z.npz for use in notebooks/Dynamic_Critical_Exponents.ipynb. The NPZ also includes standardized uncertainty keys (tau_metro_value, tau_metro_err, tau_metro_ci_low, tau_metro_ci_high, and Wolff equivalents).

2. XY Model (scripts/xy/)

  • temperature_sweep.py: Standard thermodynamic sweep for continuous vector spins, including \(|M|\), \(E\), \(\chi\), \(C_v\), entropy \(S(T)\), and integrated autocorrelation time \(\tau_{\mathrm{int}}\). Supports --n-seeds with the same single-seed blocking, entropy fallback propagation, multi-seed hierarchical uncertainty behavior, uncertainty-control CLI options, and --eq-qs-* stuck-detection flags as the Ising sweep, plus per-temperature quality flags. Saves results/xy/temperature_sweep_data.npz with the same standardized uncertainty schema and additive extras as the Ising sweep, along with separate thermodynamics and diagnostics figures for clearer uncertainty visualization.

  • ordering_kinetics.py: Quenches to \(T < T_{BKT}\) and tracks the decay of vortex density and the growth of the correlation length. Supports --seeds N and --base-seed for multi-seed ensemble averaging with IQR-based error bars.

  • ordering_evolution.py: Visual snapshots including phase maps and vorticity configurations during ordering.

  • bkt_transition.py: Specifically focuses on the BKT transition by measuring average vortex density vs. temperature. --seed (default 0) selects a reproducible seed per temperature; each point runs its two starts to convergence without stuck detection. A point whose starts never agree within --eq-max-steps is stored as NaN, and the NPZ key equilibrated marks the points that were measured. The NPZ adds the standardized blocking fields vortex_density_value, _err, _ci_low, _ci_high, _tau_int, _n_eff, _samples and the schema metadata next to the legacy vortex_densities.

  • helicity_modulus.py: Calculates the superfluid stiffness to identify the universal jump at \(T_{BKT}\). Seeding and equilibration as in bkt_transition.py. Upsilon is the mean of the per-sweep quantity \((\sum\cos - (\sum\sin)^2/T)/L^2\), so the NPZ adds blocking fields helicity_modulus_value, _err, _ci_low, _ci_high, _tau_int, _n_eff, _samples with the schema metadata.

  • wolff_efficiency.py: Compares the Wolff-Evertz cluster reflection against the Metropolis checkerboard across the BKT window, reporting work-normalised \(\tau_{\mathrm{int}}\), independent samples per second, mean cluster fraction, and the susceptibility agreement that validates both samplers. Saves results/xy/wolff_efficiency.npz.

  • correlation_comparison.py: Contrasts power-law decay (topological order) with exponential decay (disordered phase). Renamed from compare_correlations.py to match its Ising and Clock siblings. Reports the fitted anomalous dimension below \(T_{\mathrm{BKT}}\) alongside the spin-wave prediction \(\eta = T/(2\pi J)\), and the correlation length above it, as eta_low, eta_low_spin_wave, and xi_high.

3. Clock Model (scripts/clock/)

The clock scripts run the discrete clock model (DiscreteClockSimulation) by default. temperature_sweep.py, correlation_comparison.py, ordering_kinetics.py, and ordering_evolution.py accept --continuous to run planar spins with the anisotropy \(-A\cos(q\theta)\) instead, with its strength set by --aniso (default 1.0 for the sweep and the correlation comparison, 0.5 for the two kinetics scripts). --aniso without --continuous is rejected, and --discrete is accepted as an explicit spelling of the default. The approximate \(q=6\) crossover temperatures belong to the discrete model, so the sweep omits their overlay for the continuous one.

  • temperature_sweep.py: Thermodynamic sweep for the q-state clock model (--q, default 6), including \(|M|\), \(E\), \(\chi\), \(C_v\), entropy \(S(T)\), a --transition-preset overlay marking the approximate \(q=6\) crossover temperatures, and integrated autocorrelation time \(\tau_{\mathrm{int}}\). Supports --n-seeds with the same single-seed blocking, entropy fallback propagation, multi-seed hierarchical uncertainty behavior, uncertainty-control CLI options, and --eq-qs-* stuck-detection flags as the Ising sweep, plus per-temperature quality flags. For the discrete model the ordered start replaces a stranded random start below the lowest ordering temperature, as in the Ising sweep (exact for \(q = 2, 3, 4\), \(T_1 \approx 0.68\) for \(q = 6\), disabled for other \(q\)). Saves results/clock/temperature_sweep_data.npz with the same standardized uncertainty schema and additive extras as the Ising sweep, along with separate thermodynamics and diagnostics figures for clearer uncertainty visualization.

  • ordering_kinetics.py: Analyzes the ordering dynamics after a quench. Supports --seeds N and --base-seed for multi-seed ensemble averaging with IQR-based error bars.

  • ordering_evolution.py: Visualizes the evolution of discrete phase domains.

  • wolff_efficiency.py: The clock counterpart of the Ising and XY efficiency comparisons, spanning both \(q=6\) crossovers. It runs on the discrete model, whose Wolff update reflects clusters about the \(q\) mirror axes and therefore satisfies detailed balance for the full clock Hamiltonian. The continuous model offers no such comparison: its cluster update ignores the anisotropy and is only valid at \(A = 0\), where the model is the XY model. Saves results/clock/wolff_efficiency.npz.

  • correlation_comparison.py: Compares the functional form of \(G(r)\) in the ordered (\(T < T_1\)), quasi-ordered (\(T_1 < T < T_2\)), and disordered (\(T > T_2\)) phases of the \(q = 6\) clock model. Uses convergence equilibration, and reports the fitted anomalous dimension of the quasi-ordered phase against the same spin-wave prediction the XY model obeys there, plus the correlation length above \(T_2\), as eta_quasi, eta_quasi_spin_wave, and xi_disordered. The default temperatures 0.5, 0.8, and 1.2 bracket the transitions of the discrete \(q = 6\) model only; with --continuous or another \(q \ge 5\) the three temperatures must be given via --t-ordered, --t-quasi, and --t-disordered. Saves results/clock/correlation_comparison.npz.

  • compare_discrete_vs_continuous.py: Provides a side-by-side performance and physical comparison between the continuous (XY + anisotropy, strength via --aniso) and discrete implementations. Supports --seed for reproducible sweeps and --log-file like the other clock scripts.

4. Cross-Model Benchmarking (scripts/benchmarks/)

  • throughput.py: Cross-model throughput and scaling benchmark. Measures sweeps/s, ns/site, and per-call analysis costs (thermodynamic, \(G(r)\), vorticity, helicity) across all eight model variants and a range of lattice sizes. Saves a 6-panel summary figure to results/benchmarks/scaling_benchmark.png and all metrics to results/benchmarks/scaling_benchmark.npz. The NPZ file is loaded by notebooks/Performance_Benchmarks.ipynb to avoid re-running the benchmark on every notebook execution.

5. Regenerating All Data (scripts/generate_all.py)

  • generate_all.py: Runs every script that a notebook reads data from, in one command, and reports what it produced and how long each step took. Without arguments each script runs at its own production defaults, which is the data the published figures are built from and takes roughly an hour on four cores. --quick runs the same eighteen scripts at sharply reduced lattices and step counts, which exercises the whole pipeline in about a minute but produces output that is not physics. --only and --skip select by substring of the model/script key, --list prints the table, --dry-run prints the commands, --skip-existing leaves present files alone, and --fail-fast stops at the first failure instead of reporting all of them at the end. A failing run exits non-zero, so the command works as a build step. The set of datasets it covers is held to the pipeline table below by tests/integration/test_generate_all.py, so a new data-producing script cannot be added to one without the other.

Usage Guidelines

Update Schemes

As mandated in AGENTS.md, each script hardcodes the physically appropriate update scheme:

  • Kinetics scripts (ordering_kinetics.py, ordering_evolution.py, coarsening analyses) use random site selection, the only scheme valid for time-dependent studies.

  • Sweep scripts (temperature_sweep.py and related equilibrium tools) use checkerboard updates for maximum equilibrium throughput.

  • wolff_efficiency.py and measure_z.py additionally run the Wolff cluster algorithm, which reduces \(\tau_{\mathrm{int}}\) by an order of magnitude near \(T_c\) and improves the ISS rate proportionally. See notebooks/Wolff_Efficiency.ipynb for a quantitative demonstration.

  • Only the model main() entry points (python -m models.ising_model etc.) expose an --update CLI flag for direct experimentation.

Results

All scripts save their output (plots and data files) to the results/ directory, sub-divided by model and experiment type. The three correlation comparisons run their temperatures across the worker pool, so their wall time is set by the slowest single temperature rather than by their sum.

Production Defaults and Notebook Fallbacks

Scripts and notebooks serve different goals, so their parameters differ deliberately. Script defaults favour data quality: the three temperature sweeps now run 60 temperature points with 20 000 measurement steps and 5 seed replicas (Ising and XY at L=64, Clock at L=48), which is what makes the hierarchical between-seed uncertainty meaningful; with the previous single-seed default no between-seed component existed at all. A full sweep takes roughly 3 minutes (Ising), 11 minutes (XY) and 16 minutes (Clock) on four cores.

Notebook fallbacks favour responsiveness: they run only when the cached NPZ is absent and are sized so a reader never waits on a seemingly frozen cell. Each sweep fallback completes in well under a minute and still resolves the transition; the notebooks print the lattice size and step count they used, so a fallback figure is never mistaken for production data.

Data Pipeline

python -m scripts.generate_all regenerates every entry in this table at once; the sections above describe running an individual script.

Scripts serve a dual role: they generate cached NPZ data files for notebooks and produce quick-check PNG figures for immediate visual verification. Notebooks are the curated presentation layer and load precomputed NPZ files to avoid re-running expensive simulations. When NPZ data is absent, notebooks provide lightweight fallback computations for demonstration purposes.

The table below maps each script to its data output and the notebook(s) that consume it. Scripts marked “figure only” produce PNG visualizations but no cached data; their analyses are reproduced inline within notebooks at small system sizes when needed.

Script

NPZ Output

Consuming Notebook(s)

Ising

scripts/ising/temperature_sweep.py

results/ising/temperature_sweep_data.npz

Ising_Temperature_Sweep.ipynb, Ising_Relaxation_and_Autocorrelation_Analysis.ipynb

scripts/ising/measure_z.py

results/ising/dynamic_exponent_z.npz

Dynamic_Critical_Exponents.ipynb

scripts/ising/wolff_efficiency.py

results/ising/wolff_efficiency.npz

Wolff_Efficiency.ipynb

scripts/ising/correlation_comparison.py

results/ising/correlation_comparison.npz

Correlation_and_Coarsening.ipynb

scripts/ising/correlation_divergence.py

results/ising/correlation_divergence.npz

Correlation_and_Coarsening.ipynb

scripts/ising/ordering_kinetics.py

results/ising/ordering_kinetics.npz

Correlation_and_Coarsening.ipynb

scripts/ising/coarsening_analysis.py

results/ising/coarsening_analysis.npz

Correlation_and_Coarsening.ipynb

scripts/ising/diag_eq_traces.py

(figure only)

—

scripts/ising/ordering_evolution.py

(figure only)

—

XY

scripts/xy/temperature_sweep.py

results/xy/temperature_sweep_data.npz

XY_Temperature_Sweep.ipynb

scripts/xy/bkt_transition.py

results/xy/bkt_transition.npz

BKT_Transition.ipynb

scripts/xy/helicity_modulus.py

results/xy/helicity_modulus.npz

BKT_Transition.ipynb

scripts/xy/wolff_efficiency.py

results/xy/wolff_efficiency.npz

Wolff_Efficiency.ipynb

scripts/xy/correlation_comparison.py

results/xy/correlation_comparison.npz

BKT_Transition.ipynb, Correlation_and_Coarsening.ipynb

scripts/xy/ordering_kinetics.py

results/xy/ordering_kinetics.npz

Correlation_and_Coarsening.ipynb

scripts/xy/ordering_evolution.py

(figure only)

—

Clock

scripts/clock/temperature_sweep.py

results/clock/temperature_sweep_data.npz

Clock_Temperature_Sweep.ipynb

scripts/clock/ordering_kinetics.py

results/clock/ordering_kinetics.npz

Correlation_and_Coarsening.ipynb

scripts/clock/wolff_efficiency.py

results/clock/wolff_efficiency.npz

Wolff_Efficiency.ipynb

scripts/clock/correlation_comparison.py

results/clock/correlation_comparison.npz

Correlation_and_Coarsening.ipynb

scripts/clock/ordering_evolution.py

(figure only)

—

scripts/clock/compare_discrete_vs_continuous.py

(figure only)

—

Benchmarks

scripts/benchmarks/throughput.py

results/benchmarks/scaling_benchmark.npz

Performance_Benchmarks.ipynb