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), or (n_disorder, *lattice_shape, n_neighbors) with several realizations.
binder_cumulant		Binder cumulant 1 - <m^4> / (3 <m^2>^2), set after sample.
heat_capacity		Heat capacity per spin N [<e^2> - <e>^2] / T^2, with the thermal variance taken within each disorder realization before the disorder average [...], 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, seed=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) or (n_disorder, *lattice_shape, n_neighbors). Entry [..., x, d] couples site x to its forward neighbor along offset d.	'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 same-temperature overlap 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
seed		Optional non-negative integer controlling built-in random couplings and initial dynamics. None uses fresh entropy.	None

reset(seed=None)

Reset dynamics while keeping the model's couplings fixed.

A bare reset replays the constructor's initial dynamics. Passing a seed performs a deterministic one-off reset without replacing that seed.

sample(n_sweeps, sweep_mode='metropolis', cluster_update_interval=None, cluster_mode='sw', cluster_action='update', pt_interval=None, pt_schedule='single_random_edge', overlap_cluster_update_interval=None, overlap_cluster_build_mode='houdayer', overlap_cluster_mode='wolff', overlap_cluster_action='update', overlap_cluster_max_temperature=None, warmup_ratio=0.25, collect_cluster_stats=False, autocorrelation_max_lag=None, autocorrelation_backend='ring', sequential=False, equilibration_diagnostic=False, snapshot_interval=None, collect_physics=False, displacements=None, block_size=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 spin and temperature, from the disorder-averaged thermal energy variance energy_variance.
• sg_binder — Spin glass Binder parameter (only with n_replicas >= 2).
• fk_csd — FK cluster size distribution (only with collect_cluster_stats=True or cluster_action="observe").
• 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 or overlap_cluster_action="observe").

Optional attributes from an earlier call that this call does not produce are removed.

Parameters:

Name	Type	Description	Default
n_sweeps		Total number of Monte Carlo sweeps (including warmup).	required
sweep_mode		Single-spin update algorithm. "metropolis", "gibbs", or "none" to rely on cluster or overlap moves alone.	'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'
cluster_action		"update" to mutate spins or "observe" to measure a full SW/FK graph without flipping spins.	'update'
pt_interval		If set, attempt parallel tempering swaps every this many sweeps.	None
pt_schedule		"single_random_edge" for legacy PT or "full_ladder" to attempt every adjacent edge per event.	'single_random_edge'
overlap_cluster_update_interval		If set, attempt overlap cluster moves every this many sweeps. Requires n_replicas >= 2, except for "rmc", which needs at least one replica and two temperatures.	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: does not satisfy detailed balance), "pairN" (Houdayer clusters for N/2 replica pairs swapped jointly, requires n_replicas >= N; "pair2" equals "houdayer"), "jorg" (stochastic FK bonds, group_size=2), "jorgN" (Jörg bonds for N/2 pairs swapped jointly; "jorg2" equals "jorg"), "cmr" (two-phase grey+blue, group_size=2), "rmc" (Swendsen-Wang replica Monte Carlo between adjacent temperatures; records no cluster statistics), "permN" (2 <= N <= 8: a uniformly random permutation of a group of N replicas on each cluster of sites where they do not all agree; "perm2" is Houdayer's move), or its gauged form "gpermN", which keeps fixed the sites whose replica pattern matches a random reference site's up to sign ("gperm2" is Houdayer's move on the overlap sign opposite the reference's, usually the minority sign; the recommended low-temperature move). Multiple modes can be alternated with +, e.g. "cmr+houdayer" round-robins each overlap update call. See the overlap moves guide for derivations and recommendations.	'houdayer'
overlap_cluster_mode		Cluster type used inside the overlap move. "wolff" or "sw".	'wolff'
overlap_cluster_action		"update" to perform the move or "observe" to record the full graph without acting on replicas.	'update'
overlap_cluster_max_temperature		If set, apply overlap moves only at temperatures up to this value (for "rmc", only edges whose two temperatures both qualify). Same-temperature cluster moves pay off mainly well below T_c (Zhu, Ochoa & Katzgraber 2015), so this saves their cost where they barely help. Skipped temperatures report no overlap cluster statistics.	None
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
autocorrelation_max_lag		If set, estimate the integrated autocorrelation times mags2_tau (and overlap2_tau with n_replicas >= 2) in measured sweeps, using lags up to this value (capped at a quarter of the measured sweeps). overlap2_tau uses q^2 averaged over all replica pairs at each temperature, so moves that only relabel replicas do not count as decorrelation.	None
autocorrelation_backend		"ring" for exact bounded-memory accumulation or "fft" to retain the full measurement history and evaluate autocorrelation with an FFT.	'ring'
sequential		If True, disable inner-loop parallelism over replicas/temperatures. Use when outer-level parallelism over disorder realizations already saturates all physical cores.	False
equilibration_diagnostic		If True, record replica-averaged energy and link overlap over log-binned windows for equilibration_delta.	False
snapshot_interval		Every this many sweeps, record overlap-cluster snapshots of disorder realization 0 in result["cluster_snapshots"] (not for "rmc"). Requires overlap_cluster_update_interval and must be a multiple of it.	None
collect_physics		If True, also return result["physics"]: physical moments with per-disorder values under "per_disorder". With n_replicas >= 2 it includes the replica pairs' overlap2, overlap4 and overlap_structure_factor_min, Q2 averaged over every replica pair as overlap2_all_pairs (unchanged by replica relabeling; with block_size=1, a per-sweep series), and from them sg_binder, sg_structure_factor_0, sg_correlation_length and sg_correlation_length_ratio (second-moment ξ_SG and ξ_SG/L per axis). Off by default to keep the default measurement cost.	False
displacements		Spin correlation displacements for "physics"; implies collect_physics.	None
block_size		Also keep "physics" sums over blocks of this many measured sweeps; implies collect_physics.	None

Returns:

Type	Description
	Raw results dictionary with keys like "mags", "energies", etc.
	With pt_interval, result["per_disorder"]["parallel_tempering"]
	holds this call's PT edge attempts, edge acceptances and completed
	round trips (not running totals); a round trip that began in an
	earlier call counts when it completes. round_trips[d, r, t] is
	indexed by the walker that started in replica row r at slot t.

equilibration_delta(j_squared=1.0)

Compute the equilibration diagnostic Δ = e - J²β (N_b/N) (1 - q_l).

For Gaussian couplings of variance J², integrating by parts over the disorder gives the equilibrium identity [] = J²β (N_b/N) (1 - []), where e = -H/N is the stored energy (interaction sum per spin), q_l the link overlap and N_b/N = n_neighbors bonds per spin (Katzgraber, Palassini & Young, PRB 63, 184422 (2001)). The identity does not hold for bimodal couplings, so Δ need not vanish there even in equilibrium.

Each checkpoint t averages over the last ⌈t/2⌉ sweeps, i.e. the log-binned window [2^(k-1), 2^k) at t = 2^k. From random initial states both e and q_l rise toward equilibrium, so Δ approaches zero from below; the simulation is considered thermalized once Δ agrees with zero within error bars for the last few windows (Zhu, Ochoa & Katzgraber, PRL 115, 077201 (2015)).

Parameters:

Name	Type	Description	Default
j_squared		Coupling variance J². 1.0 for couplings="gaussian".	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.

Zero-field XY model on a periodic hypercubic lattice, with signed bonds.

All physical reductions use float64. Extensive observables are normalized by the original lattice volume, including vacant sites. Uniform magnetic observables do not measure spin-glass order. See docs/xy.md for moments, disorder averaging, update clocks and the finite-size validation recipe.

reset(seed=None)

Reset spins, random streams and tempering; retain couplings and masks.

sample(n_sweeps, sweep_mode='metropolis', cluster_update_interval=1, cluster_mode='sw', cluster_updates=1, overrelaxation_sweeps=0, pt_interval=None, pt_schedule='single_random_edge', warmup_ratio=0.25, displacements=None, vortices=False, collect_blocks=False, block_size=128, autocorrelation_max_lag=None, autocorrelation_backend='ring', sequential=False)

Sample physical moments, with Metropolis plus embedded SW by default.

n_sweeps includes warmup. sweep_mode="gibbs" uses an exact heat-bath (von Mises) local pass. Set sweep_mode="none" for cluster-only sampling, or cluster_update_interval=None for local updates only. cluster_updates is a fixed count per scheduled event. Overrelaxation and tempering are off by default. Blocks retain sums and counts over block_size measured sweeps; autocorrelation diagnostics use measured energy and m², averaged over replicas at each temperature.

Returns arrays indexed by temperature (and then direction/displacement). per_disorder retains individual moments, derived quantities and work counters; optional blocks and PT diagnostics are nested there. angle_vortex_density is geometric angle winding on intact plaquettes, not frustration-adjusted vorticity or chirality.