peapods: A Rust-Accelerated Monte Carlo Package for Ising and XY Spin Systems

arXiv:2602.19045 · cond-mat.stat-mech, physics.comp-ph · Submitted 2026-02-22 · Read on arXiv

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

Where the paper says it

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.

19045#pg2> The computational core is written in Rust and exposed to Python via PyO3 <ref:2602. p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

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. p. 0
Where the paper says it

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

p. 0
Where the paper says it

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

p. 0
Where the paper says it

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

19045#pg2> Overlap statistics between replica pairs enable computation of the spin glass order parameter and Binder ratio <ref:2602. p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

19045#pg4> Replica-level parallelism is achieved through the Rayon [10] workstealing scheduler <ref:2602. p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

p. 0
Where the paper says it

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.

19045#pg2>.

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

Where the paper says it

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.

19045#pg4> Hypercubic lattices use unit vectors along each axis, while triangular and FCC lattices have predefined forward neighbor directions <ref:2602. p. 1
Where the paper says it

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.

19045#pg4>. 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. p. 1
Where the paper says it

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

19045#pg4>. The package simulates R independent replicas across a parallel tempering ladder to study spin glasses <ref:2602. p. 1
Where the paper says it

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.

19045#pg4>.

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

Where the paper says it

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.

19045#pg5>. Cluster updates exploit the Fortuin–Kasteleyn representation to reduce autocorrelation times, specifically Swendsen–Wang and Wolff algorithms <ref:2602. p. 2
Where the paper says it

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.

19045#pg5>. Parallel tempering improves ergodicity by allowing replicas at different temperatures to exchange configurations using a swap probability formula <ref:2602. p. 2
Where the paper says it

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.

19045#pg5>. For spin glasses, three replica cluster moves are implemented: the Houdayer isoenergetic cluster move [7], the J¨org stochastic variant [8], and the Chayes–Machta–Redner (CMR) blue-bond algorithm [9] <ref:2602. p. 0
Where the paper says it

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

19045#pg5>.

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

Where the paper says it

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.

19045#pg6>. From these statistics, the spin glass Binder ratio g = 1 − ⟨q 4⟩ / 3⟨q 2⟩ squared can be used for finite-size scaling analysis to locate the critical temperature Tc <ref:2602. p. 4
Where the paper says it

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

19045#pg7>. The package also computes the full overlap histogram P(q) for analyzing replica symmetry breaking <ref:2602. p. 4
Where the paper says it

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.

19045#pg4>.

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

Where the paper says it

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.

19045#pg8>. This approach yields significant speedups over equivalent Python/NumPy implementations, especially for cluster algorithms where per-temperature Python loops are a bottleneck <ref:2602. p. 6
Where the paper says it

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.

19045#pg9>. The package also includes diagnostics such as the equilibration diagnostic ∆(t) and integrated autocorrelation time τint <ref:2602. p. 7
Where the paper says it

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 8

19045#pg8>.

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

Where the paper says it

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.

19045#pg9>. Future work is planned to extend the package to generalized spin models such as q-state Potts and continuous O(N) models <ref:2602. p. 8
Where the paper says it

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.

19045#pg9>. The package is open-source and available on PyPI <ref:2602. p. 8
Where the paper says it

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.

p. 8
Where the paper says it

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.

19045#pg9>.

References

[1] Yan Ru Pei. peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. p. 0

Where the paper says it

peapods: A Rust-Accelerated Monte Carlo Package for Ising Spin Systems Yan Ru Pei yanrpei@gmail. com Abstract We present peapods [1] (github.

https://github. p. 8
Where the paper says it

peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https: //github.

p. 8
Where the paper says it

peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https: //github.

p. 8
Where the paper says it

peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https: //github.

p. 8
Where the paper says it

peapods: A Rust-accelerated Monte Carlo package for Ising spin systems. https: //github.

com/PeaBrane/peapods, 2026 <ref:2602. p. 8
Where the paper says it

https: //github. com/PeaBrane/peapods, 2026.

19045#pg2>

[2] PyO3 Project Contributors. PyO3: Rust bindings for the Python interpreter. p. 8

Where the paper says it

[2] PyO3 Project Contributors. PyO3: Rust bindings for the Python interpreter.

https://github.com/PyO3/pyo3, 2025 <ref:2602. p. 8
Where the paper says it

https:// github. com/PyO3/pyo3, 2025.

19045#pg2>

[3] Nicholas Metropolis, Arianna W. Rosenbluth, Marshall N. p. 8

Where the paper says it

[3] Nicholas Metropolis, Arianna W. Rosenbluth, Marshall N.

Rosenbluth, Augusta H. p. 8
Where the paper says it

Rosenbluth, Marshall N. Rosenbluth, Augusta H.

Teller, and Edward Teller. p. 8
Where the paper says it

Rosenbluth, Augusta H. Teller, and Edward Teller.

Equation of state calculations by fast computing machines. p. 8
Where the paper says it

Teller, and Edward Teller. Equation of state calculations by fast computing machines.

The Journal of Chemical Physics, 21(6):1087–1092, 1953 <ref:2602. p. 8
Where the paper says it

Equation of state calculations by fast computing machines. The Journal of Chemical Physics, 21(6):1087–1092, 1953.

19045#pg5>

[4] Robert H. Swendsen and Jian-Sheng Wang. p. 8

Where the paper says it

[4] Robert H. Swendsen and Jian-Sheng Wang.

Nonuniversal critical dynamics in Monte Carlo simulations. p. 8
Where the paper says it

Swendsen and Jian-Sheng Wang. Nonuniversal critical dynamics in Monte Carlo simulations.

Physical Review Letters, 58(2):86–88, 1987 <ref:2602. p. 8
Where the paper says it

Nonuniversal critical dynamics in Monte Carlo simulations. Physical Review Letters, 58(2):86–88, 1987.

19045#pg5>

[5] Ulli Wolff. Collective Monte Carlo updating for spin systems. p. 8

Where the paper says it

[5] Ulli Wolff. Collective Monte Carlo updating for spin systems.

Physical Review Letters, 62(4):361–364, 1989 <ref:2602. p. 8
Where the paper says it

Collective Monte Carlo updating for spin systems. Physical Review Letters, 62(4):361–364, 1989.

19045#pg8>

[6] Koji Hukushima and Koji Nemoto. Exchange Monte Carlo method and application to spin glass simulations. p. 8

Where the paper says it

[6] Koji Hukushima and Koji Nemoto. Exchange Monte Carlo method and application to spin glass simulations.

Journal of the Physical Society of Japan, 65(6):1604–1608, 1996 <ref:2602. p. 8
Where the paper says it

Exchange Monte Carlo method and application to spin glass simulations. Journal of the Physical Society of Japan, 65(6):1604–1608, 1996.

19045#pg8>

[7] J. Houdayer. A cluster Monte Carlo algorithm for 2-dimensional spin glasses. p. 8

Where the paper says it

Journal of the Physical Society of Japan, 65(6):1604–1608, 1996. A cluster Monte Carlo algorithm for 2-dimensional spin glasses.

The European Physical Journal B, 22:479–484, 2001 <ref:2602. p. 8
Where the paper says it

A cluster Monte Carlo algorithm for 2-dimensional spin glasses. The European Physical Journal B, 22:479–484, 2001.

19045#pg4>

[8] Thomas J¨org. Cluster Monte Carlo algorithms for diluted spin glasses. p. 8

Where the paper says it

[8] Thomas J¨org. Cluster Monte Carlo algorithms for diluted spin glasses.

Progress of Theoretical Physics Supplement, 157:349–352, 2005 <ref:2602. p. 8
Where the paper says it

Cluster Monte Carlo algorithms for diluted spin glasses. Progress of Theoretical Physics Supplement, 157:349–352, 2005.

19045#pg5>

[9] Oliver Redner, Jon Machta, and Lincoln Chayes. Graphical representations and cluster algorithms for critical points with fields. p. 8

Where the paper says it

[9] Oliver Redner, Jon Machta, and Lincoln Chayes. Graphical representations and cluster algorithms for critical points with fields.

Physical Review E, 62:8114–8125, 2000 <ref:2602. p. 8
Where the paper says it

Graphical representations and cluster algorithms for critical points with fields. Physical Review E, 62:8114–8125, 2000.

19045#pg4>

[10] Josh Stone and Niko Matsakis. Rayon: A data parallelism library for Rust. p. 8

Where the paper says it

[10] Josh Stone and Niko Matsakis. Rayon: A data parallelism library for Rust.

https://github.com/rayon-rs/rayon, 2025 <ref:2602. p. 8
Where the paper says it

https://github. com/rayon-rs/rayon, 2025.

19045#pg2>

[11] Lars Onsager. Crystal statistics. p. 8

Where the paper says it

[11] Lars Onsager. Crystal statistics.

I. A two-dimensional model with an order-disorder transition. p. 8
Where the paper says it

Crystal statistics. A two-dimensional model with an order-disorder transition.

Physical Review, 65(3–4):117–149, 1944 <ref:2602. p. 8
Where the paper says it

A two-dimensional model with an order-disorder transition. Physical Review, 65(3–4):117–149, 1944.

19045#pg8>

[12] Gregory H. Wannier. Antiferromagnetism. p. 8

Where the paper says it

[12] Gregory H. Antiferromagnetism.

The triangular Ising net. p. 8
Where the paper says it

Antiferromagnetism. The triangular Ising net.

Physical Review, 79(2):357–364, 1950 <ref:2602. p. 8
Where the paper says it

The triangular Ising net. Physical Review, 79(2):357–364, 1950.

19045#pg4>

[13] R. M. F. Houtappel. Order-disorder in hexagonal lattices. p. 8

Where the paper says it

Physical Review, 79(2):357–364, 1950. Order-disorder in hexagonal lattices.

Physica, 16(5):425–455, 1950 <ref:2602. p. 8
Where the paper says it

Order-disorder in hexagonal lattices. Physica, 16(5):425–455, 1950.

19045#pg4>

[14] K. Binder. Finite size scaling analysis of Ising model block distribution functions. p. 9

Where the paper says it

Finite size scaling analysis of Ising model block distribution functions. Zeitschrift f¨ur Physik B Condensed Matter, 43:119–140, 1981.

Zeitschrift f¨ur Physik B Condensed Matter, 43:119–140, 1981 <ref:2602. p. 9
Where the paper says it

Finite size scaling analysis of Ising model block distribution functions. Zeitschrift f¨ur Physik B Condensed Matter, 43:119–140, 1981.

19045#pg8>

[15] S. F. Edwards and P. p. 0

Where the paper says it

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.

W. Anderson. Theory of spin glasses. p. 9
Where the paper says it

Edwards and P. Theory of spin glasses.

Journal of Physics F: Metal Physics, 5:965–974, 1975 <ref:2602. p. 9
Where the paper says it

Theory of spin glasses. Journal of Physics F: Metal Physics, 5:965–974, 1975.

19045#pg4>

[16] Konstantin Bauer and Maturin Contributors. Maturin: Build and publish crates with PyO3 bindings as Python packages. p. 9

Where the paper says it

[16] Konstantin Bauer and Maturin Contributors. Maturin: Build and publish crates with PyO3 bindings as Python packages.

https://github.com/PyO3/maturin, 2025 <ref:2602. p. 9
Where the paper says it

https://github. com/PyO3/maturin, 2025.

19045#pg2>

[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

Where the paper says it

Feiguin, J. Gukelberger, E.

19045#pg4>

[18] C. M. Fortuin and P. p. 2

Where the paper says it

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.

W. Kasteleyn. On the random-cluster model: I. p. 9
Where the paper says it

Fortuin and P. On the random-cluster model: I.

Introduction and relation to other models. p. 9
Where the paper says it

On the random-cluster model: I. Introduction and relation to other models.

Physica, 57:536–564, 1972 <ref:2602. p. 9
Where the paper says it

Introduction and relation to other models. Physica, 57:536–564, 1972.

19045#pg4>

[19] M. Baity-Jesi et al. p. 9

Where the paper says it

Physica, 57:536–564, 1972. Baity-Jesi et al.

Critical parameters of the three-dimensional Ising spin glass. p. 9
Where the paper says it

Baity-Jesi et al. Critical parameters of the three-dimensional Ising spin glass.

Physical Review B, 88:224416, 2013 <ref:2602. p. 9
Where the paper says it

Critical parameters of the three-dimensional Ising spin glass. Physical Review B, 88:224416, 2013.

19045#pg8>

[20] Zheng Zhu, Andrew J Ochoa, and Helmut G Katzgraber. Efficient cluster algorithm for spin glasses in any space dimension. p. 9

Where the paper says it

Katzgraber. Efficient cluster algorithm for spin glasses in any space dimension.

Physical Review Letters, 115:077201, 2015 <ref:2602. p. 9
Where the paper says it

Efficient cluster algorithm for spin glasses in any space dimension. Physical Review Letters, 115:077201, 2015.

19045#pg8>

[21] Alan D. Sokal. Monte Carlo methods in statistical mechanics: Foundations and new algorithms. p. 9

Where the paper says it

[21] Alan D. Monte Carlo methods in statistical mechanics: Foundations and new algorithms.

In Functional Integration: Basics and Applications, NATO ASI Series. p. 9
Where the paper says it

Monte Carlo methods in statistical mechanics: Foundations and new algorithms. In Functional Integration: Basics and Applications, NATO ASI Series.

Springer, 1997 <ref:2602. p. 9
Where the paper says it

In Functional Integration: Basics and Applications, NATO ASI Series. Springer, 1997.

19045#pg9>

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

Where the paper says it

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.

19045#pg4>.

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

Where the paper says it

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.

19045#pg5>. Parallel tempering allows replicas at different temperatures to exchange configurations via a swap probability formula <ref:2602. p. 2
Where the paper says it

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.

19045#pg5> The package implements three replica cluster algorithms for spin glasses, including Houdayer ICM, J¨org move, and CMR move <ref:2602. p. 7
Where the paper says it

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 8

19045#pg5>.

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

Where the paper says it

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.

19045#pg5>. The J¨org move proposes a refinement for three-dimensional systems where Houdayer clusters can span the lattice <ref:2602. p. 3
Where the paper says it

J¨org move. J¨org [8] proposed a refinement for three-dimensional systems where Houdayer clusters can span the lattice.

19045#pg5>. The CMR move uses a two-phase construction based on a decomposition of the joint Boltzmann weight of two replicas <ref:2602. p. 3
Where the paper says it

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.

19045#pg5>.

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

Where the paper says it

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.

19045#pg6>.

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

Where the paper says it

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

19045#pg7> The analogous Binder ratio for the link overlap ql is also computed <ref:2602. p. 4
Where the paper says it

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.

19045#pg6>.

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

Where the paper says it

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.

19045#pg8>. Equilibration diagnostic ∆(t) = e(t) + ⟨J 2⟩ βz 1 − ql(t) is computed to signal that thermalization has been achieved <ref:2602. p. 4
Where the paper says it

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

19045#pg9> The integrated autocorrelation time τint quantifies how many sweeps are needed to obtain an independent sample. p. 4
Where the paper says it

Integrated autocorrelation time τint. Autocorrelation times quantify how many sweeps are needed to obtain an independent sample.

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

Where the paper says it

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

19045#pg9>. All replicas are independent conditioned on the temperature assignment, enabling parallel execution across replicas using Rayon <ref:2602. p. 5
Where the paper says it

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.

19045#pg9>.

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

Where the paper says it

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.

19045#pg8>.

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

Where the paper says it

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.

19045#pg9>. The package is open-source and available on PyPI <ref:2602.19045#pg9>

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

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

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

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

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

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

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

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