Skip to content

Commit bb9ad4a

Browse files
PeaBranePeaBrane
committed
add JOSS paper, bench subcommand, and CONTRIBUTING guide
1 parent 5877186 commit bb9ad4a

File tree

5 files changed

+392
-44
lines changed

5 files changed

+392
-44
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,6 @@
44
.ipynb_checkpoints
55
**/playground*
66
**/target/
7-
paper/
7+
paper/*
8+
!paper/joss/
89
refs/

‎CONTRIBUTING.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Contributing to peapods
2+
3+
## Dev environment setup
4+
5+
You need:
6+
- **Rust toolchain** (stable) — install via [rustup](https://rustup.rs/)
7+
- **Python 3.10+** with [uv](https://docs.astral.sh/uv/)
8+
- **Maturin** for building the Rust extension
9+
10+
```bash
11+
git clone https://github.com/PeaBrane/peapods.git
12+
cd peapods
13+
uv venv
14+
uv pip install maturin numpy
15+
```
16+
17+
## Building from source
18+
19+
```bash
20+
VIRTUAL_ENV=.venv .venv/bin/maturin develop --release
21+
```
22+
23+
This compiles the Rust core and installs the package into the local venv.
24+
25+
## Running tests
26+
27+
```bash
28+
.venv/bin/python -m pytest tests/
29+
```
30+
31+
## Running benchmarks
32+
33+
```bash
34+
.venv/bin/python -m peapods bench --shape 32 32 \
35+
--temp-min 0.1 --temp-max 10 --temp-scale log --n-sweeps 1000
36+
```
37+
38+
Or the full benchmark suite:
39+
40+
```bash
41+
.venv/bin/python benchmarks/sweep_modes.py
42+
```
43+
44+
## Code style
45+
46+
- **Python**: formatted and linted with [ruff](https://docs.astral.sh/ruff/)
47+
- **Rust**: `cargo fmt` and `cargo clippy` in `peapods_core/`
48+
49+
## Pull requests
50+
51+
1. Fork the repo and create a feature branch
52+
2. Make your changes
53+
3. Run tests and lints
54+
4. Open a PR against `main`
55+
56+
## Reporting issues
57+
58+
Open an issue on [GitHub](https://github.com/PeaBrane/peapods/issues) with:
59+
- What you expected vs. what happened
60+
- Minimal reproduction steps
61+
- Python/Rust versions and OS

‎paper/joss/paper.bib‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
@article{Metropolis1953,
2+
author = {Metropolis, Nicholas and Rosenbluth, Arianna W. and Rosenbluth, Marshall N. and Teller, Augusta H. and Teller, Edward},
3+
title = {Equation of State Calculations by Fast Computing Machines},
4+
journal = {The Journal of Chemical Physics},
5+
volume = {21},
6+
number = {6},
7+
pages = {1087--1092},
8+
year = {1953},
9+
doi = {10.1063/1.1699114}
10+
}
11+
12+
@article{Swendsen1987,
13+
author = {Swendsen, Robert H. and Wang, Jian-Sheng},
14+
title = {Nonuniversal Critical Dynamics in {Monte Carlo} Simulations},
15+
journal = {Physical Review Letters},
16+
volume = {58},
17+
number = {2},
18+
pages = {86--88},
19+
year = {1987},
20+
doi = {10.1103/PhysRevLett.58.86}
21+
}
22+
23+
@article{Wolff1989,
24+
author = {Wolff, Ulli},
25+
title = {Collective {Monte Carlo} Updating for Spin Systems},
26+
journal = {Physical Review Letters},
27+
volume = {62},
28+
number = {4},
29+
pages = {361--364},
30+
year = {1989},
31+
doi = {10.1103/PhysRevLett.62.361}
32+
}
33+
34+
@article{Hukushima1996,
35+
author = {Hukushima, Koji and Nemoto, Koji},
36+
title = {Exchange {Monte Carlo} Method and Application to Spin Glass Simulations},
37+
journal = {Journal of the Physical Society of Japan},
38+
volume = {65},
39+
number = {6},
40+
pages = {1604--1608},
41+
year = {1996},
42+
doi = {10.1143/JPSJ.65.1604}
43+
}
44+
45+
@article{Houdayer2001,
46+
author = {Houdayer, J.},
47+
title = {A Cluster {Monte Carlo} Algorithm for 2-Dimensional Spin Glasses},
48+
journal = {The European Physical Journal B},
49+
volume = {22},
50+
pages = {479--484},
51+
year = {2001},
52+
doi = {10.1007/PL00011151}
53+
}
54+
55+
@article{Jorg2006,
56+
author = {J{\"o}rg, Thomas},
57+
title = {Cluster {Monte Carlo} Algorithms for Diluted Spin Glasses},
58+
journal = {Progress of Theoretical Physics Supplement},
59+
volume = {157},
60+
pages = {349--352},
61+
year = {2005},
62+
doi = {10.1143/PTPS.157.349}
63+
}
64+
65+
@article{CMR2000,
66+
author = {Redner, Oliver and Machta, Jon and Chayes, Lincoln},
67+
title = {Graphical Representations and Cluster Algorithms for Critical Points with Fields},
68+
journal = {Physical Review E},
69+
volume = {62},
70+
pages = {8114--8125},
71+
year = {2000},
72+
doi = {10.1103/PhysRevE.62.8114}
73+
}
74+
75+
@article{Edwards1975,
76+
author = {Edwards, S. F. and Anderson, P. W.},
77+
title = {Theory of Spin Glasses},
78+
journal = {Journal of Physics F: Metal Physics},
79+
volume = {5},
80+
pages = {965--974},
81+
year = {1975},
82+
doi = {10.1088/0305-4608/5/5/017}
83+
}
84+
85+
@article{Onsager1944,
86+
author = {Onsager, Lars},
87+
title = {Crystal Statistics. {I}. {A} Two-Dimensional Model with an Order-Disorder Transition},
88+
journal = {Physical Review},
89+
volume = {65},
90+
number = {3--4},
91+
pages = {117--149},
92+
year = {1944},
93+
doi = {10.1103/PhysRev.65.117}
94+
}
95+
96+
@article{Binder1981,
97+
author = {Binder, K.},
98+
title = {Finite Size Scaling Analysis of {Ising} Model Block Distribution Functions},
99+
journal = {Zeitschrift f{\"u}r Physik B Condensed Matter},
100+
volume = {43},
101+
pages = {119--140},
102+
year = {1981},
103+
doi = {10.1007/BF01293604}
104+
}
105+
106+
@misc{PyO3,
107+
author = {{PyO3 Project Contributors}},
108+
title = {{PyO3}: {Rust} Bindings for the {Python} Interpreter},
109+
year = {2025},
110+
howpublished = {\url{https://github.com/PyO3/pyo3}}
111+
}
112+
113+
@misc{Rayon,
114+
author = {Stone, Josh and Matsakis, Niko},
115+
title = {{Rayon}: A Data Parallelism Library for {Rust}},
116+
year = {2025},
117+
howpublished = {\url{https://github.com/rayon-rs/rayon}}
118+
}
119+
120+
@misc{Maturin,
121+
author = {Bauer, Konstantin and {Maturin Contributors}},
122+
title = {{Maturin}: Build and Publish Crates with {PyO3} Bindings as {Python} Packages},
123+
year = {2025},
124+
howpublished = {\url{https://github.com/PyO3/maturin}}
125+
}
126+
127+
@article{Bauer2011,
128+
author = {Bauer, B. and Carr, L. D. and Evertz, H. G. and Feiguin, A. and Freire, J. and Fuchs, S. and Gamper, L. and Gukelberger, J. and Gull, E. and Guertler, S. and Hehn, A. and Bazhirov, T. and Isr{\"a}elsson, S. and Kozik, E. and Laeuchli, A. M. and LeBlanc, P. and Pollet, L. and Sherrill, C. D. and Troyer, M. and Werner, P.},
129+
title = {The {ALPS} Project Release 2.0: Open Source Software for Strongly Correlated Systems},
130+
journal = {Journal of Statistical Mechanics: Theory and Experiment},
131+
volume = {2011},
132+
pages = {P05001},
133+
year = {2011},
134+
doi = {10.1088/1742-5468/2011/05/P05001}
135+
}
136+
137+
@misc{Peapods,
138+
author = {Pei, Yan Ru},
139+
title = {\texttt{peapods}: A {Rust}-Accelerated {Monte Carlo} Package for {Ising} Spin Systems},
140+
year = {2026},
141+
howpublished = {\url{https://github.com/PeaBrane/peapods}}
142+
}
143+
144+
@misc{PeapodsPreprint,
145+
author = {Pei, Yan Ru},
146+
title = {Peapods: A {Rust}-Accelerated {Monte Carlo} Package for {Ising} Spin Systems},
147+
year = {2026},
148+
eprint = {2602.19045},
149+
archiveprefix = {arXiv},
150+
primaryclass = {cond-mat.stat-mech}
151+
}

‎paper/joss/paper.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "peapods: A Rust-Accelerated Monte Carlo Package for Ising Spin Systems on Arbitrary Lattices"
3+
tags:
4+
- Python
5+
- Rust
6+
- Monte Carlo
7+
- Ising model
8+
- spin glass
9+
- statistical physics
10+
authors:
11+
- name: Yan Ru Pei
12+
orcid: 0000-0002-7401-3080
13+
affiliation: 1
14+
affiliations:
15+
- name: Independent Researcher
16+
index: 1
17+
date: 25 February 2026
18+
bibliography: paper.bib
19+
---
20+
21+
# Summary
22+
23+
`peapods` is a Python package for Monte Carlo simulation of Ising spin
24+
systems on arbitrary Bravais lattices with arbitrary coupling distributions.
25+
It exposes a high-level Python API and a command-line interface (`peapods
26+
simulate`, `peapods bench`) while delegating all numerically intensive work to
27+
a Rust core linked via PyO3 [@PyO3; @Maturin]. The package supports
28+
Metropolis [@Metropolis1953] and Gibbs single-spin-flip updates,
29+
Swendsen--Wang [@Swendsen1987] and Wolff [@Wolff1989] cluster algorithms,
30+
replica-exchange parallel tempering [@Hukushima1996], and the Houdayer
31+
[@Houdayer2001], Jörg [@Jorg2006], and Chayes--Machta--Redner [@CMR2000]
32+
overlap cluster moves for spin glasses. It is pip-installable from PyPI and
33+
available as a Rust crate on crates.io.
34+
35+
# Statement of need
36+
37+
Spin glasses --- disordered magnetic systems with competing ferromagnetic and
38+
antiferromagnetic interactions --- remain one of the most active areas of
39+
statistical physics. Fundamental questions about replica symmetry breaking,
40+
ultrametricity, and the nature of the low-temperature phase in finite
41+
dimensions are still open and can currently only be probed through large-scale
42+
simulation [@Edwards1975]. Effective simulation of spin glasses requires
43+
combining cluster algorithms with parallel tempering and replica overlap moves,
44+
often on non-cubic lattice geometries with random couplings.
45+
46+
Despite this need, no existing pip-installable package offers this combination
47+
of algorithms. Researchers typically rely on private C or Fortran codes, or on
48+
heavyweight frameworks that are difficult to install and extend. `peapods`
49+
fills this gap by providing a batteries-included, easy-to-install package that
50+
covers the full algorithmic toolkit needed for modern spin-glass research,
51+
while remaining simple enough for pedagogical use on clean ferromagnetic
52+
systems.
53+
54+
# State of the field
55+
56+
Several existing tools address parts of this space. ALPS `spinmc` [@Bauer2011]
57+
provides a mature C++ Monte Carlo application but does not support spin-glass
58+
couplings, requires a heavy build toolchain, and has seen limited maintenance.
59+
`tamc` is a Rust-based Monte Carlo CLI for classical spin systems but provides
60+
no cluster algorithms and no Python API. `SpinMonteCarlo.jl` offers cluster
61+
updates in Julia but lacks parallel tempering, spin-glass support, and Python
62+
interoperability. Numerous pedagogical Python repositories implement
63+
Metropolis-only sampling on square lattices but do not scale to research-grade
64+
simulations. To our knowledge, no existing JOSS paper covers a general-purpose
65+
Ising Monte Carlo package with the combination of cluster, tempering, and
66+
overlap algorithms on arbitrary lattice geometries.
67+
68+
# Software design
69+
70+
The computational core is a Rust crate (`peapods_core`) compiled into a Python
71+
extension module via PyO3 and Maturin. Lattice geometry is specified by
72+
user-provided neighbor offset vectors, enabling simulation on any Bravais
73+
lattice (square, triangular, FCC, BCC, or custom). Couplings are stored in a
74+
forward-only scheme to halve memory usage, and neighbor indices are
75+
precomputed at construction time for fast access during sweeps. Replica-level
76+
parallelism is implemented with Rayon [@Rayon], giving each temperature replica
77+
a disjoint spin slice and an independent `Xoshiro256**` random number
78+
generator.
79+
80+
The Python layer is a thin wrapper (`Ising` class) that handles model
81+
construction, temperature grid setup, and post-processing of observables
82+
(Binder cumulant [@Binder1981], heat capacity, spin-glass order parameter).
83+
A CLI (`peapods simulate`) exposes the full functionality for scriptless
84+
batch usage, and `peapods bench` provides built-in benchmarking.
85+
86+
# Research applications
87+
88+
`peapods` has been validated against exact analytical results for the 2D Ising
89+
model on square [@Onsager1944] and triangular lattices, and against published
90+
Monte Carlo estimates of the spin-glass critical temperature on six
91+
lattice/coupling combinations in two and three dimensions. These validations,
92+
along with a detailed description of the algorithms and their implementation,
93+
are presented in an accompanying preprint [@PeapodsPreprint].
94+
95+
# AI usage disclosure
96+
97+
Claude (Anthropic) assisted with code generation, documentation, and paper
98+
drafting. All algorithm selection, architecture decisions, and validation were
99+
performed by the author.
100+
101+
# References

0 commit comments

Comments
 (0)