hqs_quantum_solver.spin_batch

Module for processing multiple total spin-z sectors at once.

Classes

Operator	Operator acting on the state of a spin system.
VectorSpace	Vector space for a spin system for a list of given total spin-z values.

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[MatrixEntryGenerator], *, domain: VectorSpace, codomain: VectorSpace | None = None, dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None = None, operator_type: SparseMatrixFactory | None = None, strict: bool = True) → None

Creates an operator.

Parameters:

• expression (hqs_quantum_solver.spins.Expression) – The expression defining the operator. All expressions from the spins module can be used.

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

eig() → tuple[ndarray, BlockDiagonalOperator]

Compute a dense eigenvalue decomposition for each block.

Requires the operator to be block diagonal.

Returns:

The tuple (eigvals, eigvecs). eigvals contains the eigenvalues of the operator, sorted by total spin-z sector. eigvecs is an operator whose matrix representation are the eigenvectors placed into the columns of the matrix.

Return type:

(ndarray, BlockDiagonalOperator)

eigh() → tuple[ndarray, BlockDiagonalOperator]

Compute a dense eigenvalue decomposition for each block of a hermitian operator.

Requires the operator to be block diagonal and hermitian.

Returns:

The tuple (eigvals, eigvecs). eigvals contains the eigenvalues of the operator, sorted by total spin-z sector and inside a sector sorted by size. eigvecs is an operator whose matrix representation are the eigenvectors placed into the columns of the matrix.

Return type:

(ndarray, BlockDiagonalOperator)

property is_block_diagonal: bool

Indicated whether the operator is block diagonal.

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 VectorSpace

Vector space for a spin system for a list of given total spin-z values.

sites

The number of sites.

Type:

int

total_spin_z

The values of the total spin polarization in z-direction which are represented by this vector space. This value is given in units of \(\hbar/2\).

Type:

list[int]

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

all_occupations() → Iterator[list[int]]

Iterator over all possible occupation configurations.

Returns:

The iterator.

Return type:

Iterator[list[int]]

property dim: int

The dimension of the vector space.

fock_state(occupation: list[int] | list[SpinState], dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None = None) → 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