spin_sim/lib.rs
1//! Pure-Rust Ising and XY Monte Carlo on periodic lattices.
2//!
3//! XY uses [`XySimulation`] and [`XyConfig`] with signed couplings, vector spins,
4//! physical moments and the shared scheduling, cluster and tempering engine.
5//!
6//! # Algorithms
7//!
8//! | Move | Function |
9//! |------|----------|
10//! | Metropolis / Gibbs sweep | [`run_sweep_loop`] (`sweep_mode`) |
11//! | Wolff / Swendsen-Wang | [`run_sweep_loop`] (`cluster_update`) |
12//! | Parallel tempering | [`run_sweep_loop`] (`pt_interval`) |
13//! | Houdayer / pairN / Jörg / CMR / permN / gpermN / replica Monte Carlo | [`run_sweep_loop`] (`overlap_cluster`) |
14//!
15//! Replicas are parallelized over threads with [`rayon`].
16//! Multiple disorder realizations can be run in parallel with [`run_sweep_parallel`].
17//!
18//! # Quick start
19//!
20//! ```
21//! use spin_sim::config::*;
22//! use spin_sim::{Lattice, Realization, run_sweep_loop};
23//!
24//! let lattice = Lattice::new(vec![16, 16]);
25//! let n_spins = lattice.n_spins;
26//! let n_neighbors = lattice.n_neighbors;
27//! let temps = vec![2.0, 2.27, 2.5];
28//!
29//! // Uniform ferromagnetic couplings
30//! let couplings = vec![1.0f32; n_spins * n_neighbors];
31//! let mut real = Realization::new(&lattice, couplings, &temps, 2, 42);
32//!
33//! let config = SimConfig {
34//! n_sweeps: 5000,
35//! warmup_sweeps: 1000,
36//! sweep_mode: SweepMode::Metropolis,
37//! cluster_update: Some(ClusterConfig {
38//! interval: 1,
39//! mode: ClusterMode::Wolff,
40//! action: ClusterAction::Update,
41//! collect_stats: false,
42//! }),
43//! pt_interval: Some(1),
44//! pt_schedule: PtSchedule::SingleRandomEdge,
45//! overlap_cluster: None,
46//! autocorrelation_max_lag: None,
47//! autocorrelation_backend: AutocorrelationBackend::Ring,
48//! sequential: false,
49//! equilibration_diagnostic: false,
50//! conditional_link_overlap: true,
51//! };
52//!
53//! use std::sync::atomic::AtomicBool;
54//! let interrupted = AtomicBool::new(false);
55//! let result = run_sweep_loop(
56//! &lattice, &mut real, 2, temps.len(), &config, &interrupted, &|| {}, 0,
57//! ).unwrap();
58//! ```
59//!
60//! For a Python interface, see the [`peapods`](https://pypi.org/project/peapods/) package.
61
62pub mod config;
63pub mod geometry;
64pub mod simulation;
65pub mod spins;
66pub mod statistics;
67
68mod clusters;
69mod mcmc;
70mod parallel;
71#[cfg(test)]
72mod test_utils;
73
74pub use geometry::Lattice;
75pub use simulation::{run_sweep_loop, run_sweep_parallel, Realization};
76pub use statistics::{
77 ClusterObservations, ClusterSnapshot, ClusterStats, Diagnostics, EquilCheckpoint,
78 GraphObservationSummary, SweepResult,
79};
80
81pub use simulation::realization::{ModelRealization, XyRealization};
82pub use simulation::xy::{XyConfig, XyResult, XySimulation};