SpinToolkit python documentation

Class

class spintoolkit_py.lattice

Bases: pybind11_builtins.pybind11_object

Finite lattice for large scale simulations, or magnetic unit cell for spin wave calculations.

__init__(self): Default constructor.

__init__(self, *, basis_a: list[list[float]], pos_sub: list[list[float]], l: list[int])

Construct an untilted lattice (\(\boldsymbol{A}_j \parallel \boldsymbol{a}_j\)) from a given basis.

Parameters:

basis_a – Real-space basis vectors \([\boldsymbol{a}_0, \boldsymbol{a}_1, \ldots]\).
pos_sub – List of sublattice coordinates in units of the basis \(\boldsymbol{a}_j\).
l – List of linear dimensions along each basis direction.

__init__(self, *, name: str, l: list[int])

Construct an untilted lattice (\(\boldsymbol{A}_j \parallel \boldsymbol{a}_j\)) from a built-in name.

Parameters:

name – Name of the lattice. Choose from [chain, square, triangular, kagome, honeycomb, cubic, fcc, triangular-stacked, pyrochlore, pyrochlore-16, pyrochlore-111].
l – List of linear dimensions along each basis direction.

__init__(self, *, filename: str)

Construct a general lattice from a user-defined TOML file.

Parameters:: filename – Name of the toml file.

Notes

The TOML file must specify the lattice geometry and sublattice structure with the following fields:

dim : Spatial dimension (1, 2, or 3).
a0, a1, a2 : Basis vectors \(\boldsymbol{a}_j\) as floating-point arrays.
A0, A1, A2 : Superlattice basis vectors \(\boldsymbol{A}_j\) expressed as integer coefficients of the crystal basis.
num_sub : Number of sublattices.
pos_sub0, pos_sub1, … : Sublattice coordinates in units of the basis \(\boldsymbol{a}_j\).
[[sub0]], [[sub1]], … : Arrays of sublattice sites, where each entry contains a site field with integer coordinates specifying the position within the superlattice.

The superlattice basis vectors \(\boldsymbol{A}_j\) are not required to be parallel to the crystal basis vectors \(\boldsymbol{a}_j\), allowing for flexible magnetic unit cell definitions compatible with various ordering wave vectors.

Example

Triangular lattice with 120° ordering (K-point):

dim = 2

a0 = [ 1.0, 0.0 ]
a1 = [ -0.5, 0.86602540378443865 ]

A0 = [ 2, 1 ]
A1 = [ 1, 2 ]

num_sub = 1
pos_sub0 = [ 0.0, 0.0 ]

[[sub0]]
site = [ 0, 0 ]
[[sub0]]
site = [ 1, 0 ]
[[sub0]]
site = [ 1, 1 ]

coor2cart(self, *, coor: list[int]) → list[float]

Calculate Cartesian coordinate \([x,y,z]= \sum_i m_i \boldsymbol{a}_i\) with given coordinate \(m_i\).

Parameters:: coor – Coordinate \([m_0, m_1, \ldots]\).
Return type:: list[float]
Returns:: Cartesian coordinate \([x,y,z]\).

coor2cart(self, *, coor: list[int], sub: int) → list[float]

Calculate Cartesian coordinates \([x,y,z]= \sum_i m_i \boldsymbol{a}_i + \vec{d}\) with given coordinate \(m_i\) and sublattice index (\(\vec{d}\) accounts for the displacement of the sublattice).

Parameters:

coor – Coordinate \([m_0, m_1, \ldots]\).
sub – Index of sublattice.

Return type:

list[float]

Returns:

Cartesian coordinate \([x,y,z]\).

bond_length_min(self: spintoolkit_py.lattice) → float: Returns the length of the shortest bond.

coor2site(self: spintoolkit_py.lattice, *, coor: list[int], sub: int) → int

Calculate site index with given coordinate \(m_i\) and sublattice index.

Parameters:

coor – Coordinate \([m_0, m_1, \ldots]\) of site.
sub – Index of sublattice.

Returns:

Index of site.

Return type:

int

k2superlattice(self: spintoolkit_py.lattice, *, k: list[float]) → tuple[list[int], list[float]]

Decompose a k-vector onto the superlattice.

\[\boldsymbol{k} = \boldsymbol{K} + \tilde{\boldsymbol{k}},\]

where

\[\boldsymbol{k}=\sum_i k_i \boldsymbol{b}_i,\]

\[\boldsymbol{K} = \sum_i K_i \boldsymbol{B}_i,\quad K_i \in \text{Integers}\]

and

\[\tilde{\boldsymbol{k}} = \sum_i \tilde{k}_i \boldsymbol{B}_i, \quad \tilde{k}_i \in [0,\,1).\]

Parameters:

k – Coordinate \([k_0, k_1, \ldots ]\).

Returns:

K (list[int]) – Coordinate \([K_0, K_1, \ldots ]\).
ktilde (list[float]) – Coordinate \([\tilde{k}_0, \tilde{k}_1, \ldots ]\).

l0(self: spintoolkit_py.lattice) → int

Linear size along \(\boldsymbol{a}_0\) direction for untilted lattice.

Returns:: Linear size l0.
Return type:: int

l1(self: spintoolkit_py.lattice) → int

Linear size along \(\boldsymbol{a}_1\) direction for untilted lattice.

Returns:: Linear size l1.
Return type:: int

l2(self: spintoolkit_py.lattice) → int

Linear size along \(\boldsymbol{a}_2\) direction for untilted lattice.

Returns:: Linear size l2.
Return type:: int

polarization_matrix(self: spintoolkit_py.lattice, *, k: list[float]) → spintoolkit_py.Mat3

Return the polarization matrix \((\delta^{\mu \nu} - \hat{k}^\mu \hat{k}^\nu)\), where \(\mu, \nu = \{x, y, z\}\) (only support dim=3 at the moment).

Parameters:: k – Momentum in units of the basis \(\boldsymbol{b}_j\): \(\boldsymbol{k} = \sum_j k_j \boldsymbol{b}_j\).

q_tilted(self: spintoolkit_py.lattice) → bool

Return true if any direction tilted.

Returns:: True if the superlattice basis \(A\) is not a diagonal matrix.
Return type:: bool

r2superlattice(self: spintoolkit_py.lattice, *, coor: list[int]) → tuple[list[int], list[int]]

Decompose a real-space coordinate onto the superlattice.

Given coordinate \((m_0, m_1, ...)\), decompose as

\[\sum_i m_i \boldsymbol{a}_i = \tilde{\boldsymbol{r}} + \sum_i m_i^0 \boldsymbol{a}_i,\]

where

\[\tilde{\boldsymbol{r}} \equiv \sum_i \tilde{r}_i \boldsymbol{A}_i,\quad \tilde{r}_i \in \text{Integers}\]

and \(m_i^0\) is located in the 1st supercell.

Parameters:

coor – Coordinate \([m_0, m_1, \ldots]\).

Returns:

coor0 (list[int]) – Coordinate \([m_0^0, m_1^0, \ldots]\).
rtilde (list[int]) – Superlattice index \([\tilde{r}_0, \tilde{r}_1, \ldots]\).

site2coor(self: spintoolkit_py.lattice, *, site: int) → tuple[list[int], int]

Calculate coordinate \(m_i\) and sublattice index with given site index.

Parameters:

site – Index of site.

Returns:

coor (list[int]) – Coordinate \([m_0, m_1, \ldots]\) of site.
sub (int) – Index of sublattice.

total_sites(self: spintoolkit_py.lattice) → int

Total number of lattice sites (L) in the magnetic unit cell.

Returns:: Total number of lattice sites (L) in the magnetic unit cell.
Return type:: int

property basis_A: Superlattice basis in matrix format (column \(j \rightarrow \boldsymbol{A}_j\)) in units of \(\boldsymbol{a}_j\).

property basis_B: Reciprocal superlattice basis in matrix format (column \(j \rightarrow \boldsymbol{B}_j\)) in units of \(\boldsymbol{b}_j\).

property basis_a: Real space basis in matrix format (column \(j \rightarrow \boldsymbol{a}_j\)).

property basis_b: Reciprocal space basis in matrix format (column \(j \rightarrow \boldsymbol{b}_j\)).

property dim: Dimension of the lattice.

property num_sub: Number of sublattices.

property pos_sub: Sublattice coordinates in units of \(\boldsymbol{a}_j\).