vibespin.models package

Submodules

models.clock_model module

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.

class models.clock_model.ClockSimulation(*, 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)[source]

Bases: VectorSpinObservablesMixin, MonteCarloSimulation

Simulation of the 2D q-state clock model on a square lattice.

step() → None[source]

Perform one Monte Carlo step using Numba.

class models.clock_model.DiscreteClockSimulation(*, 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)[source]

Bases: 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.

get_spin_field() → ndarray[source]

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:

Unit-vector field of shape (L, L, 2).

Return type:

np.ndarray

Raises:

RuntimeError – If the lattice has not been initialised.

step() → None[source]

Perform one Monte Carlo sweep using Numba.

models.clock_model.clock_energy_numba(*, spins: ndarray, J: float, A: float, q: int, idx_next: ndarray) → float[source]

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 – Total energy per site.

Return type:

float

models.clock_model.clock_step_numba(*, spins: ndarray, beta: float, J: float, A: float, q: int, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.clock_step_parallel_numba(*, spins: ndarray, beta: float, J: float, A: float, q: int, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.clock_step_random_numba(*, spins: ndarray, beta: float, J: float, A: float, q: int, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.discrete_clock_energy_numba(*, spins: ndarray, J: float, q: int, cos_table: ndarray, idx_next: ndarray) → float[source]

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:

Energy per site.

Return type:

float

models.clock_model.discrete_clock_step_numba(*, spins: ndarray, beta: float, J: float, q: int, cos_table: ndarray, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.discrete_clock_step_parallel_numba(*, spins: ndarray, beta: float, J: float, q: int, cos_table: ndarray, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.discrete_clock_step_random_numba(*, spins: ndarray, beta: float, J: float, q: int, cos_table: ndarray, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

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:

Updated spins array.

Return type:

np.ndarray

models.clock_model.discrete_clock_wolff_step_numba(*, spins: ndarray, beta: float, J: float, q: int, sigma_table: ndarray, idx_next: ndarray, idx_prev: ndarray, in_cluster: ndarray, stack: ndarray, cluster_spins: ndarray) → tuple[source]

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.

models.clock_model.main() → None[source]

CLI entry point for Clock simulation example.

models.ising_model module

2D Ising Model simulation using Metropolis-Hastings and Wolff cluster algorithms.

class models.ising_model.IsingSimulation(*, size: int, temp: float, J: float = 1.0, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None)[source]

Bases: MonteCarloSimulation

Simulation of the 2D Ising model on a square lattice.

step() → None[source]

Perform one Monte Carlo sweep using the configured update scheme.

models.ising_model.ising_energy_numba(*, spins: ndarray, J: float, idx_next: ndarray) → float[source]

Calculate the total energy of the Ising lattice.

Parameters:
  • spins (np.ndarray) – (N, N) array of spins.

  • J (float) – Coupling constant.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

Returns:

energy – Total energy per site.

Return type:

float

models.ising_model.ising_step_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Perform one full Monte Carlo sweep of the Ising lattice. Uses a checkerboard update pattern for better Numba optimization.

Parameters:
  • spins (np.ndarray) – (N, N) array of spins (+1 or -1).

  • beta (float) – Inverse temperature 1/kT.

  • J (float) – Coupling constant.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

models.ising_model.ising_step_parallel_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Parallel version of ising_step_numba using numba.prange.

Parameters:
  • spins (np.ndarray) – (N, N) array of spins (+1 or -1).

  • beta (float) – Inverse temperature 1/kT.

  • J (float) – Coupling constant.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

models.ising_model.ising_step_random_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Perform one full Monte Carlo sweep of the Ising lattice using random sequential updates (N^2 randomly chosen single-spin flip attempts).

Unlike the checkerboard sweep, sites are chosen uniformly at random with replacement, giving a more physical stochastic dynamics with no spatial bias. This is the standard Metropolis single-spin flip algorithm.

Boltzmann factors for the two possible positive energy changes (4J, 8J) are pre-calculated outside the inner loop to avoid repeated calls to np.exp, matching the optimisation used in ising_step_numba.

Parameters:
  • spins (np.ndarray) – (N, N) array of spins (+1 or -1).

  • beta (float) – Inverse temperature 1/kT.

  • J (float) – Coupling constant.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

models.ising_model.ising_wolff_step_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray, in_cluster: ndarray, stack: ndarray, cluster_spins: ndarray) → tuple[source]

Perform one Wolff cluster flip on the Ising lattice.

A single cluster is grown by probabilistic DFS from a random seed site and then flipped in a single collective move. The bond acceptance probability P_add = 1 - exp(-2 beta J) is derived from the Fortuin-Kasteleyn representation and guarantees detailed balance without rejections.

One call constitutes one cluster sweep. The effective number of site updates per call scales as the mean cluster size <C> and diverges at T_c, which is precisely where Metropolis suffers maximum critical slowing down. parallel=True is silently ignored: cluster growth is inherently sequential.

Parameters:
  • spins (np.ndarray) – (N, N) array of spins (+1 or -1).

  • 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 flipped in this step.

models.ising_model.main() → None[source]

CLI entry point for Ising simulation example.

models.simulation_base module

Base classes and shared Numba-accelerated kernels for Monte Carlo simulations.

class models.simulation_base.MonteCarloSimulation(*, size: int, temp: float, init_state: str = 'random', seed: int | None = None)[source]

Bases: ABC

Abstract base class for 2D lattice Monte Carlo simulations. Provides infrastructure for equilibration, measurement runs, and statistical analysis.

calculate_correlation_function() → tuple[ndarray, ndarray][source]

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.

equilibrate(*, n_steps: int) → None[source]

Perform equilibration steps without recording measurements.

Parameters:

n_steps (int) – Number of MC steps to perform.

get_energy() → float[source]

Return the current energy per site.

Public accessor for scripts and analysis helpers; delegates to the model-specific implementation.

Returns:

Energy per site.

Return type:

float

get_magnetization() → float[source]

Return the current absolute magnetization per site.

Public accessor for scripts and analysis helpers; delegates to the model-specific implementation.

Returns:

Absolute magnetization per site.

Return type:

float

get_spin_field() → ndarray[source]

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:

Spin field suitable for structure-factor and correlation analysis.

Return type:

np.ndarray

Raises:

RuntimeError – If the lattice has not been initialised.

run(*, n_steps: int) → tuple[ndarray, ndarray][source]

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.

run_with_cluster_sizes(*, n_steps: int) → tuple[ndarray, ndarray, ndarray][source]

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.

abstractmethod step() → None[source]

Perform one full Monte Carlo sweep of the lattice.

class models.simulation_base.VectorSpinObservablesMixin[source]

Bases: object

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.

calculate_vorticity() → ndarray[source]

Calculate the vorticity (winding number) of each plaquette.

Returns:

(N, N) array of winding numbers (+1, -1, or 0).

Return type:

np.ndarray

get_helicity_data() → tuple[float, float][source]

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.

get_vortex_density() → float[source]

Calculate the vortex density n_v.

Returns:

Fraction of plaquettes with non-zero winding, in [0, 1].

Return type:

float

models.simulation_base.calculate_vortex_density_numba(*, spins: ndarray, idx_next: ndarray) → float[source]

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:

Vortex density n_v in [0, 1].

Return type:

float

models.simulation_base.calculate_vorticity_numba(*, spins: ndarray, idx_next: ndarray) → ndarray[source]

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 – (N, N) array containing winding numbers (+1, -1, or 0).

Return type:

np.ndarray

models.simulation_base.get_helicity_data_numba(*, spins: ndarray, idx_next: ndarray) → tuple[float, float][source]

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.

models.simulation_base.o2_wolff_step_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray, in_cluster: ndarray, stack: ndarray, cluster_spins: ndarray) → tuple[source]

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.

models.xy_model module

2D XY Model simulation using Metropolis-Hastings and Wolff cluster algorithms.

class models.xy_model.XYSimulation(*, size: int, temp: float, J: float = 1.0, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None)[source]

Bases: VectorSpinObservablesMixin, MonteCarloSimulation

Simulation of the 2D XY model on a square lattice.

step() → None[source]

Perform one Monte Carlo step using Numba.

models.xy_model.main() → None[source]

CLI entry point for XY simulation example.

models.xy_model.xy_energy_numba(*, spins: ndarray, J: float, idx_next: ndarray) → float[source]

Calculate the total energy of the XY lattice.

Parameters:
  • spins (np.ndarray) – (N, N, 2) array of unit vectors.

  • J (float) – Coupling constant.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

Returns:

energy – Total energy per site.

Return type:

float

models.xy_model.xy_step_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Perform one full Monte Carlo sweep of the XY 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.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

models.xy_model.xy_step_parallel_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Parallel version of xy_step_numba.

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.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

models.xy_model.xy_step_random_numba(*, spins: ndarray, beta: float, J: float, idx_next: ndarray, idx_prev: ndarray) → ndarray[source]

Perform one full Monte Carlo sweep of the XY 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.

  • idx_next (np.ndarray) – Pre-calculated next-neighbor indices.

  • idx_prev (np.ndarray) – Pre-calculated previous-neighbor indices.

Returns:

Updated spins array.

Return type:

np.ndarray

Module contents

Public API for VibeSpin simulation models.

class models.ClockSimulation(*, 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)[source]

Bases: VectorSpinObservablesMixin, MonteCarloSimulation

Simulation of the 2D q-state clock model on a square lattice.

step() → None[source]

Perform one Monte Carlo step using Numba.

class models.DiscreteClockSimulation(*, 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)[source]

Bases: 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.

get_spin_field() → ndarray[source]

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:

Unit-vector field of shape (L, L, 2).

Return type:

np.ndarray

Raises:

RuntimeError – If the lattice has not been initialised.

step() → None[source]

Perform one Monte Carlo sweep using Numba.

class models.IsingSimulation(*, size: int, temp: float, J: float = 1.0, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None)[source]

Bases: MonteCarloSimulation

Simulation of the 2D Ising model on a square lattice.

step() → None[source]

Perform one Monte Carlo sweep using the configured update scheme.

class models.MonteCarloSimulation(*, size: int, temp: float, init_state: str = 'random', seed: int | None = None)[source]

Bases: ABC

Abstract base class for 2D lattice Monte Carlo simulations. Provides infrastructure for equilibration, measurement runs, and statistical analysis.

calculate_correlation_function() → tuple[ndarray, ndarray][source]

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.

equilibrate(*, n_steps: int) → None[source]

Perform equilibration steps without recording measurements.

Parameters:

n_steps (int) – Number of MC steps to perform.

get_energy() → float[source]

Return the current energy per site.

Public accessor for scripts and analysis helpers; delegates to the model-specific implementation.

Returns:

Energy per site.

Return type:

float

get_magnetization() → float[source]

Return the current absolute magnetization per site.

Public accessor for scripts and analysis helpers; delegates to the model-specific implementation.

Returns:

Absolute magnetization per site.

Return type:

float

get_spin_field() → ndarray[source]

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:

Spin field suitable for structure-factor and correlation analysis.

Return type:

np.ndarray

Raises:

RuntimeError – If the lattice has not been initialised.

run(*, n_steps: int) → tuple[ndarray, ndarray][source]

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.

run_with_cluster_sizes(*, n_steps: int) → tuple[ndarray, ndarray, ndarray][source]

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.

abstractmethod step() → None[source]

Perform one full Monte Carlo sweep of the lattice.

class models.XYSimulation(*, size: int, temp: float, J: float = 1.0, update: str = 'checkerboard', init_state: str = 'random', parallel: bool = False, seed: int | None = None)[source]

Bases: VectorSpinObservablesMixin, MonteCarloSimulation

Simulation of the 2D XY model on a square lattice.

step() → None[source]

Perform one Monte Carlo step using Numba.