mcising logo

mcising

High-performance Ising model Monte Carlo simulation with a Rust core.

mcising is a Python library for Monte Carlo simulation of Ising spin systems. It supports 5 lattice geometries, J1-J2-J3 frustrated magnetism with external fields, 3 Monte Carlo algorithms, 3 execution modes (including parallel tempering), and adaptive thermalization. The performance-critical core is written in Rust via PyO3.

Performance

2.7-3.4x faster than peapods (Rust/PyO3) across all shared benchmarks.

MacBook Pro 14-inch (2023, Apple M2 Pro, 32 GB). Reproduce with benchmarks/compare_peapods.py.

Metropolis: Square (32×32, T=2.269)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Implementation  ┃    Time ┃ Updates/sec ┃ Sweeps/sec ┃  E/site ┃  vs mcising ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ mcising         │ 0.038 s │ 269,221,877 │    262,912 │ -1.3906 │        1.0x │
│ peapods         │ 0.131 s │  78,146,389 │     76,315 │ -1.4250 │ 3.4x slower │
└─────────────────┴─────────┴─────────────┴────────────┴─────────┴─────────────┘

Metropolis: Triangular (32×32, T=3.641)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Implementation  ┃    Time ┃ Updates/sec ┃ Sweeps/sec ┃  E/site ┃  vs mcising ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ mcising         │ 0.046 s │ 223,340,013 │    218,105 │ -2.1836 │        1.0x │
│ peapods         │ 0.157 s │  65,100,107 │     63,574 │ -2.0238 │ 3.4x slower │
└─────────────────┴─────────┴─────────────┴────────────┴─────────┴─────────────┘

Metropolis: Cubic (16³, T=4.5115)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Implementation  ┃    Time ┃ Updates/sec ┃ Sweeps/sec ┃  E/site ┃  vs mcising ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ mcising         │ 0.279 s │ 146,924,310 │     35,870 │ -1.1982 │        1.0x │
│ peapods         │ 0.812 s │  50,430,683 │     12,312 │ -1.0385 │ 2.9x slower │
└─────────────────┴─────────┴─────────────┴────────────┴─────────┴─────────────┘

Wolff: Square (32×32, T=2.269)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Implementation  ┃    Time ┃ Updates/sec ┃ Sweeps/sec ┃  E/site ┃  vs mcising ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ mcising (wolff) │ 0.103 s │  99,690,738 │     97,354 │ -1.5117 │        1.0x │
│ peapods         │ 0.337 s │  30,386,647 │     29,674 │ -1.4337 │ 3.3x slower │
└─────────────────┴─────────┴─────────────┴────────────┴─────────┴─────────────┘

Swendsen-Wang: Square (32×32, T=2.269)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Implementation  ┃    Time ┃ Updates/sec ┃ Sweeps/sec ┃  E/site ┃  vs mcising ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━┩
│ mcising         │ 0.214 s │  47,960,246 │     46,836 │ -1.3125 │        1.0x │
│ peapods         │ 0.569 s │  18,008,160 │     17,586 │ -1.4323 │ 2.7x slower │
└─────────────────┴─────────┴─────────────┴────────────┴─────────┴─────────────┘

mcising also supports features not available in peapods: J2/J3 coupling, external magnetic field, honeycomb lattice, 1D chain, and parallel tempering.

Features

5 lattice geometries -- square, triangular, honeycomb (2-sublattice), cubic (3D), chain (1D)
3 MC algorithms -- Metropolis, Wolff cluster, Swendsen-Wang cluster
3 execution modes -- sequential cool-down, independent parallel (Rayon), parallel tempering with replica exchange
J1-J2-J3 frustrated magnetism -- nearest, next-nearest, and third-nearest-neighbor couplings
External magnetic field -- h coupling, compatible with all lattices
15 Metropolis strategies -- auto-selected lookup tables optimized per coupling combination
Adaptive thermalization -- MSER equilibration detection + Sokal autocorrelation estimation
Correlation functions -- spin-spin correlation and correlation length
HDF5 output with crash-safe incremental checkpointing
Rich CLI with progress bars, benchmarking, and structured output
Fully reproducible -- deterministic RNG (Xoshiro256**), same seed = same results

Installation

pip install mcising

For development (requires Rust toolchain):

git clone https://github.com/bcivitcioglu/mcising.git
cd mcising
uv sync
uv run maturin develop

Quick Start

Python API

from mcising import Simulation, SimulationConfig, LatticeConfig, LatticeType

config = SimulationConfig(
    lattice=LatticeConfig(size=32, j1=1.0),
    temperatures=(3.0, 2.269, 1.5),
    n_sweeps=1000,
    seed=42,
)

sim = Simulation(config)
results = sim.run()

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

Multiple Lattice Types

from mcising import LatticeType

# Triangular lattice with J1-J2 frustration
config = SimulationConfig(
    lattice=LatticeConfig(
        lattice_type=LatticeType.TRIANGULAR,
        size=32,
        j1=1.0,
        j2=0.5,
    ),
    temperatures=(4.0, 3.641, 2.0),
    n_sweeps=1000,
)

# Also available: HONEYCOMB, CUBIC, CHAIN

Parallel Execution

from mcising import ExecutionMode

# Independent: each temperature runs in parallel (uses all CPU cores)
config = SimulationConfig(
    lattice=LatticeConfig(size=32),
    temperatures=(3.0, 2.5, 2.269, 2.0, 1.5),
    n_sweeps=1000,
    mode=ExecutionMode.INDEPENDENT,  # ~6x faster with 10 cores
)

# Parallel Tempering: parallel + replica swap for better sampling
config = SimulationConfig(
    lattice=LatticeConfig(size=32),
    temperatures=(3.0, 2.5, 2.269, 2.0, 1.5),
    n_sweeps=1000,
    mode=ExecutionMode.PARALLEL_TEMPERING,
)

Adaptive Mode

For large lattices near the critical temperature, enable adaptive measurement to automatically determine thermalization length and measurement spacing:

from mcising import AdaptiveConfig

config = SimulationConfig(
    lattice=LatticeConfig(size=64),
    temperatures=(3.0, 2.269, 1.5),
    adaptive=AdaptiveConfig(enabled=True, min_independent_samples=200),
    seed=42,
)

results = Simulation(config).run()

# Inspect diagnostics
for T in results.temperatures:
    diag = results.adaptive_diagnostics[T]
    print(f"T={T:.3f}: tau_int={diag.tau_int:.1f}, "
          f"interval={diag.measurement_interval}")

CLI

# Basic run
mcising run -L 32 --seed 42 -o results.h5

# Triangular lattice with parallel tempering
mcising run -L 32 --lattice triangular --mode parallel_tempering

# Independent parallel execution (uses all CPU cores)
mcising run -L 32 --mode independent -T 3.0 -T 2.269 -T 1.5

# Adaptive mode
mcising run -L 64 --adaptive --min-samples 200 --seed 42

# With checkpointing (crash-safe)
mcising run -L 32 --checkpoint sim.h5

# Resume interrupted run
mcising run -L 32 --checkpoint sim.h5 --resume

# Benchmark performance across all lattices and algorithms
mcising benchmark

# Show info
mcising info

Saving Results

from mcising import save_hdf5, load_hdf5, save_json_summary

# HDF5 (full data)
save_hdf5(results, "results.h5")
loaded = load_hdf5("results.h5")

# JSON summary (statistics only)
save_json_summary(results, "summary.json")

Architecture

mcising/
├── rust/src/              # Rust core (compiled to mcising._core)
│   ├── algorithm/         # MC algorithms (Metropolis, Wolff, Swendsen-Wang)
│   ├── autocorrelation.rs # MSER + Sokal windowing
│   ├── lattice/           # Lattice geometries (square, triangular, honeycomb, cubic, chain)
│   ├── observables.rs     # Energy, magnetization, correlation
│   ├── parallel.rs        # Rayon-parallelized execution (independent + parallel tempering)
│   └── simulation.rs      # PyO3 boundary (IsingSimulation)
├── python/mcising/        # Python package
│   ├── simulation.py      # High-level Simulation class
│   ├── config.py          # Frozen dataclass configs
│   ├── io.py              # HDF5/JSON I/O
│   ├── plotting.py        # Matplotlib visualization
│   └── cli.py             # Typer CLI
├── tests/                 # 401 tests (141 Rust + 260 Python)
└── benchmarks/            # Reproducible performance comparisons

License

This project is licensed under the MIT License.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcising-0.22.0.tar.gz (263.9 kB view details)

Uploaded Aug 15, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mcising-0.22.0-cp313-cp313-win_amd64.whl (384.2 kB view details)

Uploaded Aug 15, 2026 CPython 3.13Windows x86-64

mcising-0.22.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (505.2 kB view details)

Uploaded Aug 15, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

mcising-0.22.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (478.1 kB view details)

Uploaded Aug 15, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64

mcising-0.22.0-cp313-cp313-macosx_11_0_arm64.whl (447.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.13macOS 11.0+ ARM64

mcising-0.22.0-cp313-cp313-macosx_10_12_x86_64.whl (472.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.13macOS 10.12+ x86-64

mcising-0.22.0-cp312-cp312-win_amd64.whl (384.7 kB view details)

Uploaded Aug 15, 2026 CPython 3.12Windows x86-64

mcising-0.22.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (505.7 kB view details)

Uploaded Aug 15, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

mcising-0.22.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (478.7 kB view details)

Uploaded Aug 15, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64

mcising-0.22.0-cp312-cp312-macosx_11_0_arm64.whl (447.7 kB view details)

Uploaded Aug 15, 2026 CPython 3.12macOS 11.0+ ARM64

mcising-0.22.0-cp312-cp312-macosx_10_12_x86_64.whl (472.9 kB view details)

Uploaded Aug 15, 2026 CPython 3.12macOS 10.12+ x86-64

mcising-0.22.0-cp311-cp311-win_amd64.whl (383.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.11Windows x86-64

mcising-0.22.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (506.7 kB view details)

Uploaded Aug 15, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

mcising-0.22.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (480.3 kB view details)

Uploaded Aug 15, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

mcising-0.22.0-cp311-cp311-macosx_11_0_arm64.whl (448.5 kB view details)

Uploaded Aug 15, 2026 CPython 3.11macOS 11.0+ ARM64

mcising-0.22.0-cp311-cp311-macosx_10_12_x86_64.whl (473.1 kB view details)

Uploaded Aug 15, 2026 CPython 3.11macOS 10.12+ x86-64

mcising-0.22.0-cp310-cp310-win_amd64.whl (383.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.10Windows x86-64

mcising-0.22.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (506.8 kB view details)

Uploaded Aug 15, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

mcising-0.22.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (480.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64

mcising-0.22.0-cp310-cp310-macosx_11_0_arm64.whl (448.4 kB view details)

Uploaded Aug 15, 2026 CPython 3.10macOS 11.0+ ARM64

mcising-0.22.0-cp310-cp310-macosx_10_12_x86_64.whl (473.1 kB view details)

Uploaded Aug 15, 2026 CPython 3.10macOS 10.12+ x86-64

File details

Details for the file mcising-0.22.0.tar.gz.

File metadata

Download URL: mcising-0.22.0.tar.gz
Upload date: Aug 15, 2026
Size: 263.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mcising-0.22.0.tar.gz
Algorithm	Hash digest
SHA256	`2048ae9acb2ded0233e51851ce5780afe9683735abc092792697bdac1d3aca9d`
MD5	`0fe918cdc75f41d58a0cf8ccad761c30`
BLAKE2b-256	`4cf72d72b83861c0b1823d05b0310768ef3d5dc64f4c697fab6dbee09e2440eb`

Algorithm	Hash digest
SHA256	`5b80d99e0b2c8b4052bf8881bcd917a7e705c54bc06ad17e669bf71fc71d2bc2`
MD5	`805983189138e561cd645b5869e2e9ef`
BLAKE2b-256	`679782cc27ec86ae2ebf7b410bcb4c40fb68a219623ff0cf81c6ff449efac7dc`

Algorithm	Hash digest
SHA256	`de31489b5860b6dad1f6449341f0f406e312372d93b581888463bdfc936d9606`
MD5	`01da9282c6c04a79dce495d4f1c98c7f`
BLAKE2b-256	`fce8f93bb325dcf6574b238f751f41a852fb17c3af703f65b7571a288d65b239`

Algorithm	Hash digest
SHA256	`fc3abef490bd0ebc3cff6596ae3f0a658c1b8ecca37c56314453f27acaafbaa8`
MD5	`8878a62c34760086223b1cac7bd5dbdf`
BLAKE2b-256	`f1885df8cb5b0f30a377b521af024f8cc1f07bdb7ff1be66933d219d47d28ecd`

Algorithm	Hash digest
SHA256	`8aadb68b233b7b51a8e1a74845c6ae2f4bddae5185c224e1c3f0e0deb68cdcbe`
MD5	`10645b17afaeed6c5191181c974bfe6a`
BLAKE2b-256	`227f543fcc974e6b579e385f252a689763e18592952cfbfe7b36c8d7d23c5a2b`

Algorithm	Hash digest
SHA256	`b679cc9d781e938c842a6a5e3d0432d971990d66673926cbe8763233092ddc09`
MD5	`f20821a242f9225b6b46f4a32f8de2d5`
BLAKE2b-256	`a1bf9b0d4de1c72d0aa9ba0eea84d8b73c43654b02ce803d3b9467a7d7f9610c`

Algorithm	Hash digest
SHA256	`bd21969afb000be1fc2d3b950e2914215c038a3d89139806dc423bdc42d470c0`
MD5	`7198701bb6ca8a9736634db8a7f60205`
BLAKE2b-256	`be3f09ce53e262dc86b7c66ebf40e4aa7e0d6c5fd183322d96e2fcaa46e9fde0`

Algorithm	Hash digest
SHA256	`25502447a17b13fa710c93f072ef74caccd329471a193b43138dbb02408c975b`
MD5	`631f0bd9232479e2cf671f19bb4fae18`
BLAKE2b-256	`858db99b29989d097e26334f2c7b09f536783fa4210d7aaccaac48f112462de7`

Algorithm	Hash digest
SHA256	`4c923c35d4f807cedc7c9a80dece7fac863520ac18f12764278c9b84cf9e6276`
MD5	`830417621b392d461328e6a65415baa3`
BLAKE2b-256	`7868e45026e0e5994c24b8b211bc177ae231c74cd85dd61e5cfa7d2f1a9e8378`

Algorithm	Hash digest
SHA256	`2213dac84cc46a81c545d7e0143188ea12b6b1fb24776ae3fc799a81483ec7f0`
MD5	`5fe5117155ea85871f29cd2f10aedbdb`
BLAKE2b-256	`d241e62bdf5d8958ce7832b4818957e6cad928627ee4834accd93c97dd149b80`

Algorithm	Hash digest
SHA256	`af203b6f1e4a5a738c5644bdf10d67cd3c2e67891412c14720d25e5558085c77`
MD5	`1736cc2fa56443ccd24f22733e128fee`
BLAKE2b-256	`300c075f54b4747146d189b774a65368a967933abe6a03636ed3fb89b4e74c82`

Algorithm	Hash digest
SHA256	`2cf57f21833dea0b8d03e2b153d1451e6980330c866e81220f9ecb38dccb1edc`
MD5	`a72e6c29dd5d43b4eb9a679425185e38`
BLAKE2b-256	`2142443b1d68a4f383b7e87c8b2b16b429b5d22cfcbbfc0bf7f748e6c71bf33b`

Algorithm	Hash digest
SHA256	`9dd09212051a61f4e48ef99af9a813c6cc953de011ad5128ef8603f1831e20d7`
MD5	`fcf190c66b94559c4f597db041dc6655`
BLAKE2b-256	`fbc330f330b5e00ad308533dddd36c3b5fd904a2a4b6275be8e0f4812642f7b2`

Algorithm	Hash digest
SHA256	`ed1f5bb43d023f41b002fd911733449e78d1f566693ef88f18e092d2f22f908b`
MD5	`1edad8cce2b1a8fb0964e78808eb2574`
BLAKE2b-256	`3a85ce65b9554d2b94e0bed41fdefd86eb298a6200c8b1290ec96b6ed03bb494`

Algorithm	Hash digest
SHA256	`e751ac542b3b1fcf6b9465a0fd6c4b6221b32c860dd4ae2a4409d3c17e6170ad`
MD5	`54660d35b181e121e267723899cc9494`
BLAKE2b-256	`10e44d2c5467f62477356fd8ca1143a496d530869d01053f1c239c1393d0b343`

Algorithm	Hash digest
SHA256	`c71b45d11f0f6bdf837592393edceb399aa7259f0bba95d78a54e9aa53fa7ced`
MD5	`f90507b6eb56ac9fbbb495a3d4725791`
BLAKE2b-256	`e71042ef8f4dce05e613d507db28ad5df0f2960e8fcbcdea2afcce929b366114`

Algorithm	Hash digest
SHA256	`a1646f18facd55ff0ba70868133dfc82f821898116cf535819cea03fb3d97958`
MD5	`ffca29d36fb0d3ded284dc6a958cb7db`
BLAKE2b-256	`fd9e5b9018474901187d74033eebac7b49d1e15be407d6e325fd4aafba0549fa`

Algorithm	Hash digest
SHA256	`7fe31cb250ff2d0e43e5b6e4c903367c30e7dae17a998a035e11f23e43cc5af9`
MD5	`6646567ce29c4d3a850576b713ff7cde`
BLAKE2b-256	`dbbe58c8384f279557a507f8f145dfacc30a2b7b5c9ee42b39b3898c5f52dbf2`

Algorithm	Hash digest
SHA256	`57114a36df0f5d206c522285b7ac1442bdf2d4e289e96c4fb5769fc167094b22`
MD5	`42e6b81736d88257e9f5d2c1654f6644`
BLAKE2b-256	`3515b0d2880dba60f17d53e629918cca2e9a4b1870f1e77592fb5cc9093b049a`

Algorithm	Hash digest
SHA256	`53b6da05a2ddb4a2265ff508f12ecb3896dae1a982962ac2b3a62e36676b377e`
MD5	`04ca47a1614872bb7b33d00018bc68a3`
BLAKE2b-256	`5101a47fb1f87421d79df12be8fbcfb37a9704b85978a78b2b951e60f5f14b5a`

Algorithm	Hash digest
SHA256	`10386e0456992c0879833fc747203e10a65a5cb8acf99c0421366125f90de5d0`
MD5	`3557d5e1d7eca6789b1437c5de089c83`
BLAKE2b-256	`64f6453ce6e2bdbcf63139d8258c207be36da4b9a7b35b843a01066ef6e0c3e2`

mcising 0.22.0

mcising

Performance

Features

Installation

Quick Start

Python API

Multiple Lattice Types

Parallel Execution

Adaptive Mode

CLI

Saving Results

Architecture

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata