SpinToolkit python documentation

Class

class spintoolkit_py.model_spin

Bases: pybind11_builtins.pybind11_object

Spin model which internally stores the magnetic interactions.

__init__(self): Default constructor.

__init__(self, S: float, mode: str, lattice: spintoolkit_py.lattice, verbose: bool = True)

Construct from spin magnitude，mode and lattice.

Parameters:

S – Magnitude of the spins.
mode – Choose from {“dipole”, “SU(N)”, “RPA”}.
lattice – Underlying lattice.
verbose – If true, print detailed info in console. (Default: True)

add_2spin_DM(self: spintoolkit_py.model_spin, *, Dij: spintoolkit_py.Vec3, site_i: int, site_j: int, rtilde_i: list[int], rtilde_j: list[int]) → spintoolkit_py.model_spin

Add Dzyaloshinskii-Moriya (DM) interaction \(\vec{D}_{ij} \cdot (\hat{\boldsymbol{S}}_i \times \hat{\boldsymbol{S}}_j)\) at bond {i, j}.

Parameters:

Dij – Strength of the DM interaction.
site_i – Index of site-i.
site_j – Index of site-j.
rtilde_i – Superlattice coordinate of site-i: \(\tilde{\boldsymbol{r}}_i = \sum_n \tilde{r}_i^n \boldsymbol{A}_n\).
rtilde_j – Superlattice coordinate of site-j: \(\tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_j^n \boldsymbol{A}_n\).

add_2spin_Jmatrix(self: spintoolkit_py.model_spin, *, Jij: spintoolkit_py.Mat3, site_i: int, site_j: int, rtilde_i: list[int], rtilde_j: list[int]) → spintoolkit_py.model_spin

Add general bilinear interaction \(\hat{\boldsymbol{S}}_i \cdot (J_{ij} \hat{\boldsymbol{S}}_j)\) at bond {i, j}.

Parameters:

Jij – General \(3\times 3\) matrix of the exchange interaction.
site_i – Index of site-i.
site_j – Index of site-j.
rtilde_i – Superlattice coordinate of site-i: \(\tilde{\boldsymbol{r}}_i = \sum_n \tilde{r}_i^n \boldsymbol{A}_n\).
rtilde_j – Superlattice coordinate of site-j: \(\tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_j^n \boldsymbol{A}_n\).

add_2spin_XYZ(self: spintoolkit_py.model_spin, *, J: spintoolkit_py.Vec3, site_i: int, site_j: int, rtilde_i: list[int], rtilde_j: list[int]) → spintoolkit_py.model_spin

Add XYZ interaction \(J^x \hat{S}_i^x \hat{S}_j^x + J^y \hat{S}_i^y \hat{S}_j^y + J^z \hat{S}_i^z \hat{S}_j^z\) at bond {i, j}.

Parameters:

J – Strength of the XYZ interaction.
site_i – Index of site-i.
site_j – Index of site-j.
rtilde_i – Superlattice coordinate of site-i: \(\tilde{\boldsymbol{r}}_i = \sum_n \tilde{r}_i^n \boldsymbol{A}_n\).
rtilde_j – Superlattice coordinate of site-j: \(\tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_j^n \boldsymbol{A}_n\).

add_biquadratic(self: spintoolkit_py.model_spin, *, K: SupportsFloat, site_i: int, site_j: int, rtilde_i: list[int], rtilde_j: list[int]) → spintoolkit_py.model_spin

Add biquadratic interaction \(K \left(\hat{\boldsymbol{S}}_i \cdot \hat{\boldsymbol{S}}_j \right)^2\) at bond {i, j}.

Parameters:

K – Strength of the biquadratic interaction.
site_i – Index of site-i.
site_j – Index of site-j.
rtilde_i – Superlattice coordinate of site-i: \(\tilde{\boldsymbol{r}}_i = \sum_n \tilde{r}_i^n \boldsymbol{A}_n\).
rtilde_j – Superlattice coordinate of site-j: \(\tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_j^n \boldsymbol{A}_n\).

add_dipolar(self: spintoolkit_py.model_spin, *, D: SupportsFloat, etaR: SupportsFloat = 1.0, accuracy_goal: int = 3, use_fourier: bool = True) → spintoolkit_py.model_spin

Add dipole-dipole interaction (3D-system only), computed internally with Ewald summation method.

\[\frac{D}{2} R^3 \sum_{i\neq j} \frac{\hat{\boldsymbol{S}}_i \cdot \hat{\boldsymbol{S}}_j -3 (\hat{\boldsymbol{S}}_i \cdot \hat{r}_{ij}) (\hat{\boldsymbol{S}}_j \cdot \hat{r}_{ij})}{r_{ij}^3}.\]

Parameters:

D – Coefficient of the dipole-dipole interaction, which can be calculated by cal_dipolar_D().
etaR – Gaussian broadening factor to separate long- and short-range contributions (R is the length of the shortest bond on the lattice). (Default: 1.0)
accuracy_goal – Relative error = \(10^{-\text{accuracy goal}}\). Must be between 2 and 7. (Default: 3)
use_fourier – If true, evaluate the long-range part of the Ewald sum in fourier space; otherwise in real-space. (Default: True)

add_site_Amatrix(self: spintoolkit_py.model_spin, *, A: spintoolkit_py.Mat3, site: int) → spintoolkit_py.model_spin

Add single-ion anisotropy \(\hat{\boldsymbol{S}}_i \cdot (A \hat{\boldsymbol{S}}_i)\) on site-i.

Parameters:

A – Symmetric \(3\times 3\) matrix of the single-ion anisotropy.
site – Index of site.

add_site_CEF(self: spintoolkit_py.model_spin, *, l: int, m: int, Blm: SupportsFloat, site: int) → spintoolkit_py.model_spin

Add CEF term \(B_l^m (\hat{O}_l^m)_i\) on site-i.

Parameters:

l – Rank of the CEF term (\(2 \le l \le 8\)).
m – Component of the CEF term(\(-l \le m \le l\)).
Blm – Strength of the CEF term.
site – Index of site.

add_site_Dvector(self: spintoolkit_py.model_spin, *, D: spintoolkit_py.Vec3, site: int) → spintoolkit_py.model_spin

Add single-ion anisotropy \(\sum_\mu D^\mu (\hat{S}_i^\mu)^2\) on site-i.

Parameters:

D – Strength of the single-ion anisotropy.
site – Index of site.

add_zeeman(self: spintoolkit_py.model_spin, *, h: spintoolkit_py.Vec3, site: int) → spintoolkit_py.model_spin

Add Zeeman coupling \(-\vec{h} \cdot \hat{\boldsymbol{S}}_i\) on site-i.

Parameters:

h – Strength of the magnetic field (Note: g-tensor is absorbed inside \(\vec{h}\)).
site – Index of site.

build_mc_list(self: spintoolkit_py.model_spin, verbose: bool = True) → spintoolkit_py.model_spin

Build extra internal data structures to improve energy calculation efficiency.

The use of name “mc_list” was for historical reasons: In early versions of the code, only Monte Carlo routines were using these internal data structures. In recent versions, all energy calculations are now requiring these internal data structures to be present. So, build_mc_list must be executed immediately after model simplification.

Parameters:: verbose – If true, print out building details. (Default: True)

cal_dipolar_D(self: spintoolkit_py.model_spin, *, units: spintoolkit_py.units, g: SupportsFloat) → float

Calculate the coefficient of the dipole-dipole interaction using the given unit system.

\[D = \frac{\mu_0}{4\pi} \frac{(g \mu_B)^2}{R^3},\]

where \(R\) is the length of the shortest bond on the lattice.

Parameters:

units – The unit to be used.
g – The g-factor.

Returns:

Coefficient D.

Return type:

float

dim(self: spintoolkit_py.model_spin) → int: Return dimension of the space.

energy_SUN(self: spintoolkit_py.model_spin, *, Z: spintoolkit_py.VecZList) → float

Return energy density \(e=E/L\) in SU(N) mode.

Parameters:: Z – List of SU(N) coherent states in complex numbers: \([\vec{Z}_1, \ldots, \vec{Z}_L]\) (normalization \(|\vec{Z}_i|=1\) required).
Returns:: Energy density \(e=E/L\).
Return type:: float

energy_dipole(self: spintoolkit_py.model_spin, *, s: spintoolkit_py.Vec3List, grad: spintoolkit_py.Vec3List) → float

Return energy density \(e=E/L\) and gradients in dipole mode.

Parameters:

s – List of spin dipoles: \([\vec{s}_1,\ldots,\vec{s}_L]\) (normalization \(|\vec{s}_i| = 1\) required).
grad – Must be of size 0 or L on entry. If of size L, then overwritten by \([\frac{\mathrm{d}e}{\mathrm{d}\vec{s}_1}, \ldots, \frac{\mathrm{d}e}{\mathrm{d}\vec{s}_L}]\) (modified in-place).

Returns:

Energy density \(e=E/L\).

Return type:

float

init_GLSW(self: spintoolkit_py.model_spin, *, Z_min: spintoolkit_py.VecZList) → None

Prepare internal variables for generalized linear spin wave (GLSW) calculations. Should be called before running GLSW calculations.

Parameters:: Z_min – List of SU(N) coherent states in complex numbers of the lowest energy state: \([\vec{Z}_1, \ldots, \vec{Z}_L]\) (normalization \(|\vec{Z}_i|=1\) required).

init_LSW(self: spintoolkit_py.model_spin, *, s_min: spintoolkit_py.Vec3List) → list[spintoolkit_py.Mat3_rotation]

Prepare internal variables for linear spin wave (LSW) calculations. Should be called before running LSW calculations.

Parameters:: s_min – List of spin dipoles of the lowest energy state: \([\vec{s}_1,\ldots,\vec{s}_L]\) (normalization \(|\vec{s}_i| = 1\) required).
Returns:: List of rotation matrices that satisfy \(\vec{s}_i = R_i \hat{z}\).
Return type:: list[Mat3_rotation]

optimize_spins_SUN(self: spintoolkit_py.model_spin, total_seeds: int, seed0: int = 0, algorithm: int = 1, maxeval: int = 10000, verbose: bool = False) → tuple[spintoolkit_py.VecZList, float]

Optimize the ground state spin configurations in SU(N) mode.

Parameters:

total_seeds – Total number of random initial spin configurations tried in optimization (the more seeds, the more likely to hit global minimum).
seed0 – Seed of the first random initial spin configuration. All seeds used: [seed0, seed0+1, …, seed0+total_seeds-1]. (default to 0).
algorithm – Algorithm used in optimization. If chosen in [1:8], a particular algorithm shall be used; If >=10, algorithms 1~5 will be rotated. (default to 1).
maxeval – Maximal evaluations allowed for each optimization at a given seed. (default to 10000).
verbose – If true, print out optimization details in console. (default to False).

Returns:

Z_min (list[list[complex]]) – List of SU(N) coherent states in complex numbers of the lowest energy state: \([\vec{Z}_1, \ldots, \vec{Z}_L]\) (normalization \(|\vec{Z}_i|=1\) fulfilled).
e_min (float) – Lowest energy density \(e_\text{(min)} \equiv E_\text{(min)}/L\) found.

optimize_spins_dipole(self: spintoolkit_py.model_spin, total_seeds: int, seed0: int = 0, algorithm: int = 1, maxeval: int = 10000, verbose: bool = False) → tuple[spintoolkit_py.Vec3List, float]

Optimize the ground state spin configuration in dipole mode.

Parameters:

total_seeds – Total number of random initial spin configurations tried in optimization (the more seeds, the more likely to hit global minimum).
seed0 – Seed of the first random initial spin configuration. All seeds used: [seed0, seed0+1, …, seed0+total_seeds-1]. (default to 0).
algorithm – Algorithm used in optimization. If chosen in [1:8], a particular algorithm shall be used; If >=10, algorithms 1~5 will be rotated. (default to 1).
maxeval – Maximal evaluations allowed for each optimization at a given seed. (default to 10000).
verbose – If true, print out optimization details in console. (default to False).

Returns:

s_min (list[~spintoolkit_py.Vec3]) – List of spin dipoles of the lowest energy state: \([\vec{s}_1,\ldots,\vec{s}_L]\) (normalization \(|\vec{s}_i| = 1\) fulfilled).
e_min (float) – Lowest energy density \(e_\text{(min)} \equiv E_\text{(min)}/L\) found.

prt(self: spintoolkit_py.model_spin) → None: Print model information (list of interactions).

prt_mc_list(self: spintoolkit_py.model_spin) → None: Print model information (list of interactions structured for MC).

simplify(self: spintoolkit_py.model_spin, verbose: bool = True) → spintoolkit_py.model_spin

Clean up the internal data structure (merging identical bonds, removing zeros, etc.).

Parameters:: verbose – If true, print out simplification details. (Default: True)

total_sites(self: spintoolkit_py.model_spin) → int: Return total number of lattice sites (L) in the magnetic unit cell.

property E_shift: Constant shift of the Hamiltonian after model simplification.

property S: Magnitude of the spins.

property mode: Mode used for the computation (dipole, SUN, RPA)

Functions

spintoolkit_py.spin_cart2spherical(*, s: list[float]) → tuple[float, float]

Convert spin dipole from Cartesian representation to spherical angles.

\[\begin{split}\begin{pmatrix} s^x \\ s^y \\ s^z \end{pmatrix} = r \begin{pmatrix} \sin \theta \cos \phi \\ \sin \theta \sin \phi \\ \cos \theta \end{pmatrix}.\end{split}\]

Parameters:

s – \([s^x, s^y, s^z]\).

Returns:

theta (float) - Polar angle.
phi (float) - Azimuthal angle.

spintoolkit_py.spin_cart2spherical(*, Z: list[complex]) → list[float]

Convert SU(N) coherent state from complex numbers to Euler angles.

\[\begin{split}\begin{pmatrix} Z^0 \\ Z^1 \\ \vdots \\ Z^{N-1} \end{pmatrix} = e^{i \phi^0} \begin{pmatrix} e^{i \phi^{N-1}}\sin\theta^{1}\sin\theta^{2} \cdots\sin\theta^{N-2}\sin\theta^{N-1}\\ e^{i \phi^{N-2}}\sin\theta^{1}\sin\theta^{2} \cdots\sin\theta^{N-2}\cos\theta^{N-1}\\ \vdots\\ e^{i \phi^{2}}\sin\theta^{1}\sin\theta^{2}\cos\theta^{3}\\ e^{i \phi^{1}}\sin\theta^{1}\cos\theta^{2}\\ \cos\theta^{1} \end{pmatrix}.\end{split}\]

Parameters:: Z – Length-N list of SU(N) coherent state in complex numbers: \([Z^0,Z^1,\ldots,Z^{N-1}]\) (normalization \(|\vec{Z}|=1\) required).
Return type:: list[float]
Returns:: Length-(2N-2) list of SU(N) coherent state in Euler angles: \([\theta^1,\theta^2,\ldots,\theta^{N-1},\phi^1,\phi^2,\ldots,\phi^{N-1}]\).

spintoolkit_py.spin_spherical2cart(*, theta: float, phi: float) → list[float]

Convert spin dipole from spherical angles to Cartesian representation.

\[\begin{split}\begin{pmatrix} s^x \\ s^y \\ s^z \end{pmatrix} = \begin{pmatrix} \sin \theta \cos \phi \\ \sin \theta \sin \phi \\ \cos \theta \end{pmatrix}.\end{split}\]

Parameters:

theta – Polar angle.
phi – Azimuthal angle.

Return type:

list[float]

Returns:

\([s^x, s^y, s^z]\).

spintoolkit_py.spin_spherical2cart(*, theta_phi: list[float]) → list[complex]

Convert SU(N) coherent state from Euler angles to complex numbers.

\[\begin{split}\begin{pmatrix} Z^0 \\ Z^1 \\ \vdots \\ Z^{N-1} \end{pmatrix} = \begin{pmatrix} e^{i \phi^{N-1}}\sin\theta^{1}\sin\theta^{2} \cdots\sin\theta^{N-2}\sin\theta^{N-1}\\ e^{i \phi^{N-2}}\sin\theta^{1}\sin\theta^{2} \cdots\sin\theta^{N-2}\cos\theta^{N-1}\\ \vdots\\ e^{i \phi^{2}}\sin\theta^{1}\sin\theta^{2}\cos\theta^{3}\\ e^{i \phi^{1}}\sin\theta^{1}\cos\theta^{2}\\ \cos\theta^{1} \end{pmatrix}.\end{split}\]

Parameters:: theta_phi – Length-(2N-2) list of SU(N) coherent state in Euler angles: \([\theta^1,\theta^2,\ldots,\theta^{N-1},\phi^1,\phi^2,\ldots,\phi^{N-1}]\).
Return type:: list[complex]
Returns:: Length-N list of SU(N) coherent state in complex numbers: \([Z^0,Z^1,\ldots,Z^{N-1}]\).

spintoolkit_py.set_Ising_random(*, seed: int, s: spintoolkit_py.Vec3List) → None

Randomly flip a list of spin dipoles along input Ising axes.

Parameters:

seed – Random seed.
s – List of spin dipoles in Cartesian representation: \([\vec{s}_1, \ldots, \vec{s}_L]\) (normalization \(|\vec{s}_i| = 1\) required and fulfilled) (modified in-place).

spintoolkit_py.set_dipole_random(*, seed: int, s: spintoolkit_py.Vec3List) → None

Randomize a list of spin dipoles on the \(S^2\) sphere uniformly, using “dipole” mode.

Parameters:

seed – Random seed.
s – List of spin dipoles in Cartesian representation: \([\vec{s}_1, \ldots, \vec{s}_L]\) (normalization \(|\vec{s}_i| = 1\) fulfilled) (modified in-place).

spintoolkit_py.set_SUN_random(*, seed: int, Z: spintoolkit_py.VecZList, N: int) → None

Randomize a list of SU(N) coherent states on the \(S^{2N-2}\) sphere uniformly. In addition, the global phase is fixed such that \(Z_i^{N-1}\) is real.

Parameters:

seed – Random seed.
Z – List of SU(N) coherent states in complex numbers: \([\vec{Z}_1, \ldots, \vec{Z}_L]\) (normalization \(|\vec{Z}_i|=1\) fulfilled) (modified in-place).
N – Dimension N in SU(N).

spintoolkit_py.set_RPA_random(*, seed: int, s: spintoolkit_py.Vec3List, S: SupportsFloat) → None

Randomize a list of spin dipoles in a ball of radius S. For each spin, the angles are uniformly sampled on the \(S^2\) sphere, and the magnitude is uniformly sampled in [0, S).

Parameters:

seed – Random seed.
s – List of spin dipoles in Cartesian representation: \([\vec{s}_1, \ldots, \vec{s}_L]\) (modified in-place).
S – Magnitude of the spins.

spintoolkit_py.spins_magnetization(*, s: list[spintoolkit_py.Vec3], S: float) → tuple[float, float, float]

Compute average magnetization of spin dipoles.

Parameters:

s – List of spin dipoles (normalization \(|\vec{s}_i|=1\) required).
S – Magnitude of the spins.

Returns:

mx (float) - Average magnetization along x-direction.
my (float) - Average magnetization along y-direction.
mz (float) - Average magnetization along z-direction.

spintoolkit_py.spins_magnetization(*, Z: list[list[complex]]) → tuple[float, float, float]

Compute average magnetization of SU(N) coherent states.

Parameters:

Z – List of SU(N) coherent states (normalization \(|\vec{Z}_i|=1\) required).

Returns:

mx (float) - Average magnetization along x-direction.
my (float) - Average magnetization along y-direction.
mz (float) - Average magnetization along z-direction.