SpinToolkit python documentation

Classes

class spintoolkit_py.BondRaw

Bases: pybind11_builtins.pybind11_object

Bond expressed as two fractional coordinates.

__init__(self)

Default constructor.

__init__(self, *, ri: list[float], rj: list[float])

Construct with two site positions.

Parameters:

• ri – Coordinate of site-i in units of the basis \(\boldsymbol{a}_j\).

• rj – Coordinate of site-j in units of the basis \(\boldsymbol{a}_j\).

__init__(self, *, crystal: spintoolkit_py.Crystal, bond: spintoolkit_py.Bond)

Construct from a bond on crystal.

Parameters:

• crystal – Crystal object.

• bond – Bond object.

reverse(self: spintoolkit_py.BondRaw) → spintoolkit_py.BondRaw

Return a copy of bond with two sites reversed.

property ri

Coordinate of site-i in units of the basis \(\boldsymbol{a}_j\).

property rj

Coordinate of site-j in units of the basis \(\boldsymbol{a}_j\).

class spintoolkit_py.Bond

Bases: pybind11_builtins.pybind11_object

Bond expressed as site indices and integer displacement of unit cells.

__init__(self)

Default constructor.

__init__(self, *, i: int, j: int, G: list[int])

Construct from site indices and displacement of unit cells.

Parameters:

• i – Index of site-i.

• j – Index of site-j.

• G – Integer displacement of unit cells.

__init__(self, *, crystal: spintoolkit_py.Crystal, bond_raw: spintoolkit_py.BondRaw)

Construct from a raw bond on crystal.

Parameters:

• crystal – Crystal object.

• bond_raw – BondRaw object.

property G

Integer displacement of the unit cells.

property i

Index of site-i.

property j

Index of site-j.

class spintoolkit_py.SymOP

Bases: pybind11_builtins.pybind11_object

Symmetry operation in three-dimensional space.

__init__(self)

Default constructor.

__init__(self, *, R: spintoolkit_py.Mat3, T: spintoolkit_py.Vec3)

Construct from a rotation matrix and a translation vector.

Parameters:

• R – Rotation matrix.

• T – Translation vector.

transform(self: spintoolkit_py.SymOP, arg0: spintoolkit_py.Vec3) → spintoolkit_py.Vec3

\(\boldsymbol{r} \rightarrow R\boldsymbol{r}+\boldsymbol{T}\).

Parameters:

r – Vector to be transformed.

Returns:

The transformed vector.

Return type:

Vec3

property R

Rotation matrix.

property T

Translation vector.

class spintoolkit_py.SiteSymmetry

Bases: pybind11_builtins.pybind11_object

Point group symmetry of a site.

__init__(self)

Default constructor.

__init__(self, *, symbol: str, multiplicity: int, wyckoff: str)

Construct from site symmetry information.

Parameters:

• symbol – Site symmetry symbol (point group).

• multiplicity – Multiplicity.

• wyckoff – Wyckoff index.

property multiplicity

Multiplicity.

property symbol

Site symmetry symbol (point group).

property wyckoff

Wyckoff index.

class spintoolkit_py.Crystal

Bases: pybind11_builtins.pybind11_object

Crystal that holds the lattice unit cell and symmetry info.

__init__(self)

Default constructor.

__init__(self, *, basis_a: list[list[float]], pos_sub: list[list[float]], types: list[int] = [], symprec: float = 1e-05)

Construct by inferring symmetry from basis vectors and site positions.

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

• types – List of atom types (If list empty, all atoms are set to type 0). (Default: [])

• symprec – Tolerance for symmetry checks. (Default: 1.0e-5)

__init__(self, *, basis_a: list[list[float]], pos_sub: list[list[float]], symbol: str, setting: str = '', types: list[int] = [], symprec: float = 1e-05)

Construct from a given space group symbol.

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

• symbol – Space group symbol (e.g., “P -1”, “F d -3 m”).

• setting – Space group setting. (Default: “”)

• types – List of atom types (If list empty, all atoms are set to type 0). (Default: [])

• symprec – Tolerance for symmetry checks. (Default: 1.0e-5)

__init__(self, *, basis_a: list[list[float]], pos_sub: list[list[float]], spacegroup_number: int, setting: str = '', types: list[int] = [], symprec: float = 1e-05)

Construct from a given international space group number.

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

• spacegroup_number – International space group number.

• setting – Space group setting. (Default: “”)

• types – List of atom types (If list empty, all atoms are set to type 0). (Default: [])

• symprec – Tolerance for symmetry checks. (Default: 1.0e-5)

__init__(self, *, name: str)

Construct from a common lattice name.

Parameters:

name – Name of the lattice. Choose from [cubic, fcc] (todo: update).

displacement(self, *, bond_raw: spintoolkit_py.BondRaw) → spintoolkit_py.Vec3

Displacement vector \(\boldsymbol{r}_j-\boldsymbol{r}_i\) in cartesian coordinates.

Parameters:

bond_raw – BondRaw object.

Return type:

spintoolkit_py.Vec3

Returns:

The displacement vector in Cartesian coordinates.

displacement(self, *, bond: spintoolkit_py.Bond) → spintoolkit_py.Vec3

Displacement vector \(\boldsymbol{r}_j-\boldsymbol{r}_i\) in cartesian coordinates, accounting for the integer offsets b.G between unit cells.

Parameters:

bond – Bond object.

Return type:

spintoolkit_py.Vec3

Returns:

The displacement vector in Cartesian coordinates.

distance(self, *, bond_raw: spintoolkit_py.BondRaw) → float

Distance between two sites measured in Cartesian coordinates.

Parameters:

bond_raw – BondRaw object.

Return type:

float

distance(self, *, bond: spintoolkit_py.Bond) → float

Distance between two sites measured in Cartesian coordinates, accounting for the integer offsets b.G between unit cells.

Parameters:

bond – Bond object.

Return type:

float

is_related_by_symmetry(self, *, bond_raw1: spintoolkit_py.BondRaw, bond_raw2: spintoolkit_py.BondRaw) → bool

Return true if there is a symmetry operation that transforms one bond into another or its reverse.

Parameters:

• bond_raw1 – The first BondRaw object.

• bond_raw2 – The second BondRaw object.

Return type:

bool

is_related_by_symmetry(self, *, bond1: spintoolkit_py.Bond, bond2: spintoolkit_py.Bond) → bool

Return true if there is a symmetry operation that transforms one bond into another or its reverse.

Parameters:

• bond1 – The first Bond object.

• bond2 – The second Bond object.

Return type:

bool

is_coupling_valid(self, *, bond_raw: spintoolkit_py.BondRaw, J: spintoolkit_py.Mat3) → bool

Return true if a coupling matrix J is consistent with symmetries of a bond.

Parameters:

• bond_raw – BondRaw object.

• J – The coupling matrix.

Return type:

bool

is_coupling_valid(self, *, bond: spintoolkit_py.Bond, J: spintoolkit_py.Mat3) → bool

Return true if a coupling matrix J is consistent with symmetries of a bond.

Parameters:

• bond – Bond object

• J – The coupling matrix.

Return type:

bool

all_bonds_for_site(self: spintoolkit_py.Crystal, *, site: int, min_dist: SupportsFloat, max_dist: SupportsFloat) → list[spintoolkit_py.Bond]

Return a list of all bonds that start from a given site.

Parameters:

• site – Index of site.

• min_dist – Minimal bond distance to be considered.

• max_dist – Maximal bond distance to be considered.

Returns:

A list of all bonds found.

Return type:

list[Bond]

all_symmetry_related_bonds(self: spintoolkit_py.Crystal, *, bond_ref: spintoolkit_py.Bond) → list[spintoolkit_py.Bond]

Return a list of all bonds that are symmetry-equivalent to a reference bond or its reverse.

Parameters:

bond_ref – The reference bond.

Returns:

A list of all equivalent bonds.

Return type:

list[Bond]

all_symmetry_related_bonds_for_site(self: spintoolkit_py.Crystal, *, site: int, bond_ref: spintoolkit_py.Bond) → list[spintoolkit_py.Bond]

Return a list of all bonds that start from a given site that are symmetry equivalent to b_ref or its reverse.

Parameters:

• site – Index of site.

• bond_ref – The reference bond.

Returns:

A list of equivalent bonds.

Return type:

list[Bond]

all_symmetry_related_couplings(self: spintoolkit_py.Crystal, *, bond_ref: spintoolkit_py.Bond, J_ref: spintoolkit_py.Mat3) → list[tuple[spintoolkit_py.Bond, spintoolkit_py.Mat3]]

Given a reference bond and coupling matrix on that bond, return a list of symmetry-equivalent bonds and a corresponding list of symmetry-transformed coupling matrices.

Parameters:

• bond_ref – The reference bond.

• J_ref – The coupling matrix on the reference bond.

Returns:

List of (bond, coupling matrix) pairs.

Return type:

list[tuple[Bond, Mat3]]

all_symmetry_related_couplings_for_site(self: spintoolkit_py.Crystal, *, site: int, bond_ref: spintoolkit_py.Bond, J_ref: spintoolkit_py.Mat3) → list[tuple[spintoolkit_py.Bond, spintoolkit_py.Mat3]]

Given a reference bond and coupling matrix on that bond, return a list of symmetry-equivalent bonds (constrained to start from a given site), and a corresponding list of symmetry-transformed coupling matrices.

Parameters:

• site – Index of site.

• bond_ref – The reference bond.

• J_ref – The coupling matrix on the reference bond.

Returns:

List of (bond, coupling matrix) pairs.

Return type:

list[tuple[Bond, Mat3]]

cell_type(self: spintoolkit_py.Crystal) → str

Return the cell type (e.g., “triclinic”, “monoclinic”, …).

cell_volume(self: spintoolkit_py.Crystal) → float

Return volume of the unit cell.

coordination_number(self: spintoolkit_py.Crystal, *, site: int, bond_ref: spintoolkit_py.Bond) → int

Return the times that a given site participates in a bond equivalent to b_ref. In other words, the count of bonds that begin at a given site and that are symmetry-equivalent to b_ref or its reverse.

Parameters:

• site – Index of site.

• bond_ref – The reference bond.

Returns:

The coordination number.

Return type:

int

equiv_sites(self: spintoolkit_py.Crystal, *, site: int) → list[int]

Return a list of all sublattice indices in the same symmetry equivalency class as the provided site index.

Parameters:

site – Index of site.

Returns:

A list of equivalent sublattice indices.

Return type:

list[int]

is_equivalent_by_translation(self: spintoolkit_py.Crystal, *, bond_raw1: spintoolkit_py.BondRaw, bond_raw2: spintoolkit_py.BondRaw) → bool

Return true if two bonds are equivalent by translation.

Parameters:

• bond_raw1 – The first BondRaw object.

• bond_raw2 – The second BondRaw object.

lattice_constant_min(self: spintoolkit_py.Crystal) → float

Return the minimum of the lattice constants (a, b, c).

num_sub(self: spintoolkit_py.Crystal) → int

Return the number of sublattices in the unit cell.

position_index(self: spintoolkit_py.Crystal, *, r: Annotated[list[float], 'FixedSize(3)']) → int

For a given vector, return its index in the unit cell.

Parameters:

r – Coordinate in units of \(\boldsymbol{a}_j\).

Returns:

Index in the unit cell.

Return type:

int

print_bond(self: spintoolkit_py.Crystal, *, bond: spintoolkit_py.Bond, digits: int = 3, tol: float = 1e-05) → None

Pretty-print symmetry information of a bond.

Parameters:

• bond – Bond to be printed.

• digits – Number of digits for printing. (Default: 3)

• tol – Tolerance for symmetry checks. (Default: 1.0e-5)

print_bond_table(self: spintoolkit_py.Crystal, *, max_dist: SupportsFloat, digits: int = 3, tol: float = 0.0001) → None

Pretty-print a table of bonds, one for each symmetry equivalence class, up to a maximal bond length of max_dist.

Parameters:

• max_dist – Maximal bond length to be considered.

• digits – Number of digits for printing. (Default: 3)

• tol – Tolerance for symmetry checks. (Default: 1.0e-4)

print_site(self: spintoolkit_py.Crystal, *, site: int, digits: int = 3, tol: float = 1e-05) → None

Pretty-print symmetry information of a site.

Parameters:

• site – Index of site.

• digits – Number of digits for printing. (Default: 3)

• tol – Tolerance for symmetry checks. (Default: 1.0e-5)

reference_bonds(self: spintoolkit_py.Crystal, *, max_dist: SupportsFloat) → list[spintoolkit_py.Bond]

Return a full list of bonds, one for each symmetry equivalence class, up to distance max_dist.

The reference bond for each equivalence class is selected according to a scoring system that prioritizes simplification of the elements in basis_for_symmetry_allowed_couplings(cryst, b).

Parameters:

max_dist – Maximal bond distance to be considered.

Returns:

A list of reference bonds.

Return type:

list[Bond]

symmetry_between_bonds(self: spintoolkit_py.Crystal, *, bond_raw1: spintoolkit_py.BondRaw, bond_raw2: spintoolkit_py.BondRaw) → list[tuple[spintoolkit_py.SymOP, bool]]

Generate a list of all symmetries that transform the second bond into the first one, along with parity.

Parameters:

• bond_raw1 – The first BondRaw object.

• bond_raw2 – The second BondRaw object.

Returns:

A list of (SymmetryOperation, parity) pairs.

Return type:

list[tuple[SymOP, bool]]

property basis_a

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

property classes

Symmetry class indices for each site.

property pos_sub

Sublattice coordinates in units of \(\boldsymbol{a}_j\).

property sitesyms

List of site symmetry information.

property spacegroup

Description of the space group.

property symops

List of symmetry operations.

property symprec

Tolerance for symmetry checks.

property types

Atom types.

Functions

spintoolkit_py.lattice_basis2angle(*, basis_a: list[list[float]]) → tuple[float, float, float, float, float, float]

Compute lattice parameters from real-space basis vectors.

Parameters:

basis_a – Real-space basis vectors \([\boldsymbol{a}_0, \boldsymbol{a}_1, \ldots]\).

Returns:

• a (float) – Lattice constant a.

• b (float) – Lattice constant b.

• c (float) – Lattice constant c.

• alpha (float) – Angle \(\alpha\) in units of degree.

• beta (float) – Angle \(\beta\) in units of degree.

• gamma (float) – Angle \(\gamma\) in units of degree.

spintoolkit_py.lattice_angle2basis(*, a: SupportsFloat, b: SupportsFloat, c: SupportsFloat, alpha: SupportsFloat, beta: SupportsFloat, gamma: SupportsFloat) → list[list[float]]

Compute real-space basis vectors from lattice parameters.

Parameters:

• a – Lattice constant a.

• b – Lattice constant b.

• c – Lattice constant c.

• alpha – Angle \(\alpha\) in units of degree.

• beta – Angle \(\beta\) in units of degree.

• gamma – Angle \(\gamma\) in units of degree.

Returns:

basis_a – Real-space basis vectors \([\boldsymbol{a}_0, \boldsymbol{a}_1, \ldots]\).

Return type:

list[list[float]]