Spins

Spin realizations shared by the physics packages: Monte Carlo sampling of Ising, Potts, and XY spins.

IsingSamplingInteraction(label, *, target, state='spin', rule='metropolis', schedule='checkerboard', neighborhood=None)

Bases: SpinSamplingInteraction

Monte Carlo sweeps of Ising spins s = ±1 of local energy -J s sum_j s_j - h s, by flips.

The coupling J, the field h, and the temperature are parameters of the spins.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction, unique among the parts of its system.	required
target	Annotated[str, RoleSpec()]	The path of the group of spins.	required
state	str	The name of the state that holds the spin.	'spin'
rule	str	The acceptance, 'metropolis', 'glauber', or 'heat-bath'.	'metropolis'
schedule	str	'checkerboard' on a square lattice, 'colored' on a network, or 'random-sequential'.	'checkerboard'
neighborhood	BaseNeighborhood | None	The neighbours of a spin, or None for the von Neumann neighbourhood. A network takes AdjacencyNeighborhood().	None

Examples:

>>> from types import SimpleNamespace
>>> from sage.all__sagemath_symbolics import var
>>> from skcomplex.models.physics.common.spins import IsingSamplingInteraction
>>> ising = IsingSamplingInteraction('ising', target='spins')
>>> other = SimpleNamespace(spin=var('t'))
>>> ising.energy(SimpleNamespace(target=SimpleNamespace(spin=var('s'), J=1, h=var('h'), other=other)))
-h*s - s*neighbors(t, reduce='sum')

Source code in src/skcomplex/models/physics/common/spins/_ising_sampling.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    state: str = 'spin',
    rule: str = 'metropolis',
    schedule: str = 'checkerboard',
    neighborhood: BaseNeighborhood | None = None,
) -> None:
    super().__init__(
        label,
        target=target,
        state=state,
        energy=self._energy,
        rule=rule,
        schedule=schedule,
        neighborhood=neighborhood,
    )

PottsSamplingInteraction(label, *, target, q=3, state='color', rule='heat-bath', neighborhood=None)

Bases: SpinSamplingInteraction

Monte Carlo sweeps of Potts spins in states 0 to q - 1, of local energy -J times the like neighbours.

Every move proposes a state drawn from the q states. The coupling J and the temperature are parameters of the spins.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction, unique among the parts of its system.	required
target	Annotated[str, RoleSpec()]	The path of the group of spins.	required
q	int	The number of states.	3
state	str	The name of the state that holds the spin.	'color'
rule	str	The acceptance, 'metropolis', 'glauber', or 'heat-bath'.	'heat-bath'
neighborhood	BaseNeighborhood | None	The neighbours of a spin, or None for the von Neumann neighbourhood.	None

Examples:

>>> from skcomplex.models.physics.common.spins import PottsSamplingInteraction
>>> PottsSamplingInteraction('potts', target='spins', q=4).check().values
(0.0, 1.0, 2.0, 3.0)

Source code in src/skcomplex/models/physics/common/spins/_potts_sampling.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    q: int = 3,
    state: str = 'color',
    rule: str = 'heat-bath',
    neighborhood: BaseNeighborhood | None = None,
) -> None:
    super().__init__(
        label,
        target=target,
        state=state,
        energy=self._energy,
        move='random-value',
        rule=rule,
        neighborhood=neighborhood,
        values=tuple(float(value) for value in range(q)),
    )
    self.q = q

SpinSamplingInteraction(label, *, target, state, energy, move='flip', rule='metropolis', schedule='checkerboard', neighborhood=None, values=(), width=1.0)

Bases: ThermalSamplingInteraction

Monte Carlo sweeps of the spins of a lattice or network group at the temperature of the spins.

The temperature is the parameter temperature of the spins, so it lives with the couplings and fields of the spins, and a schedule of <group>.temperature changes it during a run. The local energy reads the states and parameters of the spin as namespace.target.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction, unique among the parts of its system.	required
target	Annotated[str, RoleSpec()]	The path of the group of spins.	required
state	str	The name of the state the moves change.	required
energy	Callable[[SimpleNamespace], object]	The function energy(namespace) of the local energy of a spin.	required
move	str | Callable[..., object]	'flip', 'random-value', 'rotate', 'gaussian', or a function that proposes values.	'flip'
rule	str	The acceptance, 'metropolis', 'glauber', or 'heat-bath'.	'metropolis'
schedule	str	'checkerboard', 'colored', or 'random-sequential'.	'checkerboard'
neighborhood	BaseNeighborhood | None	The neighbourhood the energy reduces over, or None for the von Neumann neighbourhood.	None
values	Sequence[float]	The values a random-value move draws from.	()
width	float	The largest change of a rotation, or the standard deviation of a Gaussian move.	1.0

Examples:

>>> from skcomplex.core.laws.utils import neighbors
>>> from skcomplex.models.physics.common.spins import SpinSamplingInteraction
>>> energy = lambda n: -n.target.spin * neighbors(n.target.other.spin)
>>> SpinSamplingInteraction('ising', target='spins', state='spin', energy=energy).rule
'metropolis'

Source code in src/skcomplex/models/physics/common/spins/_spin_sampling.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    state: str,
    energy: Callable[[SimpleNamespace], object],
    move: str | Callable[..., object] = 'flip',
    rule: str = 'metropolis',
    schedule: str = 'checkerboard',
    neighborhood: BaseNeighborhood | None = None,
    values: Sequence[float] = (),
    width: float = 1.0,
) -> None:
    super().__init__(
        label,
        target=target,
        state=state,
        energy=energy,
        move=move,
        rule=rule,
        schedule=schedule,
        neighborhood=neighborhood,
        values=values,
        width=width,
    )

ThermalSamplingInteraction(label, *, target, state, energy, move='flip', temperature=1.0, rule='metropolis', schedule='checkerboard', neighborhood=None, values=(), width=1.0, cooling=None)

Bases: SamplingInteraction

Monte Carlo sweeps of a state in an energy at a temperature, the intensity one over the temperature.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction, unique among the parts of its system.	required
target	Annotated[str, RoleSpec()]	The path of the group on the sites of a lattice or the nodes of a network.	required
state	str	The name of the state the moves change.	required
energy	Callable[[SimpleNamespace], object]	The function energy(namespace) of the local energy of a member.	required
move	str | Callable[..., object]	'flip', 'random-value', 'rotate', 'gaussian', 'cluster', or a function that proposes values.	'flip'
temperature	Annotated[float, ParameterSpec(domain=open(0, oo))]	The temperature.	1.0
rule	str	The acceptance, 'metropolis', 'glauber', or 'heat-bath', which draws among all values of a discrete move by their Boltzmann weights.	'metropolis'
schedule	str	'checkerboard', 'colored', or 'random-sequential'.	'checkerboard'
neighborhood	BaseNeighborhood | None	The neighbourhood the energy reduces over, or None for the von Neumann neighbourhood.	None
values	Sequence[float]	The values a random-value move draws from.	()
width	float	The largest change of a rotation, or the standard deviation of a Gaussian move.	1.0
cooling	Callable[[Expression], object] | None	The function of the time symbol that multiplies the temperature, or None for a constant temperature.	None

Examples:

>>> from skcomplex.core.laws.utils import neighbors
>>> from skcomplex.models.physics.common.spins import ThermalSamplingInteraction
>>> energy = lambda n: -n.target.s * neighbors(n.target.other.s)
>>> ThermalSamplingInteraction('ising', target='spins', state='s', energy=energy, temperature=2.0).temperature
2.0

Source code in src/skcomplex/models/physics/common/spins/_thermal_sampling.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    state: str,
    energy: Callable[[SimpleNamespace], object],
    move: str | Callable[..., object] = 'flip',
    temperature: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    rule: str = 'metropolis',
    schedule: str = 'checkerboard',
    neighborhood: BaseNeighborhood | None = None,
    values: Sequence[float] = (),
    width: float = 1.0,
    cooling: Callable[[Expression], object] | None = None,
) -> None:
    super().__init__(
        label,
        target=target,
        state=state,
        objective=energy,
        move=move,
        rule=rule,
        schedule=schedule,
        neighborhood=neighborhood,
        values=values,
        width=width,
        cooling=cooling,
    )
    self.energy = energy
    self.temperature = temperature

XYSamplingInteraction(label, *, target, width=1.0, state='theta', neighborhood=None)

Bases: SpinSamplingInteraction

Monte Carlo sweeps of planar spins at angles theta, of local energy -J sum_j cos(theta - theta_j).

Every move rotates the angle by a uniform number in [-width, width], accepted by the Metropolis rule. The coupling J and the temperature are parameters of the spins.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction, unique among the parts of its system.	required
target	Annotated[str, RoleSpec()]	The path of the group of spins.	required
width	float	The largest change of a proposed rotation.	1.0
state	str	The name of the state that holds the angle.	'theta'
neighborhood	BaseNeighborhood | None	The neighbours of a spin, or None for the von Neumann neighbourhood.	None

Examples:

>>> from skcomplex.models.physics.common.spins import XYSamplingInteraction
>>> XYSamplingInteraction('xy', target='spins', width=0.5).move
'rotate'

Source code in src/skcomplex/models/physics/common/spins/_xy_sampling.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    width: float = 1.0,
    state: str = 'theta',
    neighborhood: BaseNeighborhood | None = None,
) -> None:
    super().__init__(
        label,
        target=target,
        state=state,
        energy=self._energy,
        move='rotate',
        neighborhood=neighborhood,
        width=width,
    )