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