Simulation

Simulation(config)

High-level interface to Ising model Monte Carlo simulation.

Parameters:

Name	Type	Description	Default
config	SimulationConfig	Complete simulation configuration.	required

Examples:

>>> from mcising import Simulation, SimulationConfig, LatticeConfig
>>> config = SimulationConfig(
...     lattice=LatticeConfig(size=16, j1=1.0),
...     temperatures=(3.0, 2.269, 1.5),
...     n_sweeps=500,
... )
>>> sim = Simulation(config)
>>> results = sim.run()

spins property writable

Current spin configuration as a 2D NumPy array.

energy property

Current energy per site.

magnetization property

Current magnetization per site.

run(*, show_progress=True, on_temperature_complete=None, skip_temperatures=None)

Execute the full simulation across all temperatures.

Behavior depends on config.mode:

• COOLDOWN (default): Temperatures processed sequentially in descending order. Spins carried from high T to low T.
• INDEPENDENT: Each temperature runs in parallel from random initialization. Uses all CPU cores via Rayon.

Parameters:

Name	Type	Description	Default
show_progress	bool	Whether to display a Rich progress bar.	True
on_temperature_complete	callable	Called after each temperature (cooldown mode only).	None
skip_temperatures	frozenset[float]	Temperatures to skip (cooldown mode only).	None

Returns:

Type	Description
SimulationResults	Collected measurements across all temperatures.

sweep(temperature, n_sweeps=1)

Perform sweeps at a given temperature and return observables.

Parameters:

Name	Type	Description	Default
temperature	float	Simulation temperature (must be > 0).	required
n_sweeps	int	Number of MC sweeps to perform.	1

Returns:

Type	Description
dict[str, float]	Dictionary with keys 'energy', 'magnetization', 'acceptance_rate'.

---

SimulationResults(temperatures=list(), energy=dict(), magnetization=dict(), configurations=dict(), correlation_function=None, correlation_length=None, adaptive_diagnostics=None, metadata=dict()) dataclass

Container for simulation results across temperatures.

Attributes:

Name	Type	Description
temperatures	list[float]	Temperature values that were simulated.
energy	dict[float, NDArray[float64]]	Energy per site measurements at each temperature.
magnetization	dict[float, NDArray[float64]]	Magnetization per site measurements at each temperature.
configurations	dict[float, NDArray[int8]]	Spin configurations at each temperature. Shape: (n_samples, L, L).
correlation_function	dict[float, tuple[NDArray, NDArray]] | None	(distances, correlations) at each temperature, or None if not computed.
correlation_length	dict[float, NDArray[float64]] | None	Correlation length measurements at each temperature, or None.
metadata	dict[str, object]	Simulation metadata (config, timing, seed, etc.).

specific_heat(temperature)

Specific heat per site: Cv = N * Var(E) / T^2.

Parameters:

Name	Type	Description	Default
temperature	float	Temperature to compute Cv at.	required

Returns:

Type	Description
float	Specific heat per site.

susceptibility(temperature)

Magnetic susceptibility per site: chi = N * Var(M) / T.

Parameters:

Name	Type	Description	Default
temperature	float	Temperature to compute chi at.	required

Returns:

Type	Description
float	Susceptibility per site.

summary()

Print a Rich table summarizing results per temperature.

Shows mean energy, magnetization, specific heat, and susceptibility for each temperature.

to_dataframe()

Convert results to a pandas DataFrame.

Returns a DataFrame with columns: T, E_mean, E_std, M_mean, M_std, Cv, chi.

Returns:

Type	Description
DataFrame	Summary statistics per temperature.

Raises:

Type	Description
ImportError	If pandas is not installed.

---

AdaptiveDiagnostics(thermalization_sweeps=0, truncation_point=0, is_thermalized=True, tau_int=0.5, measurement_interval=1, production_sweeps=0, n_samples=0) dataclass

Per-temperature diagnostics from the adaptive measurement scheme.

Attributes:

Name	Type	Description
thermalization_sweeps	int	Total thermalization sweeps used (cool-down + extension).
truncation_point	int	MSER truncation point in the thermalization energy series.
is_thermalized	bool	Whether the series was detected as stationary.
tau_int	float	Estimated integrated autocorrelation time.
measurement_interval	int	Measurement interval used for production (tau_multiplier * tau_int).
production_sweeps	int	Total production sweeps used.
n_samples	int	Number of measurement samples collected.