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_term`(lattice)	A spin-operator term defined by a Lattice Builder configuration.
`lattice_terms`(args, *kwargs)	Alias for lattice_term.
`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.
`zero`()	Zero operator for a spinless fermion system.

Classes

`EntriesFromFunction`
`MatrixEntryGenerator`
`Operator`	Operator acting on the state of a spin system.
`OperatorInfo`	The properties of an operator excluding the matrix elements.
`SpinHamiltonian`	Defines entries of a quantum mechanical operator for a spin system.
`SpinState`	The two states of a spin-½ particle.
`VectorSpace`	Vector space describing a spin system.
`VectorSpaceOpsMixin`	Mixin for common vector space operations.
`VectorSpaceProduct`
`VectorSpaceProtocol`
`VectorSpaceSpan`

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

__call__(x)#: Call self as a function.

__init__(expression: Expression, *, domain: VectorSpaceProtocol, codomain: VectorSpaceProtocol | None = None, dtype: DTypeLike | None = None, operator_type: SparseMatrixFactory | None = None, strict: bool = True) → 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.
strict (bool) – When set to true an error is raised when the constructed operator maps to a state that is not part of the codomain. When set to false, the state is silently dropped.

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: VectorSpaceProtocol#: The vector space that is the codomain of the operator.

property domain: VectorSpaceProtocol#: 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

product(other: VectorSpaceProtocol) → VectorSpaceProduct#

Returns the tensor product of self and other.

The returned vector space represents the cartesian product of the quantum states represented by self and other, i.e., all possible combinations of the states of self and other.

Parameters:: other – The other vector space.
Returns:: The resulting vector space.
Return type:: VectorSpaceProduct

span(other: VectorSpaceProtocol) → VectorSpaceSpan#

Returns a vector space spanned by all vectors from self and other.

The returned vector space represents the union of the quantum states represented by self and other.

Parameters:: other – The other vector space.
Returns:: The resulting vector space.
Return type:: VectorSpaceSpan

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_term(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

lattice_terms(*args, **kwargs) → Expression[MatrixEntryGenerator]#: Alias for lattice_term.

Warning

Deprecated: use lattice_term() instead.

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: PlusMinusConvertible) → Expression#

A spin-operator term defined by a Struqture operator.

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

hqs_quantum_solver.spins

Contents

hqs_quantum_solver.spins#