Source code for models.simulation_base

"""
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