peapods: A Rust-Accelerated Monte Carlo Package for Ising and XY Spin Systems
Listen
Radio episode about this paper
Transcript
Introduction to the show: ident: Condensed Matter. The day in condensed matter: materials, phases and the measurements under them.
Kai: We're looking at the paper: "peapods: A Rust-Accelerated Monte Carlo Package for Ising and XY Spin Systems".
Mira: Here's the gist of the paper. peapods presents an open-source Python package for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets <ref:2602.19045#pg2> The computational core is written in Rust and exposed to Python via PyO3 <ref:2602.19045#pg5> This package implements Metropolis
3: and Gibbs single-spin-flip algorithms, Swendsen–Wang
4: and Wolff
5: cluster updates, parallel tempering
6: , and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster move
7: , the J¨org stochastic variant
8: , and the Chayes–Machta–Redner (CMR) blue-bond algorithm
9: <ref:2602.19045#pg2> Overlap statistics between replica pairs enable computation of the spin glass order parameter and Binder ratio <ref:2602.19045#pg4> Replica-level parallelism is achieved through the Rayon
10: workstealing scheduler <ref:2602.19045#pg2>.
Kai: Model Definition and Geometry The Ising Hamiltonian under consideration is defined as H = −X Σ⟨i,j⟩ Jij σiσj, where σi ∈ (−1, +1) are the spin variables <ref:2602.19045#pg3> The lattice geometry is fully general, allowing users to specify neighbor offsets as integer displacement vectors <ref:2602.19045#pg4> Hypercubic lattices use unit vectors along each axis, while triangular and FCC lattices have predefined forward neighbor directions <ref:2602.19045#pg4>.
Mira: The coupling constants Jij can be specified as an arbitrary user-provided array or via built-in distributions such as Ferromagnetic, Bimodal, or Gaussian <ref:2602.19045#pg4>.
Kai: The package simulates R independent replicas across a parallel tempering ladder to study spin glasses <ref:2602.19045#pg4>.
Title and authors: Kai: So, this paper is called "peapods: A Rust-Accelerated Monte Carlo Package for Ising and XY Spin Systems." It's basically a Python package that lets you run Monte Carlo simulations on Ising spin systems.
Mira: And it's interesting because the core computational part is written in Rust, which means it has compiled performance and memory safety, but you can use it through a Python interface called PyO3.
Lev: From my side, I always think about how much overhead you have to manage when you try to run these kinds of simulations on real hardware.
Kai: Yeah, so what makes this package stand out is that it lets you do Ising simulations with arbitrary coupling constants and even XY spin systems.
The paper's summary: Mira: The abstract says they present peapods as an open-source Python package for Monte Carlo simulation of Ising spin systems on periodic Bravais lattices with user-specified neighbor offsets.
Kai: And the big deal is that they implement a whole suite of algorithms, including Metropolis and Gibbs single-spin-flip updates, Swendsen–Wang and Wolff cluster updates.
Lev: That's a lot of work to implement efficiently, especially getting those cluster algorithms right for arbitrary lattices.
Mira: Plus they include parallel tempering for spin glasses—that’s the part where things get really interesting—and three replica cluster moves for spin glasses like the Houdayer isoenergetic cluster move and the CMR blue-bond algorithm.
The paper's improvements: Kai: They focus on making sure you can define your lattice geometry fully generally by letting users specify neighbor offsets as integer displacement vectors.
Mira: And they highlight that the package is currently focused on spin glass simulation, which means they are digging into how parallel tempering and replica overlap statistics work together for spin glasses.
Lev: What I'm interested in from an engineering standpoint is how they manage the memory allocation, since you can't afford to reallocate buffers every single time you take a step in a simulation.
Kai: Yeah, so they use Rayon for replica-level parallelism, which helps speed things up across different temperatures.
Conclusion: Mira: So to wrap up this paper, peapods gives researchers a way to simulate Ising and XY spin systems with customizable lattices and coupling constants using a fast Rust core exposed via Python.
Kai: It really makes the process of setting up complex simulations much easier because you get all these advanced algorithms like the Houdayer move for spin glasses in one package.
Lev: For real hardware, this means you have to make sure your simulation setup can actually utilize that parallelism from Rayon effectively, or it just becomes another bottleneck.
Kai: Exactly. So this paper shows how you can build a robust tool for these systems by combining the speed of Rust with the usability of Python.
cond-mat.stat-mech, physics.comp-ph
Submitted: 2026-02-22
Updated: 2026-11-11
Comments: 18 pages, 2 figures, 4 tables. v4 describes peapods 0.3.0: adds the XY model, new replica cluster moves, boundary conditions, diagnostics and validation against the 3D +-J spin glass and the 2D XY model; lists bugs in earlier versions that biased results; corrects the equilibration diagnostic of v3. Code: https://github.com/PeaBrane/peapods (tag v0.3.0)
Code: https://github.com/PeaBrane/peapods
License: http://creativecommons.org/licenses/by/4.0/
Importance score: 87/100
The gist: peapods presents an open-source Python package for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets…
Key concepts
- Ising Hamiltonian
- This defines the energy of a system of spins ($\sigma_i$) on a lattice. It is calculated by summing interactions ($J_{ij}$) between neighboring spins. The goal is to simulate how these spins settle into different configurations based on this energy function.
- Cluster Updates (Swendsen–Wang, Wolff)
- These are advanced Monte Carlo methods that propose changes to many neighboring spins simultaneously rather than one by one. They use a representation called the Fortuin–Kasteleyn model to identify correlated groups of spins, which significantly speeds up simulations and reduces the time needed to explore different states.
- Spin Glass Order Parameter (Overlap $q$)
- For disordered spin glasses, this measures how similar two independent simulations (replicas) are by comparing their spin configurations. A high overlap indicates that the systems are in a similar state, which is used to determine if a true spin glass transition has occurred.
Terminology
Summary
peapods presents an open-source Python package for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets <ref:2602. p. 0 com
Abstract
We present peapods [1] (github. com/PeaBrane/peapods), an open-source Python package
for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets. com/PeaBrane/peapods), an open-source Python package
for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. com/PeaBrane/peapods), an open-source Python package
for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. com/PeaBrane/peapods), an open-source Python package
for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9]. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler. Overlap statistics between replica pairs enable computation of the spin glass order
parameter and Binder ratio. Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Model Definition and Geometry
The Ising Hamiltonian under consideration is defined as H = −X Σ⟨i,j⟩ Jij σiσj, where σi ∈ (−1, +1) are the spin variables <ref:2602.19045#pg3> The lattice geometry is fully general, allowing users to specify neighbor offsets as integer displacement vectors <ref:2602. p. 1 clean Python interface for model construction, analysis, and visualization. The lattice geometry is
fully general: users specify neighbor offsets as integer displacement vectors, enabling simulation on
hypercubic, triangular, FCC, and other Bravais lattices. L×L) and a set of n integer
offset vectors specifying the forward neighbor directions; hypercubic lattices use unit vectors along
each axis (n = d), while the triangular lattice uses offsets {(1, 0),(0, 1),(1, −1)} (n = 3, coordination
z = 6). The FCC lattice uses six forward offsets (n = 6, coordination z = 12) and the BCC lattice
uses four forward offsets (n = 4, coordination z = 8); both are available as named presets via the
geometry parameter alongside triangular and hypercubic. The couplings can be specified as an
arbitrary user-provided array of shape (lattice shape, n), or via one of three built-in distributions:
• Ferromagnetic: Jij = 1 for all bonds. • Bimodal: Jij ∈ {−1, +1} with equal probability (the ±J spin glass). The package simulates R independent replicas, each consisting of a full parallel tempering ladder
across temperatures T1 < T2 < · · · < TK, giving R × K total systems. Multiple replicas at the
same temperature enable replica cluster moves and the computation of overlap statistics for spin
glass order parameters.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Algorithmic Toolkit
The package provides a comprehensive set of Monte Carlo algorithms for efficient sampling <ref:2602.19045#pg5> Single-spin-flip updates include Metropolis and Gibbs algorithms, which use local fields computed on-the-fly <ref:2602. p. 2 The local field hi
is computed on-the-fly
from both forward and backward neighbors in each lattice dimension. 2 Cluster updates
Cluster algorithms exploit the Fortuin–Kasteleyn representation [18] to build correlated clusters of
spins and flip them collectively, dramatically reducing autocorrelation times near Tc. 2 Cluster updates
Cluster algorithms exploit the Fortuin–Kasteleyn representation [18] to build correlated clusters of
spins and flip them collectively, dramatically reducing autocorrelation times near Tc. Swendsen–Wang. 3 Parallel tempering
Parallel tempering [6] improves ergodicity by allowing replicas at different temperatures to exchange
configurations. At each tempering step, a random adjacent pair (Tk, Tk+1) is selected and a swap
is accepted with probability
Pswap = min1, e∆
, ∆ = N(Ek+1 − Ek)
1
Tk
−
1
Tk+1
, (3)
where Ek is the average energy per spin of the replica currently at temperature Tk and N is the total
number of spins. The computational core is written in
Rust and exposed to Python via PyO3 [2], combining the ergonomic interface of Python with
the performance of compiled, memory-safe code. The package implements Metropolis [3] and
Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel
tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster
move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9].Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Spin Glass Order Parameters
For spin glass systems, the relevant order parameter is the overlap between replica pairs defined as q = 1/N ΣΣi=1σ(a)iσ(b)i <ref:2602.19045#pg6> The link overlap provides a complementary bond-level measure of replica similarity, ql = 1/Nb Σ⟨i,j⟩σ(a)iσ(a)jσ(b)iσ(b)j <ref:2602. p. 3 5 Overlap statistics
For spin glass systems, the relevant order parameter is the overlap between replica pairs:
q =
1
N
X
N
i=1
σ
(a)
i
σ
(b)
i
. (4)
The link overlap provides a complementary bond-level measure of replica similarity:
ql =
1
Nb
X
⟨i,j⟩
σ
(a)
i
σ
(a)
j
σ
(b)
i
σ
(b)
j
, (5)
where Nb is the number of bonds. can be used for finite-size scaling analysis of the spin glass transition, analogously to the ferromagnetic Binder cumulant. The crossing of g(T) for different system sizes locates the critical
temperature Tc [19]. Additionally, the full overlap histogram P(q) is accumulated per temperature, enabling analysis of the
overlap distribution and replica symmetry breaking. 6 Cluster size distributions
During Swendsen–Wang and Wolff cluster updates, the package collects Fortuin–Kasteleyn cluster
size histograms ns(T), where ns counts the number of clusters of size s.Where the paper says it
Where the paper says it
Where the paper says it
Validation and Performance Gains
The implementation is validated against exact critical temperatures of the two-dimensional Ising model on both square and triangular lattices using finite-size scaling of the Binder cumulant <ref:2602.19045#pg8> The package avoids overhead by placing the entire sampling loop in compiled Rust code, which offers competitive performance with C while ensuring strong memory safety <ref:2602. p. 6 All four sizes cross near U ≈ 0. 6 Performance
By moving the entire sampling loop to compiled Rust code, the package avoids the overhead inherent in Python-level Monte Carlo implementations, including per-sweep temporary array allocations,
interpreter dispatch in tight loops, and the cost of Python-level iteration over replicas for cluster updates. The Rust backend additionally benefits from precomputed neighbor tables (eliminating peraccess modular arithmetic), Rayon work-stealing parallelism across replicas, and the Xoshiro256**
generator which is substantially faster than NumPy’s default RNG for scalar draws. Together,
these yield significant speedups over equivalent Python/NumPy implementations, particularly for
cluster algorithms where per-temperature Python loops are the bottleneck. 8 Conclusion
We have presented peapods, a Monte Carlo simulation package for Ising spin systems that combines
a Python interface with a Rust computational backend. The package implements the standard
toolkit of Metropolis, Gibbs, Swendsen–Wang, Wolff, and parallel tempering algorithms, three
replica cluster moves for spin glasses (Houdayer ICM, J¨org, and CMR with proper two-phase
blue/red/grey construction), site and link overlap statistics with full overlap histograms for spin
glass order parameters, cluster size distributions, equilibration diagnostics [20], integrated autocorrelation times [21], and support for arbitrary Bravais lattice geometries—including predefined FCC
8Where the paper says it
Where the paper says it
Where the paper says it
Usage and Future Directions
The Python interface is designed for simplicity, allowing users to define models using parameters like lattice shape, couplings, and temperatures <ref:2602.19045#pg9> The package supports arbitrary Bravais lattice geometries via the neighbor offsets parameter <ref:2602. p. 7 equilibration_delta()
tau = sg. mags2_tau # integrated autocorrelation time
The package supports arbitrary Bravais lattice geometries via the neighbor offsets parameter
(defaulting to hypercubic when omitted) and all three coupling types. Several directions for future work are planned:
• Generalized spin models: extending beyond Ising (Z2) spins to support q-state Potts, Zq
clock, and continuous O(N) models, including their disordered variants. • Cluster algorithms for frustrated systems: implementing algorithms such as the KBD
algorithm that extend cluster updates to systems with competing interactions where standard
Swendsen–Wang and Wolff methods are inapplicable. The implementation
is validated against exact 2D Ising critical points on both the square and triangular lattices. The
package is open-source and available on PyPI. The implementation
is validated against exact 2D Ising critical points on both the square and triangular lattices. The
package is open-source and available on PyPI.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
References
[1] Yan Ru Pei. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. p. 0 peapods: A Rust-Accelerated Monte Carlo Package
for Ising Spin Systems
Yan Ru Pei
yanrpei@gmail. com
Abstract
We present peapods [1] (github. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https:
//github. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https:
//github. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https:
//github. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https:
//github. https:
//github. com/PeaBrane/peapods, 2026.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
[2] PyO3 Project Contributors. PyO3: Rust bindings for the Python interpreter. p. 8 [2] PyO3 Project Contributors. PyO3: Rust bindings for the Python interpreter. https://
github. com/PyO3/pyo3, 2025.Where the paper says it
Where the paper says it
[3] Nicholas Metropolis, Arianna W. Rosenbluth, Marshall N. p. 8 [3] Nicholas Metropolis, Arianna W. Rosenbluth, Marshall N. Rosenbluth, Marshall N. Rosenbluth, Augusta H. Rosenbluth, Augusta H. Teller, and
Edward Teller. Teller, and
Edward Teller. Equation of state calculations by fast computing machines. Equation of state calculations by fast computing machines. The Journal of
Chemical Physics, 21(6):1087–1092, 1953.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
[4] Robert H. Swendsen and Jian-Sheng Wang. p. 8 [4] Robert H. Swendsen and Jian-Sheng Wang. Swendsen and Jian-Sheng Wang. Nonuniversal critical dynamics in Monte Carlo
simulations. Nonuniversal critical dynamics in Monte Carlo
simulations. Physical Review Letters, 58(2):86–88, 1987.Where the paper says it
Where the paper says it
Where the paper says it
[5] Ulli Wolff. Collective Monte Carlo updating for spin systems. p. 8 [5] Ulli Wolff. Collective Monte Carlo updating for spin systems. Collective Monte Carlo updating for spin systems. Physical Review Letters,
62(4):361–364, 1989.Where the paper says it
Where the paper says it
[6] Koji Hukushima and Koji Nemoto. Exchange Monte Carlo method and application to spin glass simulations. p. 8 [6] Koji Hukushima and Koji Nemoto. Exchange Monte Carlo method and application to spin
glass simulations. Exchange Monte Carlo method and application to spin
glass simulations. Journal of the Physical Society of Japan, 65(6):1604–1608, 1996.Where the paper says it
Where the paper says it
[7] J. Houdayer. A cluster Monte Carlo algorithm for 2-dimensional spin glasses. p. 8 Journal of the Physical Society of Japan, 65(6):1604–1608, 1996. A cluster Monte Carlo algorithm for 2-dimensional spin glasses. A cluster Monte Carlo algorithm for 2-dimensional spin glasses. The European
Physical Journal B, 22:479–484, 2001.Where the paper says it
Where the paper says it
[8] Thomas J¨org. Cluster Monte Carlo algorithms for diluted spin glasses. p. 8 [8] Thomas J¨org. Cluster Monte Carlo algorithms for diluted spin glasses. Cluster Monte Carlo algorithms for diluted spin glasses. Progress of Theoretical
Physics Supplement, 157:349–352, 2005.Where the paper says it
Where the paper says it
[9] Oliver Redner, Jon Machta, and Lincoln Chayes. Graphical representations and cluster algorithms for critical points with fields. p. 8 [9] Oliver Redner, Jon Machta, and Lincoln Chayes. Graphical representations and cluster algorithms for critical points with fields. Graphical representations and cluster algorithms for critical points with fields. Physical Review E, 62:8114–8125, 2000.Where the paper says it
Where the paper says it
[10] Josh Stone and Niko Matsakis. Rayon: A data parallelism library for Rust. p. 8 [10] Josh Stone and Niko Matsakis. Rayon: A data parallelism library for Rust. https://github. com/rayon-rs/rayon, 2025.Where the paper says it
Where the paper says it
[11] Lars Onsager. Crystal statistics. p. 8 [11] Lars Onsager. Crystal statistics. Crystal statistics. A two-dimensional model with an order-disorder transition. A two-dimensional model with an order-disorder transition. Physical Review, 65(3–4):117–149, 1944.Where the paper says it
Where the paper says it
Where the paper says it
[12] Gregory H. Wannier. Antiferromagnetism. p. 8 [12] Gregory H. Antiferromagnetism. Antiferromagnetism. The triangular Ising net. The triangular Ising net. Physical Review,
79(2):357–364, 1950.Where the paper says it
Where the paper says it
Where the paper says it
[13] R. M. F. Houtappel. Order-disorder in hexagonal lattices. p. 8 Physical Review,
79(2):357–364, 1950. Order-disorder in hexagonal lattices. Order-disorder in hexagonal lattices. Physica, 16(5):425–455, 1950.Where the paper says it
Where the paper says it
[14] K. Binder. Finite size scaling analysis of Ising model block distribution functions. p. 9 Finite size scaling analysis of Ising model block distribution functions. Zeitschrift
f¨ur Physik B Condensed Matter, 43:119–140, 1981. Finite size scaling analysis of Ising model block distribution functions. Zeitschrift
f¨ur Physik B Condensed Matter, 43:119–140, 1981.Where the paper says it
Where the paper says it
[15] S. F. Edwards and P. p. 0 Despite
its simplicity—binary spins on a lattice coupled by nearest-neighbor interactions—it exhibits rich
critical phenomena and serves as a testbed for Monte Carlo algorithms. In the disordered-coupling
case, it becomes the Edwards–Anderson spin glass [15], one of the central problems in condensed
matter physics. Edwards and P. Theory of spin glasses. Theory of spin glasses. Journal of Physics F: Metal
Physics, 5:965–974, 1975.Where the paper says it
Where the paper says it
Where the paper says it
[16] Konstantin Bauer and Maturin Contributors. Maturin: Build and publish crates with PyO3 bindings as Python packages. p. 9 [16] Konstantin Bauer and Maturin Contributors. Maturin: Build and publish crates with PyO3
bindings as Python packages. https://github. com/PyO3/maturin, 2025.Where the paper says it
Where the paper says it
[17] B. Bauer, L. D. Carr, H. G. Evertz, A. Feiguin, J Freire, S Fuchs, L Gamper, J Gukelberger, E Gull, S Guertler, A Hehn <ref:2602. p. 9 Feiguin, J. Gukelberger,
E.Where the paper says it
[18] C. M. Fortuin and P. p. 2 The local field hi
is computed on-the-fly
from both forward and backward neighbors in each lattice dimension. 2 Cluster updates
Cluster algorithms exploit the Fortuin–Kasteleyn representation [18] to build correlated clusters of
spins and flip them collectively, dramatically reducing autocorrelation times near Tc. Fortuin and P. On the random-cluster model: I. On the random-cluster model: I. Introduction and relation
to other models. Introduction and relation
to other models. Physica, 57:536–564, 1972.Where the paper says it
Where the paper says it
Where the paper says it
Where the paper says it
[19] M. Baity-Jesi et al. p. 9 Physica, 57:536–564, 1972. Baity-Jesi et al. Baity-Jesi et al. Critical parameters of the three-dimensional Ising spin glass. Critical parameters of the three-dimensional Ising spin glass. Physical
Review B, 88:224416, 2013.Where the paper says it
Where the paper says it
Where the paper says it
[20] Zheng Zhu, Andrew J Ochoa, and Helmut G Katzgraber. Efficient cluster algorithm for spin glasses in any space dimension. p. 9 Katzgraber. Efficient cluster algorithm for spin
glasses in any space dimension. Efficient cluster algorithm for spin
glasses in any space dimension. Physical Review Letters, 115:077201, 2015.Where the paper says it
Where the paper says it
[21] Alan D. Sokal. Monte Carlo methods in statistical mechanics: Foundations and new algorithms. p. 9 [21] Alan D. Monte Carlo methods in statistical mechanics: Foundations and new algorithms. Monte Carlo methods in statistical mechanics: Foundations and new algorithms. In Functional Integration: Basics and Applications, NATO ASI Series. In Functional Integration: Basics and Applications, NATO ASI Series. Springer, 1997.Where the paper says it
Where the paper says it
Where the paper says it
--- Page 1 ---
peapods presents an open-source Python package for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets <ref:2602.19045#pg2> The computational core is written in Rust and exposed to Python via PyO3 <ref:2602.19045#pg5> This package implements Metropolis [3] and Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9] <ref:2602.19045#pg2> Overlap statistics between replica pairs enable computation of the spin glass order parameter and Binder ratio <ref:2602.19045#pg4> Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler <ref:2602.19045#pg2>.
--- Page 2 ---
The lattice geometry is fully general, enabling simulation on hypercubic, triangular, FCC, and other Bravais lattices <ref:2602.19045#pg4> While the package supports general Ising systems, active development is currently focused on spin glass simulation <ref:2602. p. 1 The lattice geometry is
fully general: users specify neighbor offsets as integer displacement vectors, enabling simulation on
hypercubic, triangular, FCC, and other Bravais lattices. While the package supports general Ising
systems, active development is currently focused on spin glass simulation, where the interplay of
parallel tempering, replica overlap cluster moves, and overlap statistics is of particular interest.Where the paper says it
--- Page 3 ---
Metropolis and Gibbs algorithms are implemented to propose spins based on energy change comparisons <ref:2602.19045#pg5> Cluster algorithms exploit the Fortuin–Kasteleyn representation to build correlated clusters of spins and flip them collectively <ref:2602. p. 2 The local field hi
is computed on-the-fly
from both forward and backward neighbors in each lattice dimension. 2 Cluster updates
Cluster algorithms exploit the Fortuin–Kasteleyn representation [18] to build correlated clusters of
spins and flip them collectively, dramatically reducing autocorrelation times near Tc. 3 Parallel tempering
Parallel tempering [6] improves ergodicity by allowing replicas at different temperatures to exchange
configurations. At each tempering step, a random adjacent pair (Tk, Tk+1) is selected and a swap
is accepted with probability
Pswap = min1, e∆
, ∆ = N(Ek+1 − Ek)
1
Tk
−
1
Tk+1
, (3)
where Ek is the average energy per spin of the replica currently at temperature Tk and N is the total
number of spins. 8 Conclusion
We have presented peapods, a Monte Carlo simulation package for Ising spin systems that combines
a Python interface with a Rust computational backend. The package implements the standard
toolkit of Metropolis, Gibbs, Swendsen–Wang, Wolff, and parallel tempering algorithms, three
replica cluster moves for spin glasses (Houdayer ICM, J¨org, and CMR with proper two-phase
blue/red/grey construction), site and link overlap statistics with full overlap histograms for spin
glass order parameters, cluster size distributions, equilibration diagnostics [20], integrated autocorrelation times [21], and support for arbitrary Bravais lattice geometries—including predefined FCC
8Where the paper says it
Where the paper says it
Where the paper says it
--- Page 3 ---
The Houdayer isoenergetic cluster move restricts to the negative-overlap sites N = 1/N Σi≠σ(a)i and activates all bonds deterministically (probability 1) <ref:2602.19045#pg5>. This move is always accepted with no Metropolis test, and the cluster growth is temperature-independent <ref:2602. p. 3 This exchange is isoenergetic: because every bond crossing
the cluster boundary connects a site inside N (where the replicas disagree) to a site outside N
(where they agree), the local field at each boundary site is unchanged. The move is always accepted
with no Metropolis test, and the cluster growth is temperature-independent, which is particularly
valuable at low temperatures where single-spin-flip moves freeze out. J¨org move. J¨org [8] proposed a refinement for three-dimensional systems where Houdayer clusters can span the lattice. The eligible subgraph is the same (negative-overlap sites), but bonds are
activated stochastically with probability p = 1−e
−4Jijσ
(a)
i
σ
(a)
j
/T on satisfied bonds (Jijσ
(a)
i
σ
(a)
j > 0),
breaking up system-spanning clusters into smaller pieces. The Chayes–Machta–Redner (CMR) algorithm [9] uses a two-phase construction
based on a decomposition of the joint Boltzmann weight of two replicas.Where the paper says it
Where the paper says it
Where the paper says it
--- Page 3 ---
Sites in blue clusters are intentionally flipped in both phases, and the composition of the blue and grey flips is the correct update in the CMR graphical representation <ref:2602.19045#pg5>.
--- Page 3 ---
For spin glass systems, the relevant order parameter is q = 1/N ΣΣi=1σ(a)iσ(b)i <ref:2602.19045#pg6> The link overlap provides a complementary bond-level measure of replica similarity <ref:2602. p. 3 5 Overlap statistics
For spin glass systems, the relevant order parameter is the overlap between replica pairs:
q =
1
N
X
N
i=1
σ
(a)
i
σ
(b)
i
. (4)
The link overlap provides a complementary bond-level measure of replica similarity:
ql =
1
Nb
X
⟨i,j⟩
σ
(a)
i
σ
(a)
j
σ
(b)
i
σ
(b)
j
, (5)
where Nb is the number of bonds.Where the paper says it
--- Page 3 ---
The package computes ⟨q⟩, ⟨q 2⟩, and ⟨q 4⟩ over the measurement sweeps for each consecutive replica pair at each temperature <ref:2602.19045#pg6> From these, the spin glass Binder ratio g = 1 − ⟨q 4⟩ / 3⟨q 2⟩ squared can be used for finite-size scaling analysis of the spin glass transition <ref:2602. p. 4 can be used for finite-size scaling analysis of the spin glass transition, analogously to the ferromagnetic Binder cumulant. The crossing of g(T) for different system sizes locates the critical
temperature Tc [19]. The crossing of g(T) for different system sizes locates the critical
temperature Tc [19]. The analogous Binder ratio for the link overlap ql
is also computed.Where the paper says it
Where the paper says it
--- Page 3 ---
During Swendsen–Wang and Wolff cluster updates, the package collects Fortuin–Kasteleyn cluster size histograms ns(T) to compute the susceptibility-weighted mean cluster size <ref:2602.19045#pg8> which serves as a diagnostic for the onset of critical behavior <ref:2602. p. 4 Similarly, overlap cluster
size histograms are collected during replica cluster moves. From these, the susceptibility-weighted
mean cluster size
⟨s⟩ =
P
s
s
2
P
ns
s
s ns
(7)
can be computed, which diverges at the percolation threshold and serves as a diagnostic for the
onset of critical behavior. [20], we compute the equilibration diagnostic
∆(t) = e(t) + ⟨J
2
⟩ βz 1 − ql(t)
, (8)
where e(t) is the running average energy per spin, ql(t) is the running average link overlap, β = 1/T,
and z is the coordination number. The quantity ∆ vanishes identically in thermal equilibrium, so
∆(t) → 0 signals that equilibration has been achieved. Integrated autocorrelation time τint. Autocorrelation times quantify how many sweeps are
needed to obtain an independent sample.Where the paper says it
Where the paper says it
Where the paper says it
--- Page 4 ---
The architecture follows a mixed Rust/Python layout built with Maturin [16] <ref:2602.19045#pg9> The central Rust struct is IsingSimulation, which owns spin configurations and coupling constants <ref:2602. p. 5 The central Rust struct is IsingSimulation, exposed to Python as a PyO3 pyclass. It owns:
• A flat Vec<i8> of all spin configurations across replicas (R × N entries). 3 Parallelism
All replicas are independent conditioned on the temperature assignment, so single-spin-flip sweeps,
energy computations, and cluster updates are trivially parallelizable across replicas. We use
Rayon’s [10] work-stealing thread pool via a shared par over replicas helper that dispatches
a closure over replicas in parallel.Where the paper says it
Where the paper says it
--- Page 4 ---
All buffers (spins, couplings, energies, interactions) are allocated once at initialization and reused across sweeps <ref:2602.19045#pg9> The package is validated against exact 2D Ising critical points on both the square and triangular lattices <ref:2602. p. 8 The implementation
is validated against exact 2D Ising critical points on both the square and triangular lattices. The
package is open-source and available on PyPI.Where the paper says it
--- Page 5 ---
The performance gains come from moving the entire sampling loop to compiled Rust code, which avoids overhead inherent in Python-level Monte Carlo implementations <ref:2602.19045#pg9> The Rust backend benefits from precomputed neighbor tables and Rayon work-stealing parallelism across replicas <ref:2602. p. 6 6 Performance
By moving the entire sampling loop to compiled Rust code, the package avoids the overhead inherent in Python-level Monte Carlo implementations, including per-sweep temporary array allocations,
interpreter dispatch in tight loops, and the cost of Python-level iteration over replicas for cluster updates. The Rust backend additionally benefits from precomputed neighbor tables (eliminating peraccess modular arithmetic), Rayon work-stealing parallelism across replicas, and the Xoshiro256**
generator which is substantially faster than NumPy’s default RNG for scalar draws.Where the paper says it
--- Page 7 ---
The Python interface is designed for simplicity, allowing users to define models using parameters like lattice shape, couplings, and temperatures The package supports arbitrary Bravais lattice geometries via the neighbor offsets parameter.
--- Page 8 ---
The package implements the standard toolkit of Metropolis, Gibbs, Swendsen–Wang, Wolff, and parallel tempering algorithms It supports arbitrary Bravais lattice geometries including predefined FCC and BCC lattices The package is open-source and available on PyPI.
--- Page 9 ---
The package implements the standard toolkit of Metropolis, Gibbs, Swendsen–Wang, Wolff, and parallel tempering algorithms It supports arbitrary Bravais lattice geometries including predefined FCC and BCC lattices
--- Page 10 ---
The package implements the standard toolkit of Metropolis, Gibbs, Swendsen–Wang, Wolff, and parallel tempering algorithms
Pruning redundant reasoning tokens
peapods presents an open-source Python package for Monte Carlo simulation of Ising spin systems with arbitrary coupling constants on periodic Bravais lattices with user-specified neighbor offsets <ref:2602.19045#pg2> The computational core is written in Rust and exposed to Python via PyO3 <ref:2602.19045#pg5> This package implements Metropolis [3] and Gibbs single-spin-flip algorithms, Swendsen–Wang [4] and Wolff [5] cluster updates, parallel tempering [6], and three replica cluster moves for spin glasses: the Houdayer isoenergetic cluster move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9] <ref:2602.19045#pg2> Overlap statistics between replica pairs enable computation of the spin glass order parameter and Binder ratio <ref:2602.19045#pg4> Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler <ref:2602.19045#pg2>.
Green — the paper says it, and the page is printed. Red — no passage carries it, so treat that sentence as unverified. The same check runs on your own text: check a summary against its source, $5.
Improvements for AI systems
-
System design can incorporate Rust-accelerated Monte Carlo simulations to handle tight inner loops of spin system sampling with compiled performance and memory safety while maintaining a Python interface via PyO3.
-
The improved system can efficiently implement Metropolis, Gibbs, Swendsen–Wang, and Wolff cluster updates for Ising spin systems on arbitrary periodic Bravais lattices with user-specified neighbor offsets.
-
The system can simulate disordered-coupling spin glasses by incorporating parallel tempering and replica cluster moves such as the Houdayer isoenergetic cluster move, Jörg stochastic variant, and Chayes–Machta–Redner (CMR) blue-bond algorithm.
-
The AI system will be capable of computing spin glass order parameters and Binder ratios using overlap statistics between replica pairs to analyze the spin glass transition.
-
The system can perform finite-size scaling analysis of the spin glass transition by computing the Binder ratio for link overlap and accumulating full overlap histograms for replica symmetry breaking analysis.
-
The system will include diagnostics like the equilibration diagnostic Delta t, which signals thermal equilibrium by checking if Delta t goes to zero, and an integrated autocorrelation time tau int to quantify sampling efficiency.
-
The package can support arbitrary lattice geometries, including hypercubic, triangular (with specific neighbor offsets), FCC (n=6), and BCC (n=4) lattices through user-specified integer displacement vectors.
Abstract
We present peapods, an open-source Python package for Monte Carlo simulation of classical spin models with arbitrary couplings, whose sampling loop runs in Rust. It samples Ising models on periodic Bravais lattices given by user-specified neighbor offsets, optionally with open or antiperiodic boundaries, and XY models with signed couplings and site dilution on hypercubic lattices. Besides Metropolis and heat-bath sweeps, Swendsen-Wang and Wolff cluster updates and parallel tempering, it provides a family of replica cluster moves for spin glasses: the Houdayer, Jörg and Chayes-Machta-Redner moves, multi-pair variants of the first two, replica-permutation moves and a gauged form of them, and Swendsen-Wang replica Monte Carlo across temperatures. The same-temperature moves share one construction, a symmetry of the replicas' joint energy applied on clusters, and one-step stationarity tests from exact Boltzmann samples on small lattices check each family of moves that satisfies detailed balance. The package measures overlap distributions, spin-glass correlation lengths, autocorrelation times, equilibration and tempering-flow diagnostics, and jackknife errors over disorder samples. It reproduces the exact critical temperatures of the square and triangular Ising lattices, and its Binder curves for simple-cubic, BCC and FCC lattices agree at the literature critical temperatures. For the three-dimensional plus or minus J spin glass, the crossings of ξ SG/L for L at most 12 extrapolate, with the Janus correction exponent held fixed, to T c = 1.085(42), consistent with the Janus value 1.1019(29). For the two-dimensional XY model, the helicity modulus, correlation length and structure factor agree with high-precision reference data within 1.9 standard errors. This article describes version 0.3.0.
Related papers
- Emergent long-tail dynamics in driven magnets with dynamical frustration
- Statistical Mechanics of Dynamical System Identification
- Second law of thermodynamics in closed quantum many-body systems
- Chemical potentials from structure factors: II. Charged multi-component mixtures
- Genuine quantum scars in Floquet chaotic many-body systems
- Stochastic Thermodynamics for Autoregressive Generative Models: A Non-Markovian Perspective