"""
Base classes and shared Numba-accelerated kernels for Monte Carlo simulations.
"""
from __future__ import annotations
from abc import ABC, abstractmethod
import numpy as np
from numba import njit
@njit(cache=True, fastmath=True)
def _seed_numba(*, seed: int) -> None:
"""Helper to seed Numba's internal random number generator."""
np.random.seed(seed)
_MASK64 = (1 << 64) - 1
def _derive_step_seed(*, seed: int, step: int) -> int:
"""Mix a (seed, step) pair into a decorrelated 32-bit per-sweep seed.
A plain ``seed + step`` derivation makes the per-sweep random stream of
seed ``s`` at sweep ``t + 1`` identical to that of seed ``s + 1`` at sweep
``t``, so replicas seeded with consecutive integers (the common
``base_seed + k`` convention) share almost all of their randomness and are
not statistically independent. The SplitMix64 finalizer scrambles the pair
so distinct (seed, step) inputs yield uncorrelated seeds.
Parameters
----------
seed : int
Simulation base seed (non-negative integer).
step : int
Zero-based sweep index.
Returns
-------
int
A seed in [0, 2**32) suitable for ``np.random.seed`` inside Numba.
"""
z = (seed * 0xD1B54A32D192ED03 + step * 0x9E3779B97F4A7C15) & _MASK64
z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & _MASK64
z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & _MASK64
z ^= z >> 31
return int(z & 0xFFFFFFFF)
@njit(cache=True, fastmath=True)
def _wrap_bond_angle_numba(delta: float) -> float:
"""
Wrap a bond angle difference into the half-open interval (-pi, pi].
The tie at exactly antiparallel neighbours is resolved to ``+pi``. A
tolerance absorbs the rounding of ``arctan2`` on discrete clock angles, so
a difference of pi is never split between ``+pi`` and ``-pi`` at random.
Parameters
----------
delta : float
Raw angle difference in radians.
Returns
-------
float
Wrapped difference in (-pi, pi].
"""
wrapped = (delta + np.pi) % (2.0 * np.pi) - np.pi
if wrapped <= -np.pi + 1e-9:
wrapped = np.pi
return wrapped
@njit(cache=True, fastmath=True)
def _calculate_vorticity_angles_numba(angles: np.ndarray, idx_next: np.ndarray) -> np.ndarray:
"""
Calculate the winding number of every plaquette from a 2D array of angles.
Each bond difference is wrapped once in its canonical lattice direction
(+x or +y) and negated when the plaquette loop traverses the bond
backwards. This keeps the bond contribution exactly antisymmetric, so the
winding numbers of the two plaquettes sharing a bond cancel and the total
vorticity on the torus is zero. Wrapping the backward differences
independently breaks this for antiparallel neighbours, which occur
routinely in the discrete clock model with even q: both directions then
wrap to the same value and bias the vorticity towards one sign.
Parameters
----------
angles : np.ndarray
(N, N) array of spin angles in radians.
idx_next : np.ndarray
Pre-calculated next-neighbor indices.
Returns
-------
np.ndarray
(N, N) array of winding numbers.
"""
N = angles.shape[0]
vorticity = np.zeros((N, N))
for i in range(N):
inxt = idx_next[i]
for j in range(N):
jnxt = idx_next[j]
t1 = angles[i, j]
t2 = angles[i, jnxt]
t3 = angles[inxt, jnxt]
t4 = angles[inxt, j]
# Loop (i,j) -> (i,j+1) -> (i+1,j+1) -> (i+1,j) -> (i,j); the last
# two legs run against the canonical bond direction.
d1 = _wrap_bond_angle_numba(t2 - t1)
d2 = _wrap_bond_angle_numba(t3 - t2)
d3 = -_wrap_bond_angle_numba(t3 - t4)
d4 = -_wrap_bond_angle_numba(t4 - t1)
vorticity[i, j] = np.round((d1 + d2 + d3 + d4) / (2 * np.pi))
return vorticity
[docs]
def calculate_vorticity_numba(*, spins: np.ndarray, idx_next: np.ndarray) -> np.ndarray:
"""
Calculate the vorticity (winding number) of each plaquette for 2D vector spins.
Optimized by calculating angles first and then using a fast wrapping kernel.
Parameters
----------
spins : np.ndarray
(N, N, 2) array of unit vectors.
idx_next : np.ndarray
Pre-calculated next-neighbor indices.
Returns
-------
vorticity : np.ndarray
(N, N) array containing winding numbers (+1, -1, or 0).
"""
# Vectorized arctan2 is much faster than calling it inside a Numba loop
angles = np.arctan2(spins[..., 1], spins[..., 0])
return _calculate_vorticity_angles_numba(angles, idx_next)
@njit(cache=True, fastmath=True)
def _vortex_density_from_vorticity_numba(vorticity: np.ndarray) -> float:
"""Return density of non-zero winding plaquettes."""
N = vorticity.shape[0]
count = 0
for i in range(N):
for j in range(N):
if np.abs(vorticity[i, j]) > 0.0:
count += 1
return count / float(N * N)
[docs]
def calculate_vortex_density_numba(*, spins: np.ndarray, idx_next: np.ndarray) -> float:
"""
Calculate vortex density n_v, i.e. the fraction of plaquettes with non-zero winding.
Parameters
----------
spins : np.ndarray
(N, N, 2) array of unit vectors.
idx_next : np.ndarray
Pre-calculated next-neighbor indices.
Returns
-------
float
Vortex density n_v in [0, 1].
"""
vorticity = calculate_vorticity_numba(spins=spins, idx_next=idx_next)
return float(_vortex_density_from_vorticity_numba(vorticity))
[docs]
@njit(cache=True, fastmath=True)
def get_helicity_data_numba(*, spins: np.ndarray, idx_next: np.ndarray) -> tuple[float, float]:
"""
Calculate sum of cos and sin of angle differences in x-direction for helicity modulus.
Parameters
----------
spins : np.ndarray
(N, N, 2) array of unit vectors.
idx_next : np.ndarray
Pre-calculated next-neighbor indices for PBCs.
Returns
-------
cos_sum : float
Sum of cosine of angle differences.
sin_sum : float
Sum of sine of angle differences.
"""
N = spins.shape[0]
cos_sum = 0.0
sin_sum = 0.0
for i in range(N):
for j in range(N):
j_next = idx_next[j]
# cos(theta_i - theta_j) = s_i . s_j
cos_sum += spins[i, j, 0] * spins[i, j_next, 0] + spins[i, j, 1] * spins[i, j_next, 1]
# sin(theta_i - theta_j) = cross product
sin_sum += spins[i, j, 0] * spins[i, j_next, 1] - spins[i, j, 1] * spins[i, j_next, 0]
return cos_sum, sin_sum
[docs]
@njit(cache=True, fastmath=True)
def o2_wolff_step_numba(
*,
spins: np.ndarray,
beta: float,
J: float,
idx_next: np.ndarray,
idx_prev: np.ndarray,
in_cluster: np.ndarray,
stack: np.ndarray,
cluster_spins: np.ndarray
) -> tuple:
"""
Perform one Wolff-Evertz cluster reflection on a planar unit-vector field.
A random mirror-plane axis is sampled uniformly from the unit circle, and
each spin is projected onto it. Bonds between neighbours whose projections
share a sign are activated with probability
``P_add = 1 - exp(-2 beta J sigma_i sigma_j)``, and every spin in the
resulting cluster is reflected through the plane perpendicular to the axis.
The reflection preserves unit length exactly.
The bond construction sees only the exchange term, so every O(2) model in
this project shares this update unchanged. Where the Hamiltonian adds a
single-site term that breaks the reflection symmetry, such as the
crystal-field anisotropy of the clock model, detailed balance then holds
for the exchange part alone, so ``ClockSimulation`` rejects this update
when combined with a non-zero anisotropy.
One call constitutes one cluster sweep. ``parallel=True`` is silently
ignored.
Parameters
----------
spins : np.ndarray
(N, N, 2) array of unit vectors.
beta : float
Inverse temperature 1/kT.
J : float
Coupling constant.
idx_next : np.ndarray
Pre-calculated next-neighbor indices (PBC).
idx_prev : np.ndarray
Pre-calculated previous-neighbor indices (PBC).
in_cluster : np.ndarray
Pre-allocated (N, N) boolean array for cluster membership mask.
stack : np.ndarray
Pre-allocated (N*N) int64 array for DFS stack.
cluster_spins : np.ndarray
Pre-allocated (N*N) int64 array to track cluster elements.
Returns
-------
spins
Updated spins array.
cluster_size
Number of spins reflected in this step.
"""
# The caller hands in an all-False in_cluster mask; the reflection loop
# below clears every entry it set, so the buffer stays reusable.
N = spins.shape[0]
# Random mirror-plane axis r\u0302 = (cos phi, sin phi)
phi = np.random.uniform(0.0, 2.0 * np.pi)
rx = np.cos(phi)
ry = np.sin(phi)
# Random seed site
si = np.random.randint(0, N)
sj = np.random.randint(0, N)
# Setup DFS from seed
seed_flat = si * N + sj
in_cluster[si, sj] = True
stack[0] = seed_flat
stack_top = 1
cluster_spins[0] = seed_flat
cluster_size = 1
while stack_top > 0:
stack_top -= 1
flat = stack[stack_top]
ci = flat // N
cj = flat % N
proj_c = spins[ci, cj, 0] * rx + spins[ci, cj, 1] * ry
inxt = idx_next[ci]
iprv = idx_prev[ci]
jnxt = idx_next[cj]
jprv = idx_prev[cj]
# North
if not in_cluster[iprv, cj]:
proj_n = spins[iprv, cj, 0] * rx + spins[iprv, cj, 1] * ry
prod = proj_c * proj_n
if prod > 0.0:
p_add = 1.0 - np.exp(-2.0 * beta * J * prod)
if np.random.random() < p_add:
in_cluster[iprv, cj] = True
new_idx = iprv * N + cj
stack[stack_top] = new_idx
stack_top += 1
cluster_spins[cluster_size] = new_idx
cluster_size += 1
# South
if not in_cluster[inxt, cj]:
proj_n = spins[inxt, cj, 0] * rx + spins[inxt, cj, 1] * ry
prod = proj_c * proj_n
if prod > 0.0:
p_add = 1.0 - np.exp(-2.0 * beta * J * prod)
if np.random.random() < p_add:
in_cluster[inxt, cj] = True
new_idx = inxt * N + cj
stack[stack_top] = new_idx
stack_top += 1
cluster_spins[cluster_size] = new_idx
cluster_size += 1
# West
if not in_cluster[ci, jprv]:
proj_n = spins[ci, jprv, 0] * rx + spins[ci, jprv, 1] * ry
prod = proj_c * proj_n
if prod > 0.0:
p_add = 1.0 - np.exp(-2.0 * beta * J * prod)
if np.random.random() < p_add:
in_cluster[ci, jprv] = True
new_idx = ci * N + jprv
stack[stack_top] = new_idx
stack_top += 1
cluster_spins[cluster_size] = new_idx
cluster_size += 1
# East
if not in_cluster[ci, jnxt]:
proj_n = spins[ci, jnxt, 0] * rx + spins[ci, jnxt, 1] * ry
prod = proj_c * proj_n
if prod > 0.0:
p_add = 1.0 - np.exp(-2.0 * beta * J * prod)
if np.random.random() < p_add:
in_cluster[ci, jnxt] = True
new_idx = ci * N + jnxt
stack[stack_top] = new_idx
stack_top += 1
cluster_spins[cluster_size] = new_idx
cluster_size += 1
# Reflect all cluster spins in-place and reset in_cluster mask
for i in range(cluster_size):
flat = cluster_spins[i]
ci = flat // N
cj = flat % N
proj = spins[ci, cj, 0] * rx + spins[ci, cj, 1] * ry
spins[ci, cj, 0] -= 2.0 * proj * rx
spins[ci, cj, 1] -= 2.0 * proj * ry
in_cluster[ci, cj] = False
return spins, cluster_size
[docs]
class VectorSpinObservablesMixin:
"""Public topological-observable accessors for vector-spin models.
Mixed into ``XYSimulation``, ``ClockSimulation``, and
``DiscreteClockSimulation``, which each provide the private
implementations. Keeping the public wrappers here gives scripts and
analysis helpers a stable API without duplicating docstrings per model.
"""
[docs]
def calculate_vorticity(self) -> np.ndarray:
"""Calculate the vorticity (winding number) of each plaquette.
Returns
-------
np.ndarray
(N, N) array of winding numbers (+1, -1, or 0).
"""
return self._calculate_vorticity() # type: ignore[attr-defined]
[docs]
def get_vortex_density(self) -> float:
"""Calculate the vortex density n_v.
Returns
-------
float
Fraction of plaquettes with non-zero winding, in [0, 1].
"""
return self._get_vortex_density() # type: ignore[attr-defined]
[docs]
def get_helicity_data(self) -> tuple[float, float]:
"""Calculate the helicity-modulus raw sums along the x-direction.
Returns
-------
cos_sum : float
Sum of cosine of nearest-neighbor angle differences.
sin_sum : float
Sum of sine of nearest-neighbor angle differences.
"""
return self._get_helicity_data() # type: ignore[attr-defined]
[docs]
class MonteCarloSimulation(ABC):
"""
Abstract base class for 2D lattice Monte Carlo simulations.
Provides infrastructure for equilibration, measurement runs, and statistical analysis.
"""
def __init__(
self, *, size: int, temp: float, init_state: str = 'random', seed: int | None = None
):
"""
Initialize the simulation.
Parameters
----------
size : int
Linear dimension L of the N x N lattice.
temp : float
Temperature T of the system.
init_state : str
Initial spin configuration: ``'random'`` (default) or ``'ordered'``.
seed : int | None
Optional random seed for reproducibility.
Raises
------
ValueError
If ``size`` is not a positive integer or ``temp`` is not positive.
"""
if not isinstance(size, (int, np.integer)) or size < 1:
raise ValueError(f'size must be a positive integer, got {size!r}')
if temp <= 0.0:
raise ValueError(f'temp must be positive (T > 0), got {temp}')
if init_state not in {'random', 'ordered'}:
raise ValueError(f"init_state must be 'random' or 'ordered', got {init_state!r}")
self.size = size
self.temp = temp
self.init_state = init_state
self.beta = 1.0 / temp
self.steps = 0
self.seed = seed
self.rng = np.random.default_rng(seed)
self.spins: np.ndarray | None = None # To be initialized by subclasses
self.idx_next = np.roll(np.arange(size), -1)
self.idx_prev = np.roll(np.arange(size), 1)
# Pre-allocated buffers for Wolff cluster algorithms
self._wolff_cluster_mask = np.zeros((size, size), dtype=np.bool_)
self._wolff_stack = np.empty(size * size, dtype=np.int64)
self._wolff_cluster_spins = np.empty(size * size, dtype=np.int64)
# Last Wolff cluster size (0 for non-Wolff updates or before any step)
self.last_cluster_size: int = 0
# Pre-calculate radial distance bins for correlation analysis
center = size // 2
iy, ix = np.indices((size, size))
r = np.sqrt((ix - center) ** 2 + (iy - center) ** 2)
self._r_int_pre = r.astype(int).ravel()
self._nr_pre = np.bincount(self._r_int_pre)
self._r_range_pre = np.arange(center)
@staticmethod
def _validate_coupling(*, J: float) -> None:
"""Reject couplings the kernels cannot sample correctly.
The Metropolis acceptance tables and the Wolff bond probability
``1 - exp(-2 beta J ...)`` are derived for ferromagnetic exchange.
With ``J < 0`` the precomputed Boltzmann factors exceed one and the
cluster bond probability turns negative, so the chains would no longer
satisfy detailed balance.
Parameters
----------
J : float
Exchange coupling constant.
Raises
------
ValueError
If ``J`` is negative or not finite.
"""
if not np.isfinite(J) or J < 0.0:
raise ValueError(
f'J must be a finite, non-negative (ferromagnetic) coupling, got {J}'
)
def _validate_parallel_checkerboard(self, *, parallel: bool, update: str) -> None:
"""Reject the parallel checkerboard kernel on lattices with odd L.
The two sublattices are independent only when L is even. For odd L
the periodic wrap makes rows 0 and L - 1 (and columns 0 and L - 1)
nearest neighbours of the same parity, and the ``prange`` loop may
update them on different threads at the same time, so a site can
read a neighbour that is being rewritten. The serial checkerboard
sweep stays valid for odd L, because it is an ordinary sequential
single-site update.
Parameters
----------
parallel : bool
Whether the parallel kernel was requested.
update : str
Update scheme; only ``'checkerboard'`` uses the parallel kernel.
Raises
------
ValueError
If ``parallel`` is set with the checkerboard update on odd ``L``.
"""
if parallel and update == 'checkerboard' and self.size % 2 == 1:
raise ValueError(
f'parallel=True with the checkerboard update needs an even lattice size, '
f'got L={self.size}: for odd L the periodic boundary joins same-parity '
'sites and the parallel sublattice sweep would race. Use an even L or '
'parallel=False.'
)
def _reseed_numba_for_step(self) -> None:
"""Reseed Numba's RNG deterministically for the upcoming sweep.
No-op when the simulation is unseeded. Serial kernels become fully
reproducible; parallel (``prange``) kernels are NOT seed-reproducible
because only the calling thread's Numba RNG state is seeded.
"""
if self.seed is not None:
_seed_numba(seed=_derive_step_seed(seed=self.seed, step=self.steps))
[docs]
@abstractmethod
def step(self) -> None:
"""Perform one full Monte Carlo sweep of the lattice."""
@abstractmethod
def _get_magnetization(self) -> float:
"""Return the current absolute magnetization per site."""
@abstractmethod
def _get_energy(self) -> float:
"""Return the current energy per site."""
@abstractmethod
def _get_structure_factor_squared_unshifted(self) -> np.ndarray:
"""Return the unshifted squared magnitude of the Fourier transform of spins."""
def _calculate_structure_factor(self) -> np.ndarray:
"""Calculate the 2D structure factor S(k)."""
Sk_sq = self._get_structure_factor_squared_unshifted()
return np.fft.fftshift(Sk_sq) / (self.size**2)
def _calculate_correlation_function(self) -> tuple[np.ndarray, np.ndarray]:
"""
Calculate the real-space spin-spin correlation function G(r)
by taking the inverse Fourier transform of the structure factor S(k).
Returns
-------
r : np.ndarray
Radial distances.
G_r : np.ndarray
Radially averaged correlation values.
"""
Sk_sq = self._get_structure_factor_squared_unshifted()
# G(r) is the inverse Fourier transform of S(k) (Wiener-Khinchin theorem)
G_r_map = np.real(np.fft.ifft2(Sk_sq))
# Shift the (0,0) correlation to the center of the map for radial averaging
G_r_map = np.fft.fftshift(G_r_map)
# Radially average G(r) using pre-calculated masks
tbin = np.bincount(self._r_int_pre, G_r_map.ravel())
# Avoid division by zero
radial_profile = np.divide(
tbin, self._nr_pre, out=np.zeros_like(tbin, dtype=float), where=self._nr_pre != 0
)
# Normalize by G(0) so that G(0) = 1
if radial_profile[0] != 0:
radial_profile /= radial_profile[0]
center = self.size // 2
return self._r_range_pre, radial_profile[:center]
[docs]
def get_spin_field(self) -> np.ndarray:
"""Return the spin configuration in its physical representation.
Scalar models return the ``(L, L)`` array of spins; vector models
return ``(L, L, 2)`` unit vectors. Models that store an internal
encoding (the discrete clock model keeps integer state indices)
override this method, so analysis helpers never misread state
indices as scalar spin values.
Returns
-------
np.ndarray
Spin field suitable for structure-factor and correlation analysis.
Raises
------
RuntimeError
If the lattice has not been initialised.
"""
if self.spins is None:
raise RuntimeError('Simulation lattice is uninitialized (spins is None).')
return self.spins
[docs]
def get_magnetization(self) -> float:
"""Return the current absolute magnetization per site.
Public accessor for scripts and analysis helpers; delegates to the
model-specific implementation.
Returns
-------
float
Absolute magnetization per site.
"""
return self._get_magnetization()
[docs]
def get_energy(self) -> float:
"""Return the current energy per site.
Public accessor for scripts and analysis helpers; delegates to the
model-specific implementation.
Returns
-------
float
Energy per site.
"""
return self._get_energy()
[docs]
def calculate_correlation_function(self) -> tuple[np.ndarray, np.ndarray]:
"""Calculate the radially averaged spin-spin correlation function G(r).
Public accessor for scripts and analysis helpers.
Returns
-------
r : np.ndarray
Radial distances.
G_r : np.ndarray
Radially averaged correlation values, normalized to G(0) = 1.
"""
return self._calculate_correlation_function()
[docs]
def equilibrate(self, *, n_steps: int) -> None:
"""
Perform equilibration steps without recording measurements.
Parameters
----------
n_steps : int
Number of MC steps to perform.
"""
for _ in range(n_steps):
self.step()
[docs]
def run(self, *, n_steps: int) -> tuple[np.ndarray, np.ndarray]:
"""
Run the simulation and record magnetization and energy at each step.
Parameters
----------
n_steps : int
Number of MC steps to perform and record.
Returns
-------
magnetization : np.ndarray
Array of recorded magnetization values.
energies : np.ndarray
Array of recorded energy values.
"""
magnetization: np.ndarray = np.empty(n_steps)
energies: np.ndarray = np.empty(n_steps)
for i in range(n_steps):
self.step()
magnetization[i] = self._get_magnetization()
energies[i] = self._get_energy()
return magnetization, energies
[docs]
def run_with_cluster_sizes(self, *, n_steps: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""
Run the simulation and additionally record the cluster size at every step.
For non-cluster update schemes the cluster-size array is filled with
zeros, because a local Metropolis move flips exactly one spin. A
convention of one would be equally defensible; zero was chosen so that
misuse of this method on a local update is easy to spot in the output.
Parameters
----------
n_steps : int
Number of MC steps to perform and record.
Returns
-------
magnetization : np.ndarray
Magnetization per spin at each step.
energies : np.ndarray
Energy per spin at each step.
cluster_sizes : np.ndarray
Number of spins the update touched at each step, zero for every
non-cluster scheme.
"""
magnetization = np.empty(n_steps, dtype=float)
energies = np.empty(n_steps, dtype=float)
cluster_sizes = np.zeros(n_steps, dtype=int)
for i in range(n_steps):
self.step()
magnetization[i] = self._get_magnetization()
energies[i] = self._get_energy()
cluster_sizes[i] = self.last_cluster_size
return magnetization, energies, cluster_sizes