hqs_quantum_solver.spins

hqs_quantum_solver.spins#

Operators for spin systems.

Functions

`expression_term`(spin_expression, *[, ...])	A spin operator term given by an ExpressionSpinful object.
`identity`()	The identity operator.
`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.
`lattice_terms`(lattice)	A spin-operator term defined by a Lattice Builder configuration.
`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

`Operator`	Operator acting on the state of a spin system.
`SpinState`	The two states of a spin-½ particle.
`VectorSpace`	Vector space describing a spin system.

class Operator#

Operator acting on the state of a spin system.

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: SparseMatrixFactory | 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.

static __new__(cls, *args, **kwargs)#

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, …]

tocsr() → csr_array#

CSR representation of the operator.

Returns:: The representation.
Return type:: csr_array

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#

The two states of a spin-½ particle.

DOWN = 1#: ‘Down’ spin state.

UP = 2#: ‘Up’ spin state.

class VectorSpace#

Vector space describing a spin system.

The space is spanned by vectors of the form

\[\bigotimes_{j = 0}^{M-1} \ket{\sigma_j} \quad\text{where}\quad \sigma_j \in \{ \uparrow, \downarrow \} \,.\]

The vector space contains all vectors from the set above where the total spin polarization in z-direction is equal to

\[\tfrac{\hbar}{2} \left( \texttt{total_spin_z_offset} + k \cdot \texttt{total_spin_z_stride} \right)\]

for $k \in \mathbb{Z}$.

sites#

The number of sites $M$.

Type:: int

total_spin_z_offset#

The offset of the restriction of the total spin polarization in z-direction.

Type:: int

total_spin_z_stride#

The stride of the restriction of the total spin polarization in z-direction.

Type:: int

__init__(*, sites: int, total_spin_z: Literal['all'] | int | tuple[int, int]) → None#

Create the vector space.

Parameters:

sites (int) – The number of sites in the system.
total_spin_z ("all" | int | tuple[int, int]) –
Restricts the states of the system. "all"

When providing the string "all", all possible states are represented by this vector space.

int
When providing a single integer, restricts the vector space to states whose spin polarization is equal to total_spin_z (in units of ℏ/2).

tuple[int,int]
When providing a tuple (offset, stride), restricts the space to states whose spin polarization is equal to offset plus and integer multiple of stride (in units of ℏ/2).

all_occupations() → Iterator[list[int]]#

Iterator over all possible occupation configurations.

Returns:: The iterator.
Return type:: Iterator[list[int]]

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

expression_term(spin_expression: ExpressionSpinful | ExpressionSpinful_complex, *, _min_site_count: int | None = None) → Expression[MatrixEntryGenerator]#

A spin operator term given by an ExpressionSpinful object.

This function is used to adapt an ExpressionSpinful object from Lattice Functions to an Quantum Solver Operator.

Parameters:: spin_expression (ExpressionSpinful) – The expression.

identity() → Expression[MatrixEntryGenerator]#

The identity operator.

Returns:: Term describing the identity operator.
Return type:: Expression

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.

lattice_terms(lattice: dict[str, Any] | lb.models.LatticeBuilderInputSpins | lb.Builder) → Expression#

A spin-operator term defined by a Lattice Builder configuration.

Defines the spin Hamiltonian, as defined in the physics chapter of the SCCE Documentation.

Parameters:: lattice (dict | LatticeBuilderInputSpins | Builder) – A lattice builder configuration or object.
Returns:: Term for use as an argument to Operator.
Return type:: Expression

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$.

struqture_term(struqture_operator: PlusMinusOperator | SpinHamiltonianSystem | SpinSystem) → Expression#

A spin-operator term defined by a Struqture operator.

Parameters:: struqture_operator (PlusMinusOperator | SpinHamiltonianSystem | SpinSystem) – The Struqture operator.
Returns:: Term for use as an argument to Operator.
Return type:: Expression

hqs_quantum_solver.spins

Contents

hqs_quantum_solver.spins#