Configuration

All simulation parameters are set through frozen dataclasses. Once created, they're immutable — no accidental mutations during a run.

SimulationConfig

The top-level config that controls everything:

from mcising import (
    SimulationConfig, LatticeConfig, AdaptiveConfig,
    Algorithm, ExecutionMode, LatticeType,
)

config = SimulationConfig(
    lattice=LatticeConfig(
        lattice_type=LatticeType.SQUARE,  # square, triangular, honeycomb, cubic, chain
        size=32,                           # linear extent L
        j1=1.0,                            # nearest-neighbor coupling
        j2=0.0,                            # next-nearest-neighbor coupling
        j3=0.0,                            # third-nearest-neighbor coupling
        h=0.0,                             # external magnetic field
    ),
    algorithm=Algorithm.METROPOLIS,        # metropolis, wolff, swendsen_wang
    seed=42,                               # deterministic RNG seed
    temperatures=(3.0, 2.269, 1.5),        # temperature points
    n_sweeps=1000,                         # measurement sweeps per temperature
    n_thermalization=100,                  # warmup sweeps
    measurement_interval=10,               # measure every N sweeps
    compute_correlation=False,             # compute C(r) and the correlation length
    correlation_interval=1,                # ... at every k-th measurement
    store_configs=True,                    # keep spin snapshots per measurement
    adaptive=AdaptiveConfig(enabled=False),# adaptive thermalization
    mode=ExecutionMode.COOLDOWN,           # cooldown, independent, parallel_tempering
    swap_interval=1,                       # sweeps between PT swaps
)

In parallel tempering, measurement_interval must be a multiple of swap_interval — the ladder advances in swap_interval-sized chunks and can only measure on chunk boundaries, so any other cadence is rejected at construction. Set store_configs=False to skip the per-measurement spin snapshots when only scalar observables are needed (smaller memory footprint and output files).

compute_correlation=True adds the spin-spin correlation function C(r) and the second-moment correlation length. Each evaluation is a full pair sum — O(N²) in the number of sites — so at measurement_interval=1 it dominates the run:

Lattice	Sites	Per evaluation
16×16	256	0.35 ms
32×32	1,024	7.04 ms
64×64	4,096	134.98 ms

One correlation_function() evaluation (the O(N²) pair sum) on the square lattice, Apple M4 (10 cores: 4 performance + 6 efficiency); medians of 5 evaluations.

correlation_interval=k evaluates it at every k-th measurement instead (the k-th, 2k-th, …): 1 is every measurement, n_sweeps // measurement_interval exactly once at the final one. The stored C(r) is the last evaluation and the correlation-length series has one entry per evaluation; a k larger than the number of measurements is rejected at construction. Adaptive mode ignores the knob and always takes a single end-of-production snapshot.

Configs round-trip through plain dicts: dataclasses.asdict(config) serializes (this is what saved files record), and SimulationConfig.from_dict(data) rebuilds the validated object — coercing enum strings, converting temperatures to a tuple, ignoring unknown keys, and defaulting missing ones.

LatticeConfig

Parameter	Type	Default	Description
lattice_type	LatticeType	SQUARE	Lattice geometry
size	int	10	Linear extent L (must be >= 2; even for triangular/honeycomb)
j1	float	1.0	Nearest-neighbor coupling
j2	float	0.0	Next-nearest-neighbor coupling
j3	float	0.0	Third-nearest-neighbor coupling
h	float	0.0	External magnetic field

All coupling values must be finite. Cluster algorithms (Wolff, Swendsen-Wang) require j1>0, j2=0, j3=0, h=0.

Algorithm constraints

Algorithm	J1	J2	J3	h	All lattices?
Metropolis	any	any	any	any	Yes
Wolff	> 0 only	0 only	0 only	0 only	Yes
Swendsen-Wang	> 0 only	0 only	0 only	0 only	Yes

Temperature specification

Temperatures must be positive and finite. For the cooldown mode, they're automatically sorted in descending order.

# Individual temperatures
temperatures=(3.0, 2.269, 1.5)

# Dense scan (via numpy)
import numpy as np
temperatures=tuple(np.linspace(1.5, 3.5, 50))

Defaults

Parameter	Default
lattice_type	SQUARE
size	10
j1	1.0
j2, j3, h	0.0
algorithm	METROPOLIS
seed	42
n_sweeps	1000
n_thermalization	100
measurement_interval	10
compute_correlation	False
correlation_interval	1 (every measurement)
store_configs	True
mode	COOLDOWN
swap_interval	1 (must divide measurement_interval in PT)

See the API Reference for complete documentation of all parameters.