Source code for models.clock_model

"""
2D q-state Clock Model simulation using Metropolis-Hastings and Wolff cluster algorithms.

NOTE: ``ClockSimulation`` (continuous XY-plus-anisotropy form) and
``DiscreteClockSimulation`` (integer state indices with cosine lookup tables) are
collocated here for convenience.  When either class grows beyond roughly 400 lines
of unique logic, split them into ``clock_model_continuous.py`` and
``clock_model_discrete.py`` and keep this file as a re-export shim for backward
compatibility.
"""
from __future__ import annotations

import os

import matplotlib.pyplot as plt
import numpy as np
from numba import njit, prange

from .simulation_base import (
    MonteCarloSimulation,
    VectorSpinObservablesMixin,
    calculate_vortex_density_numba,
    calculate_vorticity_numba,
    get_helicity_data_numba,
    o2_wolff_step_numba,
)


[docs] @njit(cache=True, fastmath=True) def clock_step_numba( *, spins: np.ndarray, beta: float, J: float, A: float, q: int, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ Perform one full Monte Carlo sweep of the Clock Model lattice. Uses a checkerboard update pattern for better Numba optimization. Parameters ---------- spins : np.ndarray (N, N, 2) array of unit vectors. beta : float Inverse temperature 1/kT. J : float Coupling constant. A : float Anisotropy strength. q : int Number of clock states. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] # Batch generate random updates deltas = np.random.uniform(-0.5, 0.5, size=(N, N)) cos_vals = np.cos(deltas) sin_vals = np.sin(deltas) random_vals = np.random.random(size=(N, N)) for parity in range(2): for i in range(N): # Use striding to avoid 'if' condition in the inner loop start_j = (parity + i) % 2 inxt = idx_next[i] iprv = idx_prev[i] for j in range(start_j, N, 2): jnxt = idx_next[j] jprv = idx_prev[j] # Neighbor sum nx = spins[iprv, j, 0] + spins[inxt, j, 0] + spins[i, jprv, 0] + spins[i, jnxt, 0] ny = spins[iprv, j, 1] + spins[inxt, j, 1] + spins[i, jprv, 1] + spins[i, jnxt, 1] sx, sy = spins[i, j, 0], spins[i, j, 1] # Proposed update from pre-calculated values delta = deltas[i, j] c, s = cos_vals[i, j], sin_vals[i, j] sx_new = sx * c - sy * s sy_new = sx * s + sy * c norm = np.sqrt(sx_new**2 + sy_new**2) sx_new /= norm sy_new /= norm # Interaction Energy Change dE_inter = -J * ((sx_new * nx + sy_new * ny) - (sx * nx + sy * ny)) # Anisotropy Energy Change phi_old = np.arctan2(sy, sx) phi_new = phi_old + delta dE_aniso = -A * (np.cos(q * phi_new) - np.cos(q * phi_old)) dE = dE_inter + dE_aniso if dE <= 0 or random_vals[i, j] < np.exp(-dE * beta): spins[i, j, 0] = sx_new spins[i, j, 1] = sy_new return spins
[docs] @njit(cache=True, fastmath=True, parallel=True) def clock_step_parallel_numba( *, spins: np.ndarray, beta: float, J: float, A: float, q: int, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ Parallel version of clock_step_numba. Parameters ---------- spins : np.ndarray (N, N, 2) array of unit vectors. beta : float Inverse temperature 1/kT. J : float Coupling constant. A : float Anisotropy strength. q : int Number of clock states. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] deltas = np.random.uniform(-0.5, 0.5, size=(N, N)) cos_vals = np.cos(deltas) sin_vals = np.sin(deltas) random_vals = np.random.random(size=(N, N)) for parity in range(2): for i in prange(N): start_j = (parity + i) % 2 inxt = idx_next[i] iprv = idx_prev[i] for j in range(start_j, N, 2): jnxt = idx_next[j] jprv = idx_prev[j] nx = spins[iprv, j, 0] + spins[inxt, j, 0] + spins[i, jprv, 0] + spins[i, jnxt, 0] ny = spins[iprv, j, 1] + spins[inxt, j, 1] + spins[i, jprv, 1] + spins[i, jnxt, 1] sx, sy = spins[i, j, 0], spins[i, j, 1] delta = deltas[i, j] c, s = cos_vals[i, j], sin_vals[i, j] sx_new = sx * c - sy * s sy_new = sx * s + sy * c norm = np.sqrt(sx_new**2 + sy_new**2) sx_new /= norm sy_new /= norm dE_inter = -J * ((sx_new * nx + sy_new * ny) - (sx * nx + sy * ny)) phi_old = np.arctan2(sy, sx) phi_new = phi_old + delta dE_aniso = -A * (np.cos(q * phi_new) - np.cos(q * phi_old)) dE = dE_inter + dE_aniso if dE <= 0 or random_vals[i, j] < np.exp(-dE * beta): spins[i, j, 0] = sx_new spins[i, j, 1] = sy_new return spins
[docs] @njit(cache=True, fastmath=True) def clock_step_random_numba( *, spins: np.ndarray, beta: float, J: float, A: float, q: int, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ Perform one full Monte Carlo sweep of the Clock Model lattice using random sequential updates. Parameters ---------- spins : np.ndarray (N, N, 2) array of unit vectors. beta : float Inverse temperature 1/kT. J : float Coupling constant. A : float Anisotropy strength. q : int Number of clock states. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] num_attempts = N * N # Pre-calculate random indices and updates indices = np.random.randint(0, num_attempts, size=num_attempts) deltas = np.random.uniform(-0.5, 0.5, size=num_attempts) cos_vals = np.cos(deltas) sin_vals = np.sin(deltas) random_vals = np.random.random(size=num_attempts) for k in range(num_attempts): idx = indices[k] i = idx // N j = idx % N inxt = idx_next[i] iprv = idx_prev[i] jnxt = idx_next[j] jprv = idx_prev[j] # Neighbor sum nx = spins[iprv, j, 0] + spins[inxt, j, 0] + spins[i, jprv, 0] + spins[i, jnxt, 0] ny = spins[iprv, j, 1] + spins[inxt, j, 1] + spins[i, jprv, 1] + spins[i, jnxt, 1] sx, sy = spins[i, j, 0], spins[i, j, 1] # Proposed update delta = deltas[k] c, s = cos_vals[k], sin_vals[k] sx_new = sx * c - sy * s sy_new = sx * s + sy * c norm = np.sqrt(sx_new**2 + sy_new**2) sx_new /= norm sy_new /= norm # Interaction Energy Change dE_inter = -J * ((sx_new * nx + sy_new * ny) - (sx * nx + sy * ny)) # Anisotropy Energy Change phi_old = np.arctan2(sy, sx) phi_new = phi_old + delta dE_aniso = -A * (np.cos(q * phi_new) - np.cos(q * phi_old)) dE = dE_inter + dE_aniso if dE <= 0 or random_vals[k] < np.exp(-dE * beta): spins[i, j, 0] = sx_new spins[i, j, 1] = sy_new return spins
[docs] @njit(cache=True, fastmath=True) def clock_energy_numba( *, spins: np.ndarray, J: float, A: float, q: int, idx_next: np.ndarray ) -> float: """ Calculate the total energy of the Clock Model lattice. Parameters ---------- spins : np.ndarray (N, N, 2) array of unit vectors. J : float Coupling constant. A : float Anisotropy strength. q : int Number of clock states. idx_next : np.ndarray Pre-calculated next-neighbor indices. Returns ------- energy : float Total energy per site. """ N = spins.shape[0] energy = 0.0 for i in range(N): inxt = idx_next[i] for j in range(N): jnxt = idx_next[j] # Interaction dot_right = spins[i, j, 0] * spins[i, jnxt, 0] + spins[i, j, 1] * spins[i, jnxt, 1] dot_down = spins[i, j, 0] * spins[inxt, j, 0] + spins[i, j, 1] * spins[inxt, j, 1] energy -= J * (dot_right + dot_down) # Anisotropy phi = np.arctan2(spins[i, j, 1], spins[i, j, 0]) energy -= A * np.cos(q * phi) return energy / (N * N)
[docs] class ClockSimulation(VectorSpinObservablesMixin, MonteCarloSimulation): """ Simulation of the 2D q-state clock model on a square lattice. """ _VALID_UPDATES: frozenset = frozenset({'checkerboard', 'random', 'wolff'}) def __init__( self, *, size: int, temp: float, J: float = 1.0, A: float = 1.0, q: int = 6, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None, ): """ Initialize the Clock Model simulation. Parameters ---------- size : int Linear dimension L of the L x L lattice. temp : float Temperature T. J : float Coupling constant (default 1.0). A : float Anisotropy strength (default 1.0). q : int Number of clock states (default 6). Must be \u2265 2. update : str Update scheme - ``'checkerboard'`` (default, faster), ``'random'`` (random sequential Metropolis, physical stochastic dynamics for kinetics studies), or ``'wolff'`` (Wolff-Evertz cluster algorithm using the exchange term J; only valid for A=0, where the model reduces to XY). init_state : str Initial spin configuration: ``'random'`` (default) or ``'ordered'``. parallel : bool Whether to use parallelized Numba kernels (only for checkerboard). Parallel kernels are NOT seed-reproducible: only the calling thread's Numba RNG is seeded, so two runs with the same seed may differ. Requires an even ``size``. seed : int | None Optional random seed for reproducibility. Raises ------ ValueError If ``q`` is less than 2, the update scheme is unknown, ``J`` is negative, or ``update='wolff'`` is combined with ``A != 0``. """ super().__init__(size=size, temp=temp, init_state=init_state, seed=seed) if q < 2: raise ValueError(f'q must be >= 2 (number of clock states), got {q}') if update not in self._VALID_UPDATES: valid_opts = sorted(self._VALID_UPDATES) raise ValueError(f'Unknown update scheme {update!r}. Valid options: {valid_opts}') if update == 'wolff' and A != 0.0: # The Wolff-Evertz reflection sees only the exchange term, so the # chain samples the anisotropic Boltzmann weight only for A = 0; # with A != 0 it would silently sample the XY model instead. raise ValueError( f"ClockSimulation with update='wolff' requires A=0.0 (got A={A}): " f'the cluster reflection ignores the anisotropy term and violates ' f'detailed balance otherwise. Use a local update scheme, or ' f"DiscreteClockSimulation with update='wolff'." ) self._validate_coupling(J=J) self.J = J self.A = A self.q = q self.update = update self._validate_parallel_checkerboard(parallel=parallel, update=update) self.parallel = parallel if self.init_state == 'ordered': # Ordered state: all spins at angle 0 -> (1, 0) self.spins = np.zeros((size, size, 2), dtype=float) self.spins[..., 0] = 1.0 else: # Initialize random spins as 2D unit vectors angles = self.rng.uniform(0, 2 * np.pi, size=(size, size)) self.spins = np.stack([np.cos(angles), np.sin(angles)], axis=-1)
[docs] def step(self) -> None: """Perform one Monte Carlo step using Numba.""" if self.spins is not None: self._reseed_numba_for_step() if self.update == 'random': self.spins = clock_step_random_numba( spins=self.spins, beta=self.beta, J=self.J, A=self.A, q=self.q, idx_next=self.idx_next, idx_prev=self.idx_prev, ) elif self.update == 'wolff': self.spins, self.last_cluster_size = o2_wolff_step_numba( spins=self.spins, beta=self.beta, J=self.J, idx_next=self.idx_next, idx_prev=self.idx_prev, in_cluster=self._wolff_cluster_mask, stack=self._wolff_stack, cluster_spins=self._wolff_cluster_spins, ) elif self.parallel: self.spins = clock_step_parallel_numba( spins=self.spins, beta=self.beta, J=self.J, A=self.A, q=self.q, idx_next=self.idx_next, idx_prev=self.idx_prev, ) else: self.spins = clock_step_numba( spins=self.spins, beta=self.beta, J=self.J, A=self.A, q=self.q, idx_next=self.idx_next, idx_prev=self.idx_prev, ) self.steps += 1
def _get_magnetization(self) -> float: """Calculate magnetization magnitude per spin.""" if self.spins is not None: total_spin = np.sum(self.spins, axis=(0, 1)) return float(np.linalg.norm(total_spin) / (self.size**2)) return 0.0 def _get_energy(self) -> float: """Calculate energy per spin.""" if self.spins is not None: return float( clock_energy_numba( spins=self.spins, J=self.J, A=self.A, q=self.q, idx_next=self.idx_next ) ) return 0.0 def _calculate_vorticity(self) -> np.ndarray: """Calculate the vorticity (winding number) of each plaquette.""" if self.spins is not None: return np.asarray(calculate_vorticity_numba(spins=self.spins, idx_next=self.idx_next)) return np.array([]) def _get_vortex_density(self) -> float: """Calculate vortex density n_v, the fraction of plaquettes with non-zero winding.""" if self.spins is not None: return float(calculate_vortex_density_numba(spins=self.spins, idx_next=self.idx_next)) return 0.0 def _get_helicity_data(self) -> tuple[float, float]: """Calculate sum of cos and sin of angle differences in x-direction.""" if self.spins is not None: cos_sum, sin_sum = get_helicity_data_numba(spins=self.spins, idx_next=self.idx_next) return float(cos_sum), float(sin_sum) return 0.0, 0.0 def _get_structure_factor_squared_unshifted(self) -> np.ndarray: """Calculate the unshifted squared magnitude of the Fourier transform.""" if self.spins is not None: sx = self.spins[..., 0] sy = self.spins[..., 1] Sk_x = np.fft.fft2(sx) Sk_y = np.fft.fft2(sy) return np.asarray(np.abs(Sk_x) ** 2 + np.abs(Sk_y) ** 2) return np.array([])
# --------------------------------------------------------------------------- # Discrete q-state clock model (integer spin representation) # ---------------------------------------------------------------------------
[docs] @njit(cache=True, fastmath=True) def discrete_clock_step_numba( *, spins: np.ndarray, beta: float, J: float, q: int, cos_table: np.ndarray, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ One Metropolis sweep of the discrete clock model (checkerboard update). Parameters ---------- spins : np.ndarray (N, N) array of integer spin states in {0, ..., q-1}. beta : float Inverse temperature 1/kT. J : float Coupling constant. q : int Number of clock states. cos_table : np.ndarray Pre-computed cos(2*pi*d/q) for d in {0, ..., q-1}. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] proposals = np.random.randint(0, q, size=(N, N)) random_vals = np.random.random(size=(N, N)) for parity in range(2): for i in range(N): start_j = (parity + i) % 2 inxt = idx_next[i] iprv = idx_prev[i] for j in range(start_j, N, 2): jnxt = idx_next[j] jprv = idx_prev[j] s_old = spins[i, j] s_new = proposals[i, j] if s_new == s_old: continue # Neighbor states n0 = spins[iprv, j] n1 = spins[inxt, j] n2 = spins[i, jprv] n3 = spins[i, jnxt] # dE = -J * sum_nn [cos(theta_new - theta_nn) - cos(theta_old - theta_nn)] dE = -J * ( cos_table[(s_new - n0) % q] + cos_table[(s_new - n1) % q] + cos_table[(s_new - n2) % q] + cos_table[(s_new - n3) % q] - cos_table[(s_old - n0) % q] - cos_table[(s_old - n1) % q] - cos_table[(s_old - n2) % q] - cos_table[(s_old - n3) % q] ) if dE <= 0 or random_vals[i, j] < np.exp(-dE * beta): spins[i, j] = s_new return spins
[docs] @njit(cache=True, fastmath=True, parallel=True) def discrete_clock_step_parallel_numba( *, spins: np.ndarray, beta: float, J: float, q: int, cos_table: np.ndarray, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ Parallel version of discrete_clock_step_numba. Parameters ---------- spins : np.ndarray (N, N) array of integer spin states in {0, ..., q-1}. beta : float Inverse temperature 1/kT. J : float Coupling constant. q : int Number of clock states. cos_table : np.ndarray Pre-computed cos(2*pi*d/q) for d in {0, ..., q-1}. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] proposals = np.random.randint(0, q, size=(N, N)) random_vals = np.random.random(size=(N, N)) for parity in range(2): for i in prange(N): start_j = (parity + i) % 2 inxt = idx_next[i] iprv = idx_prev[i] for j in range(start_j, N, 2): jnxt = idx_next[j] jprv = idx_prev[j] s_old = spins[i, j] s_new = proposals[i, j] if s_new == s_old: continue n0, n1 = spins[iprv, j], spins[inxt, j] n2, n3 = spins[i, jprv], spins[i, jnxt] dE = -J * ( cos_table[(s_new - n0) % q] + cos_table[(s_new - n1) % q] + cos_table[(s_new - n2) % q] + cos_table[(s_new - n3) % q] - cos_table[(s_old - n0) % q] - cos_table[(s_old - n1) % q] - cos_table[(s_old - n2) % q] - cos_table[(s_old - n3) % q] ) if dE <= 0 or random_vals[i, j] < np.exp(-dE * beta): spins[i, j] = s_new return spins
[docs] @njit(cache=True, fastmath=True) def discrete_clock_step_random_numba( *, spins: np.ndarray, beta: float, J: float, q: int, cos_table: np.ndarray, idx_next: np.ndarray, idx_prev: np.ndarray, ) -> np.ndarray: """ One Metropolis sweep of the discrete clock model (random sequential update). N^2 single-spin flip attempts at uniformly random sites, giving physical stochastic dynamics suitable for kinetics studies. Parameters ---------- spins : np.ndarray (N, N) array of integer spin states in {0, ..., q-1}. beta : float Inverse temperature 1/kT. J : float Coupling constant. q : int Number of clock states. cos_table : np.ndarray Pre-computed cos(2*pi*d/q) for d in {0, ..., q-1}. idx_next : np.ndarray Pre-calculated next-neighbor indices. idx_prev : np.ndarray Pre-calculated previous-neighbor indices. Returns ------- np.ndarray Updated spins array. """ N = spins.shape[0] num_attempts = N * N indices = np.random.randint(0, num_attempts, size=num_attempts) proposals = np.random.randint(0, q, size=num_attempts) random_vals = np.random.random(size=num_attempts) for k in range(num_attempts): idx = indices[k] i = idx // N j = idx % N s_old = spins[i, j] s_new = proposals[k] if s_new == s_old: continue inxt = idx_next[i] iprv = idx_prev[i] jnxt = idx_next[j] jprv = idx_prev[j] n0 = spins[iprv, j] n1 = spins[inxt, j] n2 = spins[i, jprv] n3 = spins[i, jnxt] dE = -J * ( cos_table[(s_new - n0) % q] + cos_table[(s_new - n1) % q] + cos_table[(s_new - n2) % q] + cos_table[(s_new - n3) % q] - cos_table[(s_old - n0) % q] - cos_table[(s_old - n1) % q] - cos_table[(s_old - n2) % q] - cos_table[(s_old - n3) % q] ) if dE <= 0 or random_vals[k] < np.exp(-dE * beta): spins[i, j] = s_new return spins
[docs] @njit(cache=True, fastmath=True) def discrete_clock_wolff_step_numba( *, spins: np.ndarray, beta: float, J: float, q: int, sigma_table: np.ndarray, idx_next: np.ndarray, idx_prev: np.ndarray, in_cluster: np.ndarray, stack: np.ndarray, cluster_spins: np.ndarray, ) -> tuple: """ Perform one Wolff cluster reflection on the discrete clock lattice. The reflection axis is drawn uniformly from the q mirror axes of the regular q-gon, at angles ``phi_m = pi * m / q``. Reflecting the angle ``theta_s = 2 pi s / q`` about ``phi_m`` gives ``2 phi_m - theta_s``, which is again an allowed state, ``s' = (m - s) mod q``. The update therefore never leaves the discrete state space, and because every state ``s'`` is reachable from ``s`` with a single-site cluster, the chain is ergodic. Bonds follow the Wolff-Evertz rule: with ``sigma_i`` the component of spin ``i`` perpendicular to the mirror axis, a bond to a neighbour is activated with probability ``1 - exp(-2 beta J sigma_i sigma_j)`` when ``sigma_i sigma_j > 0`` and never otherwise. Each reflection is an involution chosen with the same probability in both directions, so detailed balance holds for the full discrete Hamiltonian. One call constitutes one cluster flip, not one lattice sweep. Parameters ---------- spins : np.ndarray (N, N) array of integer spin states in {0, ..., q-1}. beta : float Inverse temperature 1/kT. J : float Coupling constant. q : int Number of clock states. sigma_table : np.ndarray Length-2q table with ``sigma_table[k] = sin(pi k / q)``, exactly antisymmetric under ``k -> 2q - k``. The perpendicular projection of state ``s`` for mirror axis ``m`` is ``sigma_table[(2 s - m) mod 2q]``. 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] two_q = 2 * q # Mirror axis index; 2*s - m + 2q is non-negative for s, m in [0, q). m = np.random.randint(0, q) offset = two_q - m si = np.random.randint(0, N) sj = np.random.randint(0, N) 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 sig_c = sigma_table[(2 * spins[ci, cj] + offset) % two_q] inxt = idx_next[ci] iprv = idx_prev[ci] jnxt = idx_next[cj] jprv = idx_prev[cj] # North if not in_cluster[iprv, cj]: prod = sig_c * sigma_table[(2 * spins[iprv, cj] + offset) % two_q] if prod > 0.0: if np.random.random() < 1.0 - np.exp(-2.0 * beta * J * prod): 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]: prod = sig_c * sigma_table[(2 * spins[inxt, cj] + offset) % two_q] if prod > 0.0: if np.random.random() < 1.0 - np.exp(-2.0 * beta * J * prod): 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]: prod = sig_c * sigma_table[(2 * spins[ci, jprv] + offset) % two_q] if prod > 0.0: if np.random.random() < 1.0 - np.exp(-2.0 * beta * J * prod): 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]: prod = sig_c * sigma_table[(2 * spins[ci, jnxt] + offset) % two_q] if prod > 0.0: if np.random.random() < 1.0 - np.exp(-2.0 * beta * J * prod): 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 every cluster spin, s -> (m - s) mod q, and reset the mask. for k in range(cluster_size): flat = cluster_spins[k] ci = flat // N cj = flat % N spins[ci, cj] = (m - spins[ci, cj] + q) % q in_cluster[ci, cj] = False return spins, cluster_size
[docs] @njit(cache=True, fastmath=True) def discrete_clock_energy_numba( *, spins: np.ndarray, J: float, q: int, cos_table: np.ndarray, idx_next: np.ndarray, ) -> float: """ Total energy per site of the discrete clock model. Sums -J * cos(theta_i - theta_j) over unique right/down neighbor pairs. Parameters ---------- spins : np.ndarray (N, N) array of integer spin states in {0, ..., q-1}. J : float Coupling constant. q : int Number of clock states. cos_table : np.ndarray Pre-computed cos(2*pi*d/q) for d in {0, ..., q-1}. idx_next : np.ndarray Pre-calculated next-neighbor indices. Returns ------- float Energy per site. """ N = spins.shape[0] energy = 0.0 for i in range(N): inxt = idx_next[i] for j in range(N): jnxt = idx_next[j] s = spins[i, j] energy -= J * ( cos_table[(s - spins[i, jnxt]) % q] + cos_table[(s - spins[inxt, j]) % q] ) return energy / (N * N)
[docs] class DiscreteClockSimulation(VectorSpinObservablesMixin, MonteCarloSimulation): """ Simulation of the 2D q-state clock model with discrete integer spins. Each spin takes one of q evenly spaced orientations theta_k = 2*pi*k/q. The Hamiltonian is E = -J * sum_<i,j> cos(theta_i - theta_j). Unlike ``ClockSimulation``, which uses continuous unit-vector spins plus an anisotropy term, this class represents spins as integers in {0, ..., q-1} and enforces the discrete symmetry exactly. """ _VALID_UPDATES: frozenset = frozenset({'checkerboard', 'random', 'wolff'}) def __init__( self, *, size: int, temp: float, J: float = 1.0, q: int = 6, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None, ): """ Initialize the discrete clock model simulation. Parameters ---------- size : int Linear dimension L of the L x L lattice. temp : float Temperature T. J : float Coupling constant (default 1.0). q : int Number of clock states (default 6). Must be >= 2. update : str Update scheme - ``'checkerboard'`` (default, faster), ``'random'`` (random sequential Metropolis, more physical stochastic dynamics for kinetics studies), or ``'wolff'`` (Wolff cluster reflections about the q mirror axes; one step is one cluster flip). init_state : str Initial spin configuration: ``'random'`` (default) or ``'ordered'``. parallel : bool Whether to use parallelized Numba kernels (only for checkerboard). Parallel kernels are NOT seed-reproducible: only the calling thread's Numba RNG is seeded, so two runs with the same seed may differ. Requires an even ``size``. seed : int | None Optional random seed for reproducibility. Raises ------ ValueError If ``q`` is less than 2, the update scheme is unknown, or ``J`` is negative. """ super().__init__(size=size, temp=temp, init_state=init_state, seed=seed) if q < 2: raise ValueError(f'q must be >= 2 (number of clock states), got {q}') if update not in self._VALID_UPDATES: valid_opts = sorted(self._VALID_UPDATES) raise ValueError(f'Unknown update scheme {update!r}. Valid options: {valid_opts}') self._validate_coupling(J=J) self.J = J self.q = q self.update = update self._validate_parallel_checkerboard(parallel=parallel, update=update) self.parallel = parallel # Pre-compute lookup tables (no trig inside kernels) angles = 2.0 * np.pi * np.arange(q) / q self.cos_table = np.cos(angles) # cos(2*pi*d/q) for dE calculation self._cos_angles = np.cos(angles) # per-state cos for observables self._sin_angles = np.sin(angles) # per-state sin for observables # Perpendicular projections for the Wolff reflection, sin(pi k / q) # for k in [0, 2q). Mirroring the upper half enforces the exact # antisymmetry sigma[2q - k] = -sigma[k] that detailed balance relies # on, independent of floating-point rounding in np.sin. half = np.sin(np.pi * np.arange(q + 1) / q) half[0] = 0.0 half[q] = 0.0 self._wolff_sigma_table = np.concatenate([half[:q], -half[q:0:-1]]) if self.init_state == 'ordered': # Initialize ordered discrete spins (state 0) self.spins = np.zeros((size, size), dtype=np.int32) else: # Initialize random discrete spins self.spins = self.rng.integers(0, q, size=(size, size), dtype=np.int32)
[docs] def step(self) -> None: """Perform one Monte Carlo sweep using Numba.""" if self.spins is not None: self._reseed_numba_for_step() if self.update == 'random': self.spins = discrete_clock_step_random_numba( spins=self.spins, beta=self.beta, J=self.J, q=self.q, cos_table=self.cos_table, idx_next=self.idx_next, idx_prev=self.idx_prev, ) elif self.update == 'wolff': self.spins, self.last_cluster_size = discrete_clock_wolff_step_numba( spins=self.spins, beta=self.beta, J=self.J, q=self.q, sigma_table=self._wolff_sigma_table, idx_next=self.idx_next, idx_prev=self.idx_prev, in_cluster=self._wolff_cluster_mask, stack=self._wolff_stack, cluster_spins=self._wolff_cluster_spins, ) elif self.parallel: self.spins = discrete_clock_step_parallel_numba( spins=self.spins, beta=self.beta, J=self.J, q=self.q, cos_table=self.cos_table, idx_next=self.idx_next, idx_prev=self.idx_prev, ) else: self.spins = discrete_clock_step_numba( spins=self.spins, beta=self.beta, J=self.J, q=self.q, cos_table=self.cos_table, idx_next=self.idx_next, idx_prev=self.idx_prev, ) self.steps += 1
def _get_magnetization(self) -> float: """Calculate magnetization magnitude per spin.""" if self.spins is not None: mx = np.sum(self._cos_angles[self.spins]) my = np.sum(self._sin_angles[self.spins]) return float(np.sqrt(mx**2 + my**2) / (self.size**2)) return 0.0 def _get_energy(self) -> float: """Calculate energy per spin.""" if self.spins is not None: return float( discrete_clock_energy_numba( spins=self.spins, J=self.J, q=self.q, cos_table=self.cos_table, idx_next=self.idx_next, ) ) return 0.0 def _spins_as_vectors(self) -> np.ndarray: """Convert integer spin states to (N, N, 2) unit-vector representation.""" sx = self._cos_angles[self.spins] sy = self._sin_angles[self.spins] return np.stack([sx, sy], axis=-1)
[docs] def get_spin_field(self) -> np.ndarray: """Return the spins as ``(L, L, 2)`` unit vectors. The integer state indices are an internal encoding; analysis helpers need the planar vectors they represent. Returns ------- np.ndarray Unit-vector field of shape ``(L, L, 2)``. 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_as_vectors()
def _calculate_vorticity(self) -> np.ndarray: """Calculate the vorticity (winding number) of each plaquette.""" if self.spins is not None: vectors = self._spins_as_vectors() return np.asarray(calculate_vorticity_numba(spins=vectors, idx_next=self.idx_next)) return np.array([]) def _get_vortex_density(self) -> float: """Calculate vortex density n_v, the fraction of plaquettes with non-zero winding.""" if self.spins is not None: vectors = self._spins_as_vectors() return float(calculate_vortex_density_numba(spins=vectors, idx_next=self.idx_next)) return 0.0 def _get_helicity_data(self) -> tuple[float, float]: """Calculate sum of cos and sin of angle differences in x-direction.""" if self.spins is not None: vectors = self._spins_as_vectors() cos_sum, sin_sum = get_helicity_data_numba(spins=vectors, idx_next=self.idx_next) return float(cos_sum), float(sin_sum) return 0.0, 0.0 def _get_structure_factor_squared_unshifted(self) -> np.ndarray: """Calculate the unshifted squared magnitude of the Fourier transform.""" if self.spins is not None: vectors = self._spins_as_vectors() sx = vectors[..., 0] sy = vectors[..., 1] Sk_x = np.fft.fft2(sx) Sk_y = np.fft.fft2(sy) return np.asarray(np.abs(Sk_x) ** 2 + np.abs(Sk_y) ** 2) return np.array([])
[docs] def main() -> None: """CLI entry point for Clock simulation example.""" import argparse import logging from utils.system import setup_logging parser = argparse.ArgumentParser(description='Clock Model Quick Example') parser.add_argument('--size', type=int, default=128, help='Lattice size L') parser.add_argument('--temp', type=float, default=0.2, help='Temperature T') parser.add_argument('--q', type=int, default=6, help='Clock states q') parser.add_argument('--steps', type=int, default=500, help='MC steps') parser.add_argument('--seed', type=int, default=None, help='Random seed') parser.add_argument('--parallel', action='store_true', help='Use parallel kernels') parser.add_argument( '--update', type=str, default='checkerboard', choices=['checkerboard', 'random', 'wolff'], help='Update scheme (default: checkerboard)', ) parser.add_argument( '--continuous', action='store_true', help='Continuous planar spins with anisotropy -A cos(q theta) instead of ' 'the discrete model (default: discrete)', ) parser.add_argument( '--aniso', type=float, default=None, help='Anisotropy A of the continuous model (default 1.0); requires --continuous', ) parser.add_argument('--verbose', action='store_true', help='Enable verbose logging') args = parser.parse_args() if args.aniso is not None and not args.continuous: parser.error('--aniso applies only to the continuous model; add --continuous') log_level = logging.DEBUG if args.verbose else logging.INFO logger = setup_logging(level=log_level) sim: ClockSimulation | DiscreteClockSimulation if args.continuous: aniso = 1.0 if args.aniso is None else args.aniso variant = f'continuous, A={aniso}' sim = ClockSimulation( size=args.size, temp=args.temp, q=args.q, A=aniso, seed=args.seed, parallel=args.parallel, update=args.update, ) else: variant = 'discrete' sim = DiscreteClockSimulation( size=args.size, temp=args.temp, q=args.q, seed=args.seed, parallel=args.parallel, update=args.update, ) logger.info( f'Initialized {args.q}-state Clock Model ({variant}, L={args.size}, ' f'T={args.temp}, update={args.update}, parallel={args.parallel})' ) logger.info(f'Running for {args.steps} steps...') mag_history, energy_history = sim.run(n_steps=args.steps) # Plotting fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(18, 5)) fig.suptitle(f'2D {args.q}-state Clock Model - $L={args.size}, T={args.temp}$', fontsize=14) # Final Phase Configuration if sim.spins is not None: field = sim.get_spin_field() angles = np.arctan2(field[..., 1], field[..., 0]) im1 = ax1.imshow(angles, cmap='hsv', interpolation='none', vmin=-np.pi, vmax=np.pi) ax1.set_title('Final Spin Phase') ax1.axis('off') plt.colorbar(im1, ax=ax1, label='Phase (rad)', shrink=0.8) # Magnetization and Energy ax2.plot(mag_history, label='|M|') ax2.plot(energy_history, label='Energy') ax2.set_title('Thermodynamics vs Time') ax2.set_xlabel('Monte Carlo Steps') ax2.set_ylabel('Value') ax2.grid(True, alpha=0.3) ax2.legend() # Vorticity map vort = sim.calculate_vorticity() im2 = ax3.imshow(vort, cmap='bwr', interpolation='none', vmin=-1, vmax=1) ax3.set_title(f'Vorticity (Total: {int(np.sum(np.abs(vort)))})') ax3.axis('off') plt.colorbar(im2, ax=ax3, ticks=[-1, 0, 1], label='Winding No.', shrink=0.8) plt.tight_layout() output_dir = 'results' os.makedirs(output_dir, exist_ok=True) output_file = os.path.join(output_dir, 'clock_example.png') plt.savefig(output_file) logger.info(f'Simulation finished. Plot saved to {output_file}')
if __name__ == '__main__': main()