hqs_quantum_solver.operators

hqs_quantum_solver.operators#

Implementations of operator classes to be used throughout the repository.

Classes

`DyadicOperatorProduct`	DyadicOperator using general operators.
`DyadicOperatorSum`	DyadicOperator using general operators.
`IdentityOperator`	Basic operator that provides the identity operation.
`OperatorEigen`	Generic implementation of operator compatible with Eigen csr matrix types.
`OperatorMKL`	Generic implementation of operator compatible with `sparse_dot_MKL` matrix types.
`OperatorNumpyScipy`	Generic implementation of operator compatible with NumPy/SciPy matrix types.
`SpinOperatorEigen`	SpinOperator using `lattice_functions` backend.
`SpinOperatorMKL`	SpinOperator using SciPy sparse matrices with MKL backend.
`SpinOperatorNumpyScipy`	SpinOperator using SciPy sparse matrices.
`SpinProperties`	Parent class to hold the properties specific to spins.
`SpinfulFermionOperatorEigen`	SpinfulFermionOperator using `lattice_functions` backend.
`SpinfulFermionProperties`	Parent class to hold the properties specific to spinful fermions.
`SpinlessFermionOperatorEigen`	SpinlessFermionOperator using `lattice_functions` backend.
`SpinlessFermionOperatorNumpyScipy`	SpinlessFermionOperator using SciPy backend.
`SpinlessFermionProperties`	Parent class to hold the properties specific to spinless fermions.

class DyadicOperatorProduct#

DyadicOperator using general operators.

For the special case where an operator may be represented by a kronecker product we use the so-called dyadic representation of our system to greatly reduce computational complexity. We do so by operating on the individual spaces individually and reshaping the solutions afterwards, for the user this is all taken care of as if it were the same as the full expression all without ever computing the kronecker product explicitly.

This uses a well-known matrix vectorization trick in reverse, let vec(X) denote the so-called row-major vectorization operator, then: (A ⊗ B) vec(X) = vec(A X B^T).

which is why the second operator must be transposed for this implementation. We use similar such expressions for the other methods available in this operator (such as rdot) however they will not be discussed here.

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__(operator_up: OperatorProtocol, operator_down_transposed: OperatorProtocol) → None#

Take operators and form the composite.

Parameters:

operator_up (OperatorProtocol) – Operator for the up space.
operator_down_transposed (OperatorProtocol) – Operator for the transposed down space.

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

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.

Internally decomposes the dot product into two matrix multiplications of much smaller Hilbert spaces.

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.

Internally decomposes dot_h into two matrix multiplications of much smaller Hilbert spaces.

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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

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.

Internally decomposes rdot into two matrix multiplications of much smaller Hilbert spaces.

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.

Internally decomposes rdot_h into two matrix multiplications of much smaller Hilbert spaces.

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]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, 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 DyadicOperatorSum#

DyadicOperator using general operators.

For the special case where an operator may be represented by a kronecker sum (and a diagonal matrix) we use the so-called dyadic representation of our system to greatly reduce computational complexity. We do so by operating on the individual spaces individually and reforming the solutions afterwards, for the user this is all taken care of as if it were the same as the full expression all without ever computing the kronecker product explicitly.

This uses a well-known matrix vectorization trick in reverse, let vec(X) denote the so-called row-major vectorization operator, then: (A ⊗ B) vec(X) = vec(A X B^T).

i.e., if operator is A ⊕ B = (A ⊗ I_B) + (I_A ⊗ B), then:

vec(A X I_B) = (A ⊗ I_B) vec(X)

vec(I_A X B^T) = (I_A ⊗ B) vec(X)

and therefore:

(A ⊗ I_B + I_A ⊗ B) vec(X) = vec(A X + X B^T)

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__(operator_up: OperatorProtocol, operator_down_transposed: OperatorProtocol, diagonal_matrix: ndarray | None = None, operator_full_space: OperatorProtocol | None = None) → None#

Take operators and form the composite.

Parameters:

operator_up (OperatorProtocol) – Operator for the up space.
operator_down_transposed (OperatorProtocol) – Operator for the transposed down space.
diagonal_matrix (np.ndarray) – Matrix representing the diagonal part of the operator.
operator_full_space (OperatorProtocol) – An operator that acts on the whole space.

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

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. Internally, decomposes dot product into the sum of two matrix multiplications of much smaller Hilbert spaces.

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.

Internally, decomposes dot_h product into the sum of two matrix multiplications.

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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

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. Internally, decomposes rdot product into the sum of two matrix multiplications.

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.

Internally, decomposes rdot_h into the sum of two matrix multiplications.

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]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, 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 IdentityOperator#

Basic operator that provides the identity operation.

This operator allows simple usage of the identity operation. Rather than actually compute the various matrix products explicitly, IdentityOperator computes them by inference.

For brevity, the operator will be denoted by I throughout.

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__(dim: int) → None#

Initialize the identity operator.

Parameters:: dim (int) – The dimension of the identity operator.
Raises:: ValueError – If the dimension is not positive.

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

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

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

When represented by NumPy this operation would be I @ x = x, however in practice no multiplication is actually performed.

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, I @ x = x.

Return type:

np.ndarray

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

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

When represented by NumPy this operation would be: out += z * (I @ x), i.e., out += z * 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 identityᴴ with array; optional out to avoid reallocation.

When represented by NumPy this operation would be I.conj().T @ x = x, however in practice no multiplication is actually performed.

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, I.conj().T @ x = x.

Return type:

np.ndarray

property dtype: OperatorDType#

The data type of the identity operator, float.

The identity is a strictly real operator.

Returns:: The data type of the identity operator.
Return type:: float_or_complex_type

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 identity operator.

When represented by NumPy this operation would be x @ I = x, however in practice no multiplication is actually performed.

Parameters:: x (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, x @ I = x.
Return type:: np.ndarray

rdot_h(x: ndarray) → ndarray#

Compute the dot product of array with adjoint of identity.

When represented by NumPy this operation would be x @ I.conj().T = x, however in practice no multiplication is actually performed.

Parameters:: x (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, x @ I.conj().T = x.
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]#

The shape=(int, int) of the operator.

Returns:: The shape of the identity operator.
Return type:: Tuple[int, int]

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The identity 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 OperatorEigen#

Generic implementation of operator compatible with Eigen csr matrix types.

Note that operators do not need to be Hermitian and may also be rectangular as in the case of spin-raising operators or fermionic creation/annihilation operators.

This interface can be considered the “safe” version of the Eigen interface. All methods and properties are found within the standard csr_matrix_eigen(_c) classes but they provide no checking of dimension/type. If you want to save the extra microseconds from these checks, simply use csr_matrix_eigen(_c) directly.

For brevity, the operator will be denoted by A throughout.

__init__(matrix: _spbase | MatrixEigen) → None#

Take initial matrix and assign it.

Parameters:: matrix (sparse_matrix) – the matrix which we will use as our operator, A.
Returns:: None

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 type of the scalar elements of the vector space that is acted on.

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorEigen#

Create a new operator.

See SparseMatrixFactory.

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class OperatorMKL#

Generic implementation of operator compatible with sparse_dot_MKL matrix types.

Note that operators do not need to be Hermitian and may also be rectangular as in the case of spin-raising operators or fermionic creation/annihilation operators.

We would like to note that sparse_dot_MKL requires C-contiguous data. If an array or vector is passed that is not C-contiguous, then a copy will be made. No copying occurs if the data is properly contiguous.

For brevity, the operator will be denoted by A throughout.

__init__(matrix: MatrixMKL) → None#

Take initial matrix and assign it.

Parameters:: matrix (MatrixMKL) – the matrix which we will use as our operator, A.
Returns:: None
Raises:: TypeError – If the matrix provided is not a sparse CSR, CSC, or BSR matrix.

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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorMKL#

Create a new operator.

See SparseMatrixFactory.

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class OperatorNumpyScipy#

Generic implementation of operator compatible with NumPy/SciPy matrix types.

This class allows for the use of any NumPy/SciPy matrix. For dense representations this means np.ndarray. For sparse representations the following are all supported:

bsr: Block Sparse Row array

coo: A sparse array in COOrdinate format.

csc: Compressed Sparse Column array

csr: Compressed Sparse Row array

dia: Sparse array with DIAgonal storage

dok: Dictionary Of Keys based sparse array.

lil: Row-based LIst of Lists sparse array

However, if using sparse matrices it is recommended that one use CSR, CSC or BSR due to their more efficient multiplication properties in their respective niches.

Note that operators do not need to be Hermitian and may also be rectangular as in the case of spin-raising operators or fermionic creation/annihilation operators.

For brevity, the operator will be denoted by A throughout.

__init__(matrix: MatrixNumpyScipy) → None#

Take initial matrix and assign it.

Parameters:: matrix (MatrixNumpyScipy) – the matrix which we will use as our operator, A.
Returns:: None

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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorNumpyScipy#

Create a new operator.

See SparseMatrixFactory.

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinOperatorEigen#

SpinOperator using lattice_functions backend.

property M: int#: The total number of sites.

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

The spin polarization, fixes the z-component of the total spin. abs(Sz) must be less than or equal to the number of sites times the spin representation, i.e. M * spin_representation.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spin_input: SpinInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spin_input (SpinInput) – The SpinInput (or child class) describing 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 type of the scalar elements of the vector space that is acted on.

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorEigen#

Create a new operator.

See SparseMatrixFactory.

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

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 please specify the input parameter mod_Sz to be a positive even integer. For example, mod_Sz=2 allows eigenstates to be a superposition of states differing by single or multiple spin flips. A value of mod_Sz=0 enforces conservation (even if it is not reasonable).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 9) mod 8  ; (28 ≡ 100) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

property spin_representation: int#

The spin representation a.k.a. spin quantum number, s, in units of ħ/2.

The spin representation governs the spin quantum number, s. In practice, fermions would correspond to half-integers and bosons to full integers, but instead we write our quantum number in units of 1/2 to use the int type.

This means that fermions correspond to odd integers:
1, 3, 5, ... <-> 1/2, 3/2, 5/2, ...

and that bosons correspond to even integers:
0, 2, 4, 6, ... <-> 0, 1, 2, 3, ...

Returns:: The spin representation / spin quantum number, s.
Return type:: int

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinOperatorMKL#

SpinOperator using SciPy sparse matrices with MKL backend.

property M: int#: The total number of sites.

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

The spin polarization, fixes the z-component of the total spin. abs(Sz) must be less than or equal to the number of sites times the spin representation, i.e. M * spin_representation.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spin_input: SpinInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spin_input (SpinInput) – The SpinInput describing 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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorMKL#

Create a new operator.

See SparseMatrixFactory.

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 9) mod 8  ; (28 ≡ 100) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

property spin_representation: int#

The spin representation a.k.a. spin quantum number, s, in units of ħ/2.

This means that fermions correspond to odd integers:
1, 3, 5, ... <-> 1/2, 3/2, 5/2, ...

and that bosons correspond to even integers:
0, 2, 4, 6, ... <-> 0, 1, 2, 3, ...

Returns:: The spin representation / spin quantum number, s.
Return type:: int

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinOperatorNumpyScipy#

SpinOperator using SciPy sparse matrices.

property M: int#: The total number of sites.

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

The spin polarization, fixes the z-component of the total spin. abs(Sz) must be less than or equal to the number of sites times the spin representation, i.e. M * spin_representation.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spin_input: SpinInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spin_input (SpinInput) – The SpinInput describing 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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorNumpyScipy#

Create a new operator.

See SparseMatrixFactory.

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 9) mod 8  ; (28 ≡ 100) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

property spin_representation: int#

The spin representation a.k.a. spin quantum number, s, in units of ħ/2.

This means that fermions correspond to odd integers:
1, 3, 5, ... <-> 1/2, 3/2, 5/2, ...

and that bosons correspond to even integers:
0, 2, 4, 6, ... <-> 0, 1, 2, 3, ...

Returns:: The spin representation / spin quantum number, s.
Return type:: int

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinProperties#

Parent class to hold the properties specific to spins.

This class is not meant to be used on its own, instead it is meant to be inherited from to reduce code duplication for the specific spin operator implementations. It does not check the validity of the inputs. It merely takes in the spin representation, Sz, and mod_Sz as parameters and exposes them as properties.

As this is for solely internal development purposes, it is hidden from the API docs.

property M: int#: The total number of sites.

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

The spin polarization, fixes the z-component of the total spin. abs(Sz) must be less than or equal to the number of sites times the spin representation, i.e. M * spin_representation.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spin_input: SpinInputBase) → None#

Take initial spin_input and extract the relevant properties.

Parameters:: spin_input (SpinInputBase) – The spin input.

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 9) mod 8  ; (28 ≡ 100) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

property spin_representation: int#

The spin representation a.k.a. spin quantum number, s, in units of ħ/2.

This means that fermions correspond to odd integers:
1, 3, 5, ... <-> 1/2, 3/2, 5/2, ...

and that bosons correspond to even integers:
0, 2, 4, 6, ... <-> 0, 1, 2, 3, ...

Returns:: The spin representation / spin quantum number, s.
Return type:: int

class SpinfulFermionOperatorEigen#

SpinfulFermionOperator using lattice_functions backend.

Special spinful fermion operator class for the case of Hubbard interaction with no spin-orbit coupling, i.e. the special case where h_ud = h_du = 0.

Because the only extra contribution between the different spin degrees of freedom occurs solely on the diagonal of the Hamiltonian, we can instead partition the individual spin spaces and the diagonal into three separate terms and sum their contributions to form the total solution. Greatly outperforming the more general kronecker-product space significantly.

property N: int#

The number of spinful fermions in the system, N.

For spinful fermions, N must be less or equal to twice the total number of sites.

Returns:: The number of spinful fermions in the system.
Return type:: int

property N_down: int#

Number of spin-down fermions, a derived property from (N - Sz) / 2.

Returns:: The number of spin-down fermions in the system.
Return type:: int

property N_up: int#

Number of spin-up fermions, a derived property from (N + Sz) / 2.

Returns:: The number of spin-up fermions in the system.
Return type:: int

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

Fixes the z-component of the total spin. For M sites and N fermions, it must satisfy |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spinful_fermion_input: SpinfulFermionAnnihilationInput | SpinfulFermionCreationInput | SpinfulFermionHamiltonianInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spinful_fermion_input (SpinfulFermionInput) – The spinful fermion input describing the operator.
Raises:: ValueError – if the component operators are not defined correctly.

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.

property mod_N: int#

Integer representing the extent of N violations allowed (in modular arithmetic).

In the presence of (for example) anomalous pairing, N is no longer a good quantum number. In order to allow for states to break this symmetry please specify the input parameter mod_N to be a positive even integer, typically mod_N = 2. A value of mod_N = 0 enforces conservation (even if it is not reasonable).

mod here stands for modular arithmetic, e.g.:
(3 ≡ -1) mod 4  ; (5 ≡ 1) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the number of spinful fermions.
Return type:: int

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 11) mod 2  ; (-3 ≡ 5) mod 4  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

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

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

class SpinfulFermionProperties#

Parent class to hold the properties specific to spinful fermions.

This class is not meant to be used on its own, instead it is meant to be inherited from to reduce code duplication for the specific spinful fermion operator implementations. It does not check the validity of the inputs. It merely takes in the SpinfulFermionInput and exposes them as properties.

As this is for solely internal development purposes, it is hidden from the API docs.

property N: int#

The number of spinful fermions in the system, N.

For spinful fermions, N must be less or equal to twice the total number of sites.

Returns:: The number of spinful fermions in the system.
Return type:: int

property N_down: int#

Number of spin-down fermions, a derived property from (N - Sz) / 2.

Returns:: The number of spin-down fermions in the system.
Return type:: int

property N_up: int#

Number of spin-up fermions, a derived property from (N + Sz) / 2.

Returns:: The number of spin-up fermions in the system.
Return type:: int

property Sz: int#

The total spin polarization in the z-axis, Sz, in units of ħ/2.

Fixes the z-component of the total spin. For M sites and N fermions, it must satisfy |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Returns:: The total spin polarization multiplied by 2/ħ.
Return type:: int

__init__(spinful_fermion_input: SpinfulFermionInputBase) → None#

Take initial spin_input and extract the relevant properties.

Parameters:: spinful_fermion_input (SpinfulFermionInputBase) – The SpinfulFermionInputBase (or child class) describing the operator.

property mod_N: int#

Integer representing the extent of N violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(3 ≡ -1) mod 4  ; (5 ≡ 1) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the number of spinful fermions.
Return type:: int

property mod_Sz: int#

Integer representing the extent of Sz violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(1 ≡ 11) mod 2  ; (-3 ≡ 5) mod 4  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the spin polarization.
Return type:: int

class SpinlessFermionOperatorEigen#

SpinlessFermionOperator using lattice_functions backend.

property N: int#

The number of spinless fermions in the system, N.

For spinless fermions, N must be less or equal to the total number of sites.

Returns:: The number of spinless fermions in the system.
Return type:: int

__init__(spinless_fermion_input: SpinlessFermionAnnihilationInput | SpinlessFermionCreationInput | SpinlessFermionHamiltonianInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spinless_fermion_input (SpinlessFermionInput) – The SpinlessFermionInput describing 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 type of the scalar elements of the vector space that is acted on.

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorEigen#

Create a new operator.

See SparseMatrixFactory.

property mod_N: int#

Integer representing the extent of N violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(-5 ≡ 13) mod 6  ; (5 ≡ 9) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the number of fermions.
Return type:: int

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinlessFermionOperatorNumpyScipy#

SpinlessFermionOperator using SciPy backend.

property N: int#

The number of spinless fermions in the system, N.

For spinless fermions, N must be less or equal to the total number of sites.

Returns:: The number of spinless fermions in the system.
Return type:: int

__init__(spinless_fermion_input: SpinlessFermionAnnihilationInput | SpinlessFermionCreationInput | SpinlessFermionHamiltonianInput) → None#

Take initial spin_input and assign the operator based on it.

Parameters:: spinless_fermion_input (SpinlessFermionInput) – The SpinlessFermionInput describing 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 data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:: The data type of the operator.
Return type:: float_or_complex_type

static from_entries(entries: TripletList | MatrixEntryVectors, shape: tuple[int, int], dtype: DTypeLike) → OperatorNumpyScipy#

Create a new operator.

See SparseMatrixFactory.

property mod_N: int#

Integer representing the extent of N violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(-5 ≡ 13) mod 6  ; (5 ≡ 9) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the number of fermions.
Return type:: int

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

property shape: Tuple[int, int]#

The shape=(int, int) of the operator.

Returns:: The shape of the operator.
Return type:: Tuple[int, int]

tocsr() → csr_array#

Convert the operator to a csr_array.

See SparseMatrixProtocol.

todense() → ndarray#

Return the operator as a dense matrix.

Returns:: The operator as a dense matrix.
Return type:: np.ndarray

class SpinlessFermionProperties#

Parent class to hold the properties specific to spinless fermions.

This class is not meant to be used on its own, instead it is meant to be inherited from to reduce code duplication for the specific spinless fermion operator implementations. It does not check the validity of the inputs. It merely takes in the SpinlessFermionInput and exposes them as properties.

As this is for solely internal development purposes, it is hidden from the API docs.

property N: int#

The number of spinless fermions in the system, N.

For spinless fermions, N must be less or equal to the total number of sites.

Returns:: The number of spinless fermions in the system.
Return type:: int

__init__(spinless_fermion_input: SpinlessFermionInputBase) → None#

Take initial spin_input and extract the relevant properties.

Parameters:: spinless_fermion_input (SpinlessFermionInputBase) – The SpinlessFermionInputBase (or child class) describing the operator.

property mod_N: int#

Integer representing the extent of N violations allowed (in modular arithmetic).

mod here stands for modular arithmetic, e.g.:
(-5 ≡ 13) mod 6  ; (5 ≡ 9) mod 2  ; (0 ≡ 2 ≡ 4) mod 2

Returns:: The modulus of the number of fermions.
Return type:: int

hqs_quantum_solver.operators

Contents

hqs_quantum_solver.operators#