pyspinw.exchange#

Exchange terms between lattice sites.

Functions

specialise_exchange(exchange[, ...])

Find the narrowest exchange subclass to fit the exchange

Classes

`DMExchange`(site_1, site_2, d_x, d_y, d_z[, ...])	Represent a Dzyaloshinskii-Moriya exchange term.
`DiagonalExchange`(site_1, site_2, j_x, j_y, j_z)	Represent a diagonal exchange term.
`Exchange`(site_1, site_2, cell_offset, ...[, ...])	Represent an exchange term between two lattice sites.
`ExchangeBaseDeserialisation`(name, site_1, ...)	Hold basic properties of an exchange term.
`HeisenbergExchange`(site_1, site_2, j[, ...])	Represent a Heisenberg exchange term.
`IsingExchange`(site_1, site_2, j_z[, ...])	Represent an Ising exchange term for the z component.
`XXZExchange`(site_1, site_2, j_xy, j_z[, ...])	Represent an XXZ exchange term.
`XYExchange`(site_1, site_2, j[, cell_offset, ...])	Represent an XY exchange term.

class pyspinw.exchange.DMExchange(site_1: Site, site_2: Site, d_x: float, d_y: float, d_z: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent a Dzyaloshinskii-Moriya exchange term.

The exchange takes the form

\[H_{ij} = \mathbf{D}_{ij} \cdot (\mathbf{S}_i \times \mathbf{S}_j).\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
d_x (float) – x component of the D vector, \(\mathbf{D}^x_{ij}\).
d_y (float) – y component of the D vector, \(\mathbf{D}^y_{ij}\).
d_z (float) – z component of the D vector, \(\mathbf{D}^z_{ij}\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

property d_x#: DM exchange constant for x.

property d_y#: DM exchange constant for y.

property d_z#: DM exchange constant for z.

exchange_type = 'Dzyaloshinskii-Moriya'#

is_symmetric()#: Return whether this is a symmetric exchange.

parameter_defaults: list[float] = [1.0, 1.0, 1.0]#

parameters: list[str] = ['d_x', 'd_y', 'd_z']#

short_string = 'DM'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
d_x (float, optional) – Replacement x D-vector component. If omitted, the current component is reused.
d_y (float, optional) – Replacement y D-vector component. If omitted, the current component is reused.
d_z (float, optional) – Replacement z D-vector component. If omitted, the current component is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

class pyspinw.exchange.DiagonalExchange(site_1: Site, site_2: Site, j_x: float, j_y: float, j_z: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent a diagonal exchange term.

The exchange takes the form

\[H_{ij} = J^{xx}_{ij} \mathbf{S}^x_i \mathbf{S}^x_j + J^{yy}_{ij} \mathbf{S}^y_i \mathbf{S}^y_j + J^{zz}_{ij} \mathbf{S}^z_i \mathbf{S}^z_j.\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
j_x (float) – Scalar exchange coefficient for the x component, \(J^{xx}_{ij}\).
j_y (float) – Scalar exchange coefficient for the y component, \(J^{yy}_{ij}\).
j_z (float) – Scalar exchange coefficient for the z component, \(J^{zz}_{ij}\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

exchange_type = 'Diagonal'#

is_symmetric()#

Return whether this is a symmetric exchange.

A diagonal exchange is always symmetric, so this always returns True.

property j_x#: Exchange constant for x.

property j_y#: Exchange constant for y.

property j_z#: Exchange constant for z.

parameter_defaults: list[float] = [1.0, 1.0, 1.0]#

parameters: list[str] = ['j_x', 'j_y', 'j_z']#

short_string = 'J'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
j_x (float, optional) – Replacement x exchange coefficient. If omitted, the current coefficient is reused.
j_y (float, optional) – Replacement y exchange coefficient. If omitted, the current coefficient is reused.
j_z (float, optional) – Replacement z exchange coefficient. If omitted, the current coefficient is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

class pyspinw.exchange.Exchange(site_1: Site, site_2: Site, cell_offset: CellOffset | tuple[int, int, int] | None, exchange_matrix: ndarray, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: SPWSerialisable

Represent an exchange term between two lattice sites.

Parameters:

site_1 (Site) – First lattice site in the exchange term.
site_2 (Site) – Second lattice site in the exchange term.
cell_offset (CellOffsetCoercible) – Offset between the unit cells containing the two sites.
exchange_matrix (numpy.ndarray) – 3x3 matrix defining the exchange interaction.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

property cell_offset#: Offset between unit cells containing sites 1 and 2.

distance(unit_cell: UnitCell)#

Return the distance between site 1 and site 2 in Cartesian coordinates.

Parameters:: unit_cell – Unit cell used to convert lattice coordinates to Cartesian coordinates.
Returns:: Distance between site 1 and site 2 in Cartesian coordinates.
Return type:: float

property exchange_matrix: ndarray#

The exchange matrix for this exchange.

If \(H\) is the energy contribution for this exchange, \(\mathbf{S}_i\) and \(\mathbf{S}_j\) are the spin states, and \(M\) is the exchange matrix, then

\[H = \mathbf{S}_i^T M \mathbf{S}_j.\]

exchange_type = 'General'#

generalise()#: Convert to most general Exchange class

is_symmetric()#: Return whether this is a symmetric exchange.

property lattice_vector#: Vector from site 1 to site 2 in lattice coordinates.

property name#: Name of this exchange.

obeys_symmetry(structure: Structure) → bool#: Check that this exchange is consistent with the symmetry group

parameter_defaults: list[float] = []#

property parameter_string: str#: String representation of the exchange parameters.

parameters: list[str] = []#

serialisation_name = 'exchange'#

short_string = 'M'#

property site_1#: First site in the exchange term.

property site_2#: Second site in the exchange term.

specialise()#: Get the most specific exchange class available that fits this exchange

symmetry_copy(structure: Structure, site_1: Site, site_2: Site, cell_offset: CellOffset | tuple[int, int, int] | None = (0, 0, 0)) → Exchange#: Copy this exchange using symmetry operations

symmetry_fill(structure: Structure, include_original=False, specialisation_rounding_exponent: int | None = 14) → list[Exchange]#: Make multiple copies of this exchange so that symmetry is satisfied

property unique_id: int#: Unique identifier for this exchange.

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
exchange_matrix (numpy.ndarray, optional) – Replacement exchange matrix. If omitted, the current matrix is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

vector(unit_cell: UnitCell)#

Return the vector from site 1 to site 2 in Cartesian coordinates.

Parameters:: unit_cell – Unit cell used to convert lattice coordinates to Cartesian coordinates.
Returns:: Vector from site 1 to site 2 in Cartesian coordinates.
Return type:: numpy.ndarray

class pyspinw.exchange.ExchangeBaseDeserialisation(name: str, site_1: Site, site_2: Site, cell_offset: CellOffset, metadata: ExchangeMetadata)#

Bases: object

Hold basic properties of an exchange term.

cell_offset: CellOffset#

metadata: ExchangeMetadata#

name: str#

site_1: Site#

site_2: Site#

class pyspinw.exchange.HeisenbergExchange(site_1: Site, site_2: Site, j: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent a Heisenberg exchange term.

The exchange takes the form

\[H_{ij} = J_{ij} \, (\mathbf{S}_i \cdot \mathbf{S}_j).\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
j (float) – Exchange coefficient, \(J_{ij}\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

exchange_type = 'Heisenberg'#

is_symmetric()#

Return whether this is a symmetric exchange.

A Heisenberg exchange is always symmetric, so this always returns True.

property j#: Exchange constant.

parameter_defaults: list[float] = [1.0]#

parameters: list[str] = ['j']#

short_string = 'J'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
j (float, optional) – Replacement exchange coefficient. If omitted, the current coefficient is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

class pyspinw.exchange.IsingExchange(site_1: Site, site_2: Site, j_z: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent an Ising exchange term for the z component.

The exchange takes the form

\[H_{ij} = J_{ij} \, \mathbf{S}^z_i \mathbf{S}^z_j.\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
j_z (float) – Exchange coefficient for the z component, \(J_{ij}\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

exchange_type = 'Ising'#

is_symmetric()#

Return whether this is a symmetric exchange.

An Ising exchange is always symmetric, so this always returns True.

property j_z#: Exchange constant for z.

parameter_defaults: list[float] = [1.0]#

parameters: list[str] = ['j_z']#

short_string = 'J'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
j_z (float, optional) – Replacement z exchange coefficient. If omitted, the current coefficient is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

class pyspinw.exchange.XXZExchange(site_1: Site, site_2: Site, j_xy: float, j_z: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent an XXZ exchange term.

The exchange takes the form

\[H_{ij} = J_{xy} \, (\mathbf{S}^x_i \mathbf{S}^x_j + \mathbf{S}^y_i \mathbf{S}^y_j) + J_z \, (\mathbf{S}^z_i \mathbf{S}^z_j).\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
j_xy (float) – Exchange coefficient for the x and y components, \(J_{xy}\).
j_z (float) – Exchange coefficient for the z component, \(J_z\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

exchange_type = 'XXZ'#

is_symmetric()#

Return whether this is a symmetric exchange.

An XXZ exchange is always symmetric, so this always returns True.

property j_xy#: Exchange constant for x and y.

property j_z#: Exchange constant for z.

parameter_defaults: list[float] = [1.0, 1.0]#

parameters: list[str] = ['j_xy', 'j_z']#

short_string = 'J'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
j_xy (float, optional) – Replacement x-y exchange coefficient. If omitted, the current coefficient is reused.
j_z (float, optional) – Replacement z exchange coefficient. If omitted, the current coefficient is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

class pyspinw.exchange.XYExchange(site_1: Site, site_2: Site, j: float, cell_offset: CellOffset | tuple[int, int, int] | None = None, name: str = '', color: tuple[float, float, float] | None = None, metadata: ExchangeMetadata | None = None)#

Bases: Exchange

Represent an XY exchange term.

The exchange takes the form

\[H_{ij} = J_{ij} \, (\mathbf{S}^x_i \mathbf{S}^x_j + \mathbf{S}^y_i \mathbf{S}^y_j).\]

Parameters:

site_1 (Site) – Lattice site associated with \(\mathbf{S}_i\).
site_2 (Site) – Lattice site associated with \(\mathbf{S}_j\).
j (float) – Exchange coefficient for the x and y components, \(J_{ij}\).
cell_offset (CellOffsetCoercible, optional) – Offset between the unit cells containing the two sites.
name (str, optional) – Name for the exchange term. Default is "".
color (tuple of float, optional) – RGB color used when displaying the exchange term.
metadata (ExchangeMetadata, optional) – Metadata attached to the exchange term.

exchange_type = 'XY'#

is_symmetric()#

Return whether this is a symmetric exchange.

An XY exchange is always symmetric, so this always returns True.

property j#: Exchange constant for x and y.

parameter_defaults: list[float] = [1.0]#

parameters: list[str] = ['j']#

short_string = 'J'#

Return a copy of this exchange with variables replaced.

Parameters:

site_1 (LatticeSite, optional) – Replacement first lattice site. If omitted, the current site is reused.
site_2 (LatticeSite, optional) – Replacement second lattice site. If omitted, the current site is reused.
cell_offset (CellOffset, optional) – Replacement unit-cell offset. If omitted, the current offset is reused.
name (str, optional) – Replacement exchange name. If omitted, the current name is reused.
j (float, optional) – Replacement exchange coefficient. If omitted, the current coefficient is reused.
metadata (ExchangeMetadata, optional) – Replacement metadata. If omitted, the current metadata is copied.

pyspinw.exchange.specialise_exchange(exchange: Exchange, rounding_exponent: int | None = None)#: Find the narrowest exchange subclass to fit the exchange