hqs_quantum_solver.spins

Operators for spin systems.

Functions

expression_term(spin_expression, *[, ...])	A spin operator term given by a ExpressionSpinful object.
interaction_cross(coef)	Cross product interaction term.
interaction_cross_and_spin_y(coef)	Term for the cross product interaction and the magnetic field in y-direction.
interaction_perp(coef)	Interaction perpendicular to the z-axis.
interaction_perp_and_spin_x(coef)	Interaction perpendicular to the z-axis and the magnetic field in x-direction.
interaction_z(coef)	The spin coupling in the z-direction.
interaction_z_and_spin_z(coef)	The spin coupling in the z-direction and the magnetic field in z-direction.
isotropic_interaction(coef)	The Heisenberg spin-spin interaction.
lowering(*[, site, coef])	The spin lowering operators.
magnetic_field_x(*[, site, coef])	Terms representing a magnetic field in x-direction.
magnetic_field_y(*[, site, coef])	Terms representing a magnetic field in y-direction.
magnetic_field_z(*[, site, coef])	Terms representing a magnetic field in z-direction.
raising(*[, site, coef])	The spin raising operators.
raising_lowering_hc(coef)	Term of raising after lowering plus hermitian conjugate.
raising_raising_hc(coef)	Term of raising after raising plus hermitian conjugate.
spin_x(*[, site, coef])	The spin operators for the x-direction.
spin_y(*[, site, coef])	The spin operators for the y-direction.
spin_z(*[, site, coef])	The spin operators for the z-direction.
struqture_term(struqture_operator)	A spin-operator term defined by a Struqture operator.

Classes

EntriesFromFunction(fun, dtype)	Method generated by attrs for class EntriesFromFunction.
MatrixEntryGenerator()
Operator(*args, **kwargs)	Operator acting on the state of a spin system.
OperatorInfo(*, domain, codomain, dtype)	The properties of an operator excluding the matrix elements.
SpinHamiltonian(*[, coef_spin_z, ...])	Defines entries of a quantum mechanical operator for a spin system.
SpinState(value[, names, module, qualname, ...])	The two states of a spin-½ particle.
VectorSpace(*, sites, total_spin_z)	Vector space describing a spin system.

class Operator(*args, **kwargs)

Operator acting on the state of a spin system.

Creates an operator.

Parameters:

• expression (Expression) – The expression defining the operator.

• domain (VectorSpace) – The domain of the operator.

• codomain (VectorSpace) – The codomain of the operator.

• dtype (Optional[DTypeLike]) – The dtype of the operator.

• operator_type (Optional[OperatorFactory]) – The linear algebra backend.

property H

Hermitian adjoint.

Returns the Hermitian adjoint of self, aka the Hermitian conjugate or Hermitian transpose. For a complex matrix, the Hermitian adjoint is equal to the conjugate transpose.

Can be abbreviated self.H instead of self.adjoint().

Returns:

A_H – Hermitian adjoint of self.

Return type:

LinearOperator

property T

Transpose this linear operator.

Returns a LinearOperator that represents the transpose of this one. Can be abbreviated self.T instead of self.transpose().

__init__(expression: Expression, *, domain: VectorSpace, codomain: VectorSpace | None = None, dtype: DTypeLike | None = None, operator_type: OperatorFactory | None = None) → None

Creates an operator.

Parameters:

• expression (Expression) – The expression defining the operator.

• domain (VectorSpace) – The domain of the operator.

• codomain (VectorSpace) – The codomain of the operator.

• dtype (Optional[DTypeLike]) – The dtype of the operator.

• operator_type (Optional[OperatorFactory]) – The linear algebra backend.

adjoint()

Hermitian adjoint.

Returns the Hermitian adjoint of self, aka the Hermitian conjugate or Hermitian transpose. For a complex matrix, the Hermitian adjoint is equal to the conjugate transpose.

Can be abbreviated self.H instead of self.adjoint().

Returns:

A_H – Hermitian adjoint of self.

Return type:

LinearOperator

property codomain: VectorSpace

The vector space that is the codomain of the operator.

property domain: VectorSpace

The vector space that is the domain of the operator.

dot(x: ndarray, out: ndarray | None = None) → ndarray

Compute the dot product of operator with array; optional out to avoid reallocation.

When represented by NumPy this operation would be A @ x.

Parameters:

• x (np.ndarray) – The vector/array to dot product with.

• out (Optional[np.ndarray]) – Optional array to store results and avoid reallocation.

Returns:

The result of the dot product, A @ x.

Return type:

np.ndarray

dot_add(x: ndarray, out: ndarray, z: float | complex = 1.0) → None

Compute the dot product of operator with array and add it to out array.

When represented by NumPy this operation would be out += z * (A @ x).

Parameters:

• x (np.ndarray) – The vector/array to dot product with.

• out (np.ndarray) – The array to which the outcome will be added.

• z (complex) – scalar prefactor before addition, defaults to unity.

dot_h(x: ndarray, out: ndarray | None = None) → ndarray

Compute the dot product of operator adjoint with array, allows optional out.

When represented by NumPy this operation would be A.conj().T @ x. Though transpose returns only a view of a matrix, conjugate returns a copy, hence this method.

Parameters:

• x (np.ndarray) – The vector/array to dot product with.

• out (Optional[np.ndarray]) – Optional array to store results and avoid reallocation.

Returns:

The result of the dot product, A.conj().T @ x.

Return type:

np.ndarray

property dtype: OperatorDType

The NumPy dtype.

matmat(X)

Matrix-matrix multiplication.

Performs the operation y=A@X where A is an MxN linear operator and X dense N*K matrix or ndarray.

Parameters:

X ({matrix, ndarray}) – An array with shape (N,K).

Returns:

Y – A matrix or ndarray with shape (M,K) depending on the type of the X argument.

Return type:

{matrix, ndarray}

Notes

This matmat wraps any user-specified matmat routine or overridden _matmat method to ensure that y has the correct type.

matvec(x)

Matrix-vector multiplication.

Performs the operation y=A@x where A is an MxN linear operator and x is a column vector or 1-d array.

Parameters:

x ({matrix, ndarray}) – An array with shape (N,) or (N,1).

Returns:

y – A matrix or ndarray with shape (M,) or (M,1) depending on the type and shape of the x argument.

Return type:

{matrix, ndarray}

Notes

This matvec wraps the user-specified matvec routine or overridden _matvec method to ensure that y has the correct shape and type.

rdot(x: ndarray) → ndarray

Compute the dot product of array with operator.

When represented by NumPy this operation would be x @ A.

Parameters:

x (np.ndarray) – The vector/array to dot product with.

Returns:

The result of the dot product, x @ A.

Return type:

np.ndarray

rdot_h(x: ndarray) → ndarray

Compute the dot product of array with operator adjoint.

When represented by NumPy this operation would be x @ A.conj().T.

Parameters:

x (np.ndarray) – The vector/array to dot product with.

Returns:

The result of the dot product, x @ A.conj().T.

Return type:

np.ndarray

rmatmat(X)

Adjoint matrix-matrix multiplication.

Performs the operation y = A^H @ x where A is an MxN linear operator and x is a column vector or 1-d array, or 2-d array. The default implementation defers to the adjoint.

Parameters:

X ({matrix, ndarray}) – A matrix or 2D array.

Returns:

Y – A matrix or 2D array depending on the type of the input.

Return type:

{matrix, ndarray}

Notes

This rmatmat wraps the user-specified rmatmat routine.

rmatvec(x)

Adjoint matrix-vector multiplication.

Performs the operation y = A^H @ x where A is an MxN linear operator and x is a column vector or 1-d array.

Parameters:

x ({matrix, ndarray}) – An array with shape (M,) or (M,1).

Returns:

y – A matrix or ndarray with shape (N,) or (N,1) depending on the type and shape of the x argument.

Return type:

{matrix, ndarray}

Notes

This rmatvec wraps the user-specified rmatvec routine or overridden _rmatvec method to ensure that y has the correct shape and type.

property shape: tuple[int, int]

Returns the shape tuple of the class.

Returns:

The tuple containing the dimensions of the class.

Return type:

Tuple[int, …]

todense() → ndarray

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

transpose()

Transpose this linear operator.

Returns a LinearOperator that represents the transpose of this one. Can be abbreviated self.T instead of self.transpose().

class SpinState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The two states of a spin-½ particle.

DOWN = 1

‘Down’ spin state.

UP = 2

‘Up’ spin state.

class VectorSpace(*, sites: int, total_spin_z: int | tuple[int, int])

Vector space describing a spin system.

sites

the number of sites.

Type:

int

spin_representation

the spin representation / spin quantum number, s, in units of ħ/2, i.e. an integer. If not specified it defaults to 1 (i.e. spin-1/2).

Type:

int

total_spin_z_offset

Together with total_spin_z_stride, specifies the possible values for the total spin polarization in the z-axis, \(S_z\), of the system. The possible values are total_spin_z plus any multiple of total_spin_z_stride.

The spin polarization is measured in units of ħ/2. abs(total_spin_z) must be less than or equal to the number of sites times the spin representation, sites * spin_representation.

Type:

Optional[int]

total_spin_z_stride

Together with total_spin_z_offset, specifies the possible values for the total spin polarization in the z-axis, \(S_z\), of the system. The possible values are total_spin_z plus any multiple of total_spin_z_stride.

A value of total_spin_z_stride=0 enforces conservation of the total spin polarization (even if it is not reasonable). E.g., in the presence of a transverse magnetic field (Bx ≠ 0 and/or By ≠ 0), Sz is no longer a good quantum number. In order to allow for breaking this symmetry total_spin_z_stride to be a positive even integer. For example, total_spin_z_stride=2 allows states to be a superposition of states differing by single or multiple spin flips.

Type:

int

Create the vector space.

__init__(*, sites: int, total_spin_z: int | tuple[int, int]) → None

Create the vector space.

copy(*, total_spin_z_change: int = 0) → VectorSpace

Returns a new vector space with a different value for the total spin polarization.

Parameters:

total_spin_z_change (int) – The value to be added to the total spin polarization.

Note

The argument total_spin_z_change is measured in units of \(\hbar/2\). Thus, for representing a spin flip from \(-\hbar/2\) to \(\hbar/2\), total_spin_z_change must be set to 2.

property dim: int

The dimension of the vector space.

fock_state(occupation: list[int] | list[SpinState], dtype: DTypeLike = None) → np.ndarray

Returns an element of the occupancy number basis.

Given a list of single-spin states, i.e., \(\sigma_i \in \{ \downarrow, \uparrow \}\) for \(i = 0, \dots, n-1\), this function returns a representation of the state

\[\ket{\sigma_0 \, \sigma_1 \cdots \sigma_{n-1}} = \ket{\sigma_0} \otimes \ket{\sigma_1} \otimes \cdots \otimes \ket{\sigma_{n-1}} \,.\]

Parameters:

• occupation (list[int] | list[SpinState]) – The occupation number per site. When given as an integer, must be either 0 for spin down or 1 for spin up.

• dtype (type) – The datatype of the state vector to be returned.

Returns:

The state vector.

Return type:

ndarray

interaction_cross(coef: ndarray) → Expression[MatrixEntryGenerator]

Cross product interaction term.

The term is defined by

\[\begin{split}\sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} J^\times_{jk} \, \mathbf{e}_z \cdot \left( \hat{\mathbf{S}}_j \times \hat{\mathbf{S}}_k \right) \,,\end{split}\]

where \(J^\times_{jk} \in \mathbb{R}\) are the given coefficients.

Note

This function expects the coef argument to be real-valued and its diagonal to be zero.

interaction_cross_and_spin_y(coef: ndarray) → Expression[MatrixEntryGenerator]

Term for the cross product interaction and the magnetic field in y-direction.

The term is defined by

\[\begin{split}\sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} J^\times_{jk} \, \mathbf{e}_z \cdot \left( \hat{\mathbf{S}}_j \times \hat{\mathbf{S}}_k \right) + \sum_{j = 0}^{M-1} J_{jj} \hat{S}^y_j \,,\end{split}\]

where \(J_{jk}\) are the given coefficients.

Note

The matrix \(J\) is expected to be real-valued.

interaction_perp(coef: ndarray) → Expression[MatrixEntryGenerator]

Interaction perpendicular to the z-axis.

The term is defined by

\[\sum_{j \not= k}^{M-1} J^\perp_{jk} \, \left( \hat{S}^x_j \hat{S}^x_k + \hat{S}^y_j \hat{S}^y_k \right) \,,\]

where \(J^\perp_{jk} \in \mathbb{R}\) are the given coefficients.

Note

This function expects the coef argument to be real-valued and its diagonal to be zero.

interaction_perp_and_spin_x(coef: ndarray) → Expression[MatrixEntryGenerator]

Interaction perpendicular to the z-axis and the magnetic field in x-direction.

Defines the term

\[\sum_{j \not= k}^{M-1} J_{jk} \left( \hat{S}^x_j \hat{S}^x_k + \hat{S}^y_j \hat{S}^y_k \right) + \sum_{j = 0}^{M-1} J_{jj} \hat{S}^x_j \,,\]

where \(J_{jk}\) are the given coefficients.

Note

The matrix \(J\) is expected to be real-valued.

interaction_z(coef: ArrayLike) → Expression

The spin coupling in the z-direction.

Defines the term

\[\begin{split}\sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} J^z_{jk} \, \hat{S}^z_j \hat{S}^z_k \,,\end{split}\]

where $J^z_{jk}$ are the given coefficients.

Parameters:

coef (ndarray) – The coefficient matrix \(J^z\).

Note

The function expects the diagonal elements of \(J^z\) to be zero.

interaction_z_and_spin_z(coef: ndarray) → Expression[MatrixEntryGenerator]

The spin coupling in the z-direction and the magnetic field in z-direction.

Defines the term

\[\begin{split}\sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} J^z_{jk} \, \hat{S}^z_j \hat{S}^z_k + \sum_{j=0}^{M-1} J^z_{jj} \, \hat{S}^z_j \,,\end{split}\]

where $J^z_{jk}$ are the given coefficients.

Parameters:

coef (ndarray) – The coefficient matrix \(J^z\).

Note

The function expects the diagonal elements of \(J^z\) to be zero.

isotropic_interaction(coef: ndarray) → Expression[MatrixEntryGenerator]

The Heisenberg spin-spin interaction.

The term is defined by

\[\sum_{j \not= k}^{M-1} J_{jk} \, \hat{\mathbf{S}}_j \cdot \hat{\mathbf{S}}_k \,,\]

where \(J_{jk} \in \mathbb{R}\) are the given coefficients.

Note

This function expects the coef argument to be real-valued and its diagonal to be zero.

lowering(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

The spin lowering operators.

Defines the term

\[\sum_{j=0}^{M-1} J^-_j \hat{S}^-_j \,,\]

where $J^-_j$ are the given coefficients.

Parameters:

• site (int) – When set to \(j\) then \(J^-\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(J^-\).

magnetic_field_x(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

Terms representing a magnetic field in x-direction.

Defines the term

\[- \sum_{j=0}^{M-1} B^x_j \hat{S}^x_j \,,\]

where $B^x_j$ are the given coefficients.

Important

This function assumes a negative-sign convention for the magnetic field, as indicated in the formula above.

Parameters:

• site (int) – When set to \(j\) then \(B^x\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(B^x\).

magnetic_field_y(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

Terms representing a magnetic field in y-direction.

Defines the term

\[- \sum_{j=0}^{M-1} B^y_j \hat{S}^y_j \,,\]

where $B^y_j$ are the given coefficients.

Important

This function assumes a negative-sign convention for the magnetic field, as indicated in the formula above.

Parameters:

• site (int) – When set to \(j\) then \(B^y\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(B^y\).

magnetic_field_z(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

Terms representing a magnetic field in z-direction.

Defines the term

\[- \sum_{j=0}^{M-1} B^z_j \hat{S}^z_j \,,\]

where $B^z_j$ are the given coefficients.

Important

This function assumes a negative-sign convention for the magnetic field, as indicated in the formula above.

Parameters:

• site (int) – When set to \(j\) then \(B^z\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(B^z\).

raising(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

The spin raising operators.

Defines the term

\[\sum_{j=0}^{M-1} J^+_j \hat{S}^+_j \,,\]

where $J^+_j$ are the given coefficients.

Parameters:

• site (int) – When set to \(j\) then \(J^+\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(J^+\).

raising_lowering_hc(coef: ndarray) → Expression[MatrixEntryGenerator]

Term of raising after lowering plus hermitian conjugate.

Defines the term

\[\sum_{j \not= k}^{M-1} J^p_{jk} \, \hat{S}^+_j \hat{S}^-_k + (J^p_{jk})^* \, \hat{S}^+_k \hat{S}^-_j \,,\]

where \(J^p_{jk}\) are the given coefficients.

Note

The diagonal of the coefficient matrix is expected to be zero.

raising_raising_hc(coef: ndarray) → Expression[MatrixEntryGenerator]

Term of raising after raising plus hermitian conjugate.

Defines the term

\[\sum_{j,k=0}^{M-1} J^d_{jk} \, \hat{S}^+_j \hat{S}^+_k + (J^d_{jk})^* \, \hat{S}^-_k \hat{S}^-_j\]

where \(J^d_{jk}\) are the given coefficients.

spin_x(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

The spin operators for the x-direction.

Defines the term

\[\sum_{j=0}^{M-1} J^x_j \hat{S}^x_j \,,\]

where $J^x_j$ are the given coefficients.

Parameters:

• site (int) – When set to \(j\) then \(J^x\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(J^x\).

spin_y(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

The spin operators for the y-direction.

Defines the term

\[\sum_{j=0}^{M-1} J^y_j \hat{S}^y_j \,,\]

where $J^y_j$ are the given coefficients.

Parameters:

• site (int) – When set to \(j\) then \(J^y\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(J^y\).

spin_z(*, site: int | None = None, coef: ArrayLike | None = None) → Expression

The spin operators for the z-direction.

Defines the term

\[\sum_{j=0}^{M-1} J^z_j \hat{S}^z_j \,,\]

where \(J^z_j\) are the given coefficients.

Parameters:

• site (int) – When set to \(j\) then \(J^z\) is j-th cannonical unit vector.

• coef (ArrayLike) – Directly sets the coefficients \(J^z\).