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,MonteCarloSimulationSimulation of the 2D q-state clock model on a square lattice.
- 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,MonteCarloSimulationSimulation 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.
- 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 angletheta_s = 2 pi s / qaboutphi_mgives2 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 states'is reachable fromswith a single-site cluster, the chain is ergodic.Bonds follow the Wolff-Evertz rule: with
sigma_ithe component of spiniperpendicular to the mirror axis, a bond to a neighbour is activated with probability1 - exp(-2 beta J sigma_i sigma_j)whensigma_i sigma_j > 0and 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 underk -> 2q - k. The perpendicular projection of statesfor mirror axismissigma_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.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:
MonteCarloSimulationSimulation of the 2D Ising model on a square lattice.
- 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 inising_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=Trueis 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.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:
ABCAbstract 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.
- class models.simulation_base.VectorSpinObservablesMixin[source]
Bases:
objectPublic topological-observable accessors for vector-spin models.
Mixed into
XYSimulation,ClockSimulation, andDiscreteClockSimulation, 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
- 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
ClockSimulationrejects this update when combined with a non-zero anisotropy.One call constitutes one cluster sweep.
parallel=Trueis 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,MonteCarloSimulationSimulation of the 2D XY model on a square lattice.
- 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,MonteCarloSimulationSimulation 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,MonteCarloSimulationSimulation 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:
MonteCarloSimulationSimulation 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:
ABCAbstract 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,MonteCarloSimulationSimulation of the 2D XY model on a square lattice.
- step() None[source]
Perform one Monte Carlo step using Numba.