API Reference

Ising model on a periodic Bravais lattice with Monte Carlo sampling.

Supports ferromagnets and spin glasses on hypercubic, triangular, FCC, BCC, or any custom lattice defined by neighbor offsets. Multiple replicas enable overlap-based spin glass order parameters.

Attributes:

Name	Type	Description
lattice_shape		Shape of the lattice as a tuple of ints.
n_dims		Number of spatial dimensions.
n_neighbors		Number of nearest neighbors per site.
temperatures		Array of temperatures for parallel tempering.
n_temps		Number of temperature points.
n_replicas		Number of replicas per temperature.
n_disorder		Number of disorder realizations.
couplings		Coupling array with shape (*lattice_shape, n_neighbors).
binder_cumulant		Binder cumulant 1 - <m^4> / (3 <m^2>^2), set after sample.
heat_capacity		Heat capacity (<E^2> - <E>^2) / T^2, set after sample.
sg_binder		Spin glass Binder parameter 1 - <q^4> / (3 <q^2>^2), set after sample with n_replicas >= 2.

__init__(lattice_shape, couplings='ferro', temperatures=np.geomspace(0.1, 10, 32), n_replicas=1, n_disorder=1, neighbor_offsets=None, geometry=None)

Create an Ising model.

Parameters:

Name	Type	Description	Default
lattice_shape		Shape of the periodic lattice, e.g. (32, 32) for a 2D 32x32 grid.	required
couplings		Coupling configuration. One of "ferro" (all +1), "bimodal" (random +/-1), "gaussian" (standard normal), or a NumPy array of shape (*lattice_shape, n_neighbors).	'ferro'
temperatures		Array of temperatures for the simulation. Defaults to 32 points log-spaced from 0.1 to 10.	geomspace(0.1, 10, 32)
n_replicas		Number of independent replicas per temperature. Must be = 2 for overlap statistics and Houdayer moves.	1
n_disorder		Number of disorder realizations. Each realization gets its own coupling array.	1
neighbor_offsets		List of integer offset vectors defining nearest neighbors, e.g. [[1, 0], [0, 1]] for a square lattice. Mutually exclusive with geometry.	None
geometry		Named lattice geometry. One of "triangular" / "tri", "fcc", or "bcc". Mutually exclusive with neighbor_offsets. If neither is given, defaults to a hypercubic lattice.	None

reset()

Reset all spins to a random configuration.

sample(n_sweeps, sweep_mode='metropolis', cluster_update_interval=None, cluster_mode='sw', pt_interval=None, overlap_cluster_update_interval=None, overlap_cluster_build_mode='houdayer', overlap_cluster_mode='wolff', warmup_ratio=0.25, collect_cluster_stats=False, autocorrelation_max_lag=None, sequential=False, equilibration_diagnostic=False, snapshot_interval=None)

Run Monte Carlo sampling and compute observables.

After sampling, the following attributes are set on the instance:

• binder_cumulant — Binder cumulant per temperature.
• heat_capacity — Heat capacity per temperature.
• sg_binder — Spin glass Binder parameter (only with n_replicas >= 2).
• fk_csd — FK cluster size distribution (only with collect_cluster_stats=True).
• top_cluster_sizes — List of arrays (one per overlap mode), each shape (n_temps, 4), giving average relative sizes of the 4 largest overlap clusters per temperature (only with collect_cluster_stats=True).

Parameters:

Name	Type	Description	Default
n_sweeps		Total number of Monte Carlo sweeps (including warmup).	required
sweep_mode		Single-spin update algorithm. "metropolis" or "gibbs".	'metropolis'
cluster_update_interval		If set, perform a cluster update every this many sweeps.	None
cluster_mode		Cluster algorithm. "sw" (Swendsen-Wang) or "wolff".	'sw'
pt_interval		If set, attempt parallel tempering swaps every this many sweeps.	None
overlap_cluster_update_interval		If set, attempt overlap cluster moves every this many sweeps. Requires n_replicas >= 2.	None
overlap_cluster_build_mode		Overlap cluster algorithm. "houdayer" (deterministic, group_size=2), "houdN" where N is even >= 2 (e.g. "houd4", "houd6" — isoenergetic balanced-site criterion, requires n_replicas >= N; experimental for N > 2: very likely does not satisfy detailed balance), "jorg" (stochastic FK bonds, group_size=2), or "cmr" (two-phase grey+blue, group_size=2). Multiple modes can be alternated with +, e.g. "cmr+houdayer" round-robins each overlap update call.	'houdayer'
overlap_cluster_mode		Cluster type used inside the overlap move. "wolff" or "sw".	'wolff'
warmup_ratio		Fraction of sweeps discarded as warmup before collecting statistics. Default 0.25.	0.25
collect_cluster_stats		If True, collect FK cluster size distribution and top-4 overlap cluster sizes.	False
sequential		If True, disable inner-loop parallelism over replicas/temperatures. Use when outer-level parallelism over disorder realizations already saturates all physical cores.	False

Returns:

Type	Description
	Raw results dictionary with keys like "mags", "energies", etc.

equilibration_delta(j_squared=1.0)

Compute equilibration diagnostic Δ(t) = e(t) - J²β z (1 - q_l(t)).

Δ approaches zero as the system thermalizes (Zhu et al. 2015). Note: the Rust energy convention is e = +Σ J s_i s_j / N (no minus sign), so the sign here is flipped relative to the Hamiltonian form.

Parameters:

Name	Type	Description	Default
j_squared		Average squared coupling ⟨J²⟩. 1.0 for bimodal and Gaussian (unit variance) spin glasses.	1.0

Returns:

Type	Description
	Tuple of (sweeps, delta) where sweeps has shape (n_checkpoints,)
	and delta has shape (n_checkpoints, n_temps).

get_energies()

Return the mean energies per temperature from the last sample run.