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]\).

all_bonds_on_lattice(self, *, min_len: float, max_len: float, tol_rel: float) → list[tuple[float, list[tuple[list[int], list[int]]]]]

Generate a list of bonds with length in range [min_len, max_len] on the lattice.

Each element in the list is <len, bond_list> for a list of bonds of the same length.

Each element in bond_list is <[site_i, site_j], \(\tilde{\boldsymbol{r}}_{ij}\)>.

\(\tilde{\boldsymbol{r}}_{ij}\) is the difference of superlattice coordinates:

\[\tilde{\boldsymbol{r}}_i - \tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_{ij}^n \boldsymbol{A}_n.\]

Parameters:

• min_len – Minimal bond length to be considered.

• max_len – Maximal bond length to be considered.

• tol_rel – Tolerance for checking distance.

Return type:

list[tuple[float, list[tuple[list[int], list[int]]]]]

Returns:

list[<len, list[<[site_i, site_j], \(\tilde{\boldsymbol{r}}_{ij}\)>]>].

all_bonds_on_lattice(self, *, n_neighbors: int, tol_rel: float) → list[tuple[float, list[tuple[list[int], list[int]]]]]

Generate a list of bonds up to a certain number of neighbors on the lattice.

Each element in the list is <len, bond_list> for a list of bonds of the same length.

Each element in bond_list is <[site_i, site_j], \(\tilde{\boldsymbol{r}}_{ij}\)>.

\(\tilde{\boldsymbol{r}}_{ij}\) is the difference of superlattice coordinates:

\[\tilde{\boldsymbol{r}}_i - \tilde{\boldsymbol{r}}_j = \sum_n \tilde{r}_{ij}^n \boldsymbol{A}_n.\]

Parameters:

• n_neighbors – Number of coordination shells (number of neighbors) to extract.

• tol_rel – Tolerance for checking distance.

Return type:

list[tuple[float, list[tuple[list[int], list[int]]]]]

Returns:

list[<len, list[<[site_i, site_j], \(\tilde{\boldsymbol{r}}_{ij}\)>]>].

all_bonds_for_site(self: spintoolkit_py.lattice, *, sub: int, min_len: SupportsFloat | SupportsIndex, max_len: SupportsFloat | SupportsIndex, tol_rel: SupportsFloat | SupportsIndex) → list[tuple[float, tuple[int, list[int]]]]

Return a list of <len, <sub’, \(m_0^\prime\), \(m_1^\prime\), …]>> that start from a given sublattice, where the starting sublattice (sub) is at the 0th unit cell, and the target sublattice (sub’) is at \(\sum_i m_i^\prime \boldsymbol{a}_i\).

Parameters:

• sub – Sublattice index of the starting site.

• min_len – Minimal bond length to be considered.

• max_len – Maximal bond length to be considered.

• tol_rel – Tolerance for checking distance.

Returns:

list of <len, <sub’, \(m_0^\prime\), \(m_1^\prime\), …]>>.

Return type:

list[tuple[float, tuple[int, list[int]]]]

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\).