Why mcising¶

Who it is for. Researchers in computational and statistical physics who need classical Ising Monte Carlo they can trust and cite: studies of frustrated magnetism (competing J1-J2-J3 couplings on square, triangular, honeycomb and cubic lattices), critical phenomena and finite-size scaling, and machine-learning-for-physics work that needs large, labelled, reproducible sets of spin configurations.

The gap it fills. Textbook Ising codes are easy to write and hard to get right: the sign of a coupling, the neighbour table of a non-square lattice, the error bar on a specific heat. mcising packages the parts that go wrong as tested, pip-installable infrastructure — a Rust core checked against exact enumeration of small systems and against exact results (Onsager's solution, the critical temperatures of four lattices) on large ones; blocking and jackknife errors on every observable, with integrated autocorrelation times and adaptive thermalization; three execution modes including parallel tempering; and HDF5 output that records the configuration, seed, version and commit needed to reproduce a run. Antiferromagnetic and competing couplings, the case most reduced examples get wrong, go through the same tests as the ferromagnet.

Research context. mcising was developed alongside and used in a study of phase determination in the frustrated J1-J2 Ising model with deep learning (Çivitcioğlu, Römer & Honecker, Phys. Rev. E 111, 024131 (2025), arXiv:2403.09786) and its follow-up on minimal training sets (arXiv:2504.19795). The frustration tutorial reproduces the stripe phase of that model, and the examples reproduce Onsager's exact solution and a Binder-cumulant determination of Tc:

Phase diagram of the J1-J2 Ising model on the square lattice: ferromagnetic and stripe order parameters over the (J2, T) plane, with the specific-heat peak line

How mcising compares with peapods, ALPS and the Julia spin-model packages, feature by feature, is on the related work page.

Install¶

uvpip

uv add mcising

pip install mcising

Quick example¶

from mcising import Simulation, SimulationConfig, LatticeConfig

# Configure: 32x32 square lattice, three temperatures across Tc
config = SimulationConfig(
    lattice=LatticeConfig(size=32, j1=1.0),
    temperatures=(3.0, 2.269, 1.5),
    n_sweeps=1000,
    seed=42,
)

# Run
results = Simulation(config).run()

# Inspect
for T in results.temperatures:
    E = results.energy[T].mean()
    M = abs(results.magnetization[T]).mean()
    print(f"T={T:.3f}: <E>={E:.4f}, <|M|>={M:.4f}")

This runs a Monte Carlo simulation of the 2D Ising model on a 32x32 square lattice, scanning through three temperatures including the critical point Tc = 2.269.

What mcising gives you¶

5 Lattice Geometries

Square, triangular, honeycomb, cubic (3D), and chain (1D). All with periodic boundary conditions.

Lattice types
Rust-core throughput

351M Metropolis spin updates per second on one core (32×32 at Tc, Apple M4) — 140.4× faster than pure Python, 15.0× faster than a NumPy checkerboard.

Performance
J1-J2-J3 Frustrated Magnetism

Nearest, next-nearest, and third-nearest-neighbor couplings plus external field. 15 auto-optimized Metropolis strategies.

Frustrated magnetism
3 Execution Modes

Sequential cool-down, independent parallel (Rayon), or parallel tempering with replica exchange.

Parallel execution
3 MC Algorithms

Metropolis single-spin-flip, Wolff cluster, and Swendsen-Wang cluster. Choose the right tool for your physics.

Algorithms
Adaptive Thermalization

MSER equilibration detection + Sokal autocorrelation estimation. No more guessing warmup sweeps.

Adaptive mode

Or use the CLI¶

mcising run -L 32 -T 3.0 -T 2.269 -T 1.5 -o results.h5
mcising summary results.h5
mcising plot energy results.h5 -o energy.png
mcising plot specific-heat results.h5 -o cv.png
mcising export results.h5 lattices.zip

Full CLI reference: CLI Guide

Citing¶

If mcising contributes to published work, please cite it. The repository's CITATION.cff carries the current version and is what GitHub's "Cite this repository" button renders. Every release is archived on Zenodo: the concept DOI 10.5281/zenodo.22650285 always resolves to the latest version, and each version has its own DOI (1.0.0: 10.5281/zenodo.22650286). Cite the version you used.

@software{mcising,
  author  = {{\c{C}}ivitcio{\u{g}}lu, Burak},
  title   = {mcising: high-performance {Ising} model {Monte Carlo} simulation with a {Rust} core},
  version = {1.0.0},
  doi     = {10.5281/zenodo.22650286},
  url     = {https://github.com/bcivitcioglu/mcising},
  license = {MIT},
  note    = {Replace version and doi with those of the release you used},
}

If the J1-J2 functionality supported your research, consider also citing the study it was developed for: Çivitcioğlu, Römer & Honecker, Phase determination with and without deep learning, Phys. Rev. E 111, 024131 (2025).

Next steps¶

New to mcising? Start with the Tutorial — it walks you through a complete simulation in 5 minutes.

Looking for a specific function or class? Check the API Reference.

Need CLI commands? See the CLI Reference.

Building on top of mcising? Read Stability & Versioning for what the API promises.