Configuration

SimulationConfig(lattice=LatticeConfig(), algorithm=Algorithm.METROPOLIS, seed=DEFAULT_SEED, temperatures=(2.269,), n_sweeps=DEFAULT_N_SWEEPS, n_thermalization=DEFAULT_N_THERMALIZATION, measurement_interval=DEFAULT_MEASUREMENT_INTERVAL, compute_correlation=False, correlation_interval=1, store_configs=True, adaptive=AdaptiveConfig(), mode=ExecutionMode.COOLDOWN, swap_interval=1) dataclass

Configuration for a Monte Carlo simulation run.

Parameters:

Name	Type	Description	Default
lattice	LatticeConfig	Lattice geometry and coupling parameters.	LatticeConfig()
algorithm	Algorithm	Monte Carlo update algorithm to use.	METROPOLIS
seed	int	Random seed for reproducibility.	DEFAULT_SEED
temperatures	tuple[float, ...]	Temperatures to simulate at (in descending order for cool-down).	(2.269,)
n_sweeps	int	Number of MC sweeps per temperature point.	DEFAULT_N_SWEEPS
n_thermalization	int	Number of thermalization sweeps before measurement.	DEFAULT_N_THERMALIZATION
measurement_interval	int	Collect a measurement every this many sweeps. In parallel tempering it must be a multiple of swap_interval.	DEFAULT_MEASUREMENT_INTERVAL
compute_correlation	bool	Whether to compute the spin-spin correlation function C(r) and the second-moment correlation length. Each evaluation is a full pair sum, O(N^2) in the number of sites (measured costs are on the performance page of the docs), so at measurement_interval=1 it dominates the run; use correlation_interval to thin it.	False
correlation_interval	int	Evaluate the correlation observables at every k-th measurement (the k-th, 2k-th, ...): 1 evaluates at every measurement, n_sweeps // measurement_interval exactly once, at the final one. The stored C(r) is the last evaluation; the correlation length series has one entry per evaluation. Ignored by adaptive mode, which always takes a single end-of-production snapshot.	1
store_configs	bool	Whether to store spin configurations at every measurement. Disable to cut memory and file size when only scalar observables are needed.	True
mode	ExecutionMode	Execution strategy. COOLDOWN (default) processes temperatures sequentially via cool-down. INDEPENDENT runs each temperature in parallel from random initialization using all CPU cores. PARALLEL_TEMPERING runs one coupled replica-exchange ensemble.	COOLDOWN
swap_interval	int	Sweeps between replica swap attempts (parallel tempering only). Must divide measurement_interval.	1

from_dict(data) classmethod

Build a SimulationConfig from a mapping.

The inverse of dataclasses.asdict: nested lattice and adaptive mappings become their config objects, enum values are coerced from strings, and temperatures becomes a tuple. Unknown keys are ignored (forward compatibility with newer file schemas) and missing keys take their defaults (older schemas). Validation in __post_init__ runs as usual.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Field values, e.g. a decoded config_json record from a saved results file.	required

Returns:

Type	Description
SimulationConfig	A validated configuration.

Raises:

Type	Description
ConfigurationError	If data is not a mapping or any value is invalid.

---

LatticeConfig(lattice_type=LatticeType.SQUARE, size=DEFAULT_LATTICE_SIZE, j1=DEFAULT_J1, j2=DEFAULT_J2, j3=DEFAULT_J3, h=DEFAULT_H) dataclass

Configuration for lattice geometry.

Parameters:

Name	Type	Description	Default
lattice_type	LatticeType	Type of lattice geometry.	SQUARE
size	int	Linear size L of the lattice (creates L x L for 2D). Must be even for triangular and honeycomb lattices (their periodic wrap is only consistent for even L).	DEFAULT_LATTICE_SIZE
j1	float	Nearest-neighbor coupling strength.	DEFAULT_J1
j2	float	Next-nearest-neighbor coupling strength.	DEFAULT_J2
j3	float	Third-nearest-neighbor coupling strength.	DEFAULT_J3
h	float	External magnetic field.	DEFAULT_H

num_sites property

Total number of spins N for this geometry.

Pure function of (lattice_type, size); kept in lockstep with the Rust constructors by a parity test over every lattice type (tests/test_simulation.py::TestNumSites).

from_dict(data) classmethod

Build a LatticeConfig from a mapping.

Unknown keys are ignored (forward compatibility with newer file schemas) and missing keys take their defaults (older schemas).

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Field values, e.g. the dict form produced by dataclasses.asdict. lattice_type may be a :class:LatticeType or its string value.	required

Returns:

Type	Description
LatticeConfig	A validated configuration.

Raises:

Type	Description
ConfigurationError	If data is not a mapping or any value is invalid.

---

AdaptiveConfig(enabled=False, min_thermalization_sweeps=DEFAULT_ADAPTIVE_MIN_THERMALIZATION, max_thermalization_sweeps=DEFAULT_ADAPTIVE_MAX_THERMALIZATION, c_window=DEFAULT_ADAPTIVE_C_WINDOW, min_independent_samples=DEFAULT_ADAPTIVE_MIN_INDEPENDENT_SAMPLES, max_total_sweeps=DEFAULT_ADAPTIVE_MAX_TOTAL_SWEEPS, tau_multiplier=DEFAULT_ADAPTIVE_TAU_MULTIPLIER) dataclass

Configuration for adaptive thermalization and measurement spacing.

When enabled, each temperature is annealed with a cool-down ramp and then probed with a fixed-temperature diagnostic energy series: MSER verifies equilibration and Sokal's windowing method estimates the integrated autocorrelation time (tau_int) on the stationary tail of that series — never across the ramp, whose energy trace is non-stationary by construction. The measurement interval is set to tau_multiplier * tau_int for independent samples.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether to use adaptive mode. When False (default), the simulation uses fixed n_sweeps / measurement_interval / n_thermalization.	False
min_thermalization_sweeps	int	Floor for the annealing-ramp length and the length of each fixed-temperature diagnostic block (itself floored at MIN_DIAGNOSTIC_SWEEPS).	DEFAULT_ADAPTIVE_MIN_THERMALIZATION
max_thermalization_sweeps	int	Maximum thermalization sweeps (cap to prevent runaway near T_c).	DEFAULT_ADAPTIVE_MAX_THERMALIZATION
c_window	float	Sokal windowing constant for tau_int estimation.	DEFAULT_ADAPTIVE_C_WINDOW
min_independent_samples	int	Target number of effectively independent samples per temperature.	DEFAULT_ADAPTIVE_MIN_INDEPENDENT_SAMPLES
max_total_sweeps	int	Hard cap on total sweeps per temperature (thermalization + production).	DEFAULT_ADAPTIVE_MAX_TOTAL_SWEEPS
tau_multiplier	float	Measurement interval = tau_multiplier * tau_int. Using 2*tau gives ~86% independence between consecutive samples.	DEFAULT_ADAPTIVE_TAU_MULTIPLIER

from_dict(data) classmethod

Build an AdaptiveConfig from a mapping.

Unknown keys are ignored and missing keys take their defaults; see :meth:LatticeConfig.from_dict.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Field values, e.g. the dict form produced by dataclasses.asdict.	required

Returns:

Type	Description
AdaptiveConfig	A validated configuration.

Raises:

Type	Description
ConfigurationError	If data is not a mapping or any value is invalid.

---

LatticeType

Bases: str, Enum

Available lattice geometries.

---

Algorithm

Bases: str, Enum

Available Monte Carlo update algorithms.

---

ExecutionMode

Bases: str, Enum

Execution strategy for temperature scans.

COOLDOWN: Sequential cool-down — carry spins from high T to low T. Best for avoiding metastable states. Single-threaded. INDEPENDENT: Each temperature runs independently from random init. Fully parallelized via Rayon. Uses all CPU cores. PARALLEL_TEMPERING: All temperatures run as one coupled replica-exchange ensemble with periodic swap attempts between adjacent temperatures. Not resumable per temperature — the replicas advance together.