hqs_quantum_solver.spinful_fermions

hqs_quantum_solver.spinful_fermions#

Operators for spinful fermions.

Functions

down(down_expression)

Applies a spinless operator only to the "down" sector.

expression_terms(fermionic_expression)

A spinful-fermion operator term given by a ExpressionSpinful object.

intersite_interaction(coef)

Inter-site interaction terms.

onsite_and_intersite_interaction(coef)

On-site and inter-site interaction terms.

onsite_interaction(coef)

On-site interaction terms.

up(up_expression)

Applies a spinless operator only to the "up" sector.

Classes

EntriesFromFunction(fun, dtype)

Wraps a function into a MatrixEntryGenerator.

EntryBuffer(*, up_expression, ...)

Storage for the matrix entries of an operator in-construction.

MatrixEntryGenerator()

ABC for a class providing the add_entries method.

Operator(*args, **kwargs)

Operator acting on a space representing spinful fermions.

OperatorInfo(*, domain, codomain, dtype)

The properties of an operator excluding the matrix elements.

VectorSpace(*, sites, up_particle_numbers, ...)

Vector space describing a spinful fermion system.
class Operator(*args, **kwargs)#

Operator acting on a space representing spinful fermions.

Creates the operator.

Parameters:

  • expression (Expression) – The operator expression to build.

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

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

  • dtype (DTypeLike | None) – When given, forces the dtype of the operator.

  • operator_type (OperatorFactory | None) – The operator backend.

property H#

Hermitian adjoint.

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

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

Returns:

A_H – Hermitian adjoint of self.

Return type:

LinearOperator

property T#

Transpose this linear operator.

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

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

Creates the operator.

Parameters:

  • expression (Expression) – The operator expression to build.

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

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

  • dtype (DTypeLike | None) – When given, forces the dtype of the operator.

  • operator_type (OperatorFactory | None) – The operator backend.

adjoint()#

Hermitian adjoint.

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

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

Returns:

A_H – Hermitian adjoint of self.

Return type:

LinearOperator

property codomain: VectorSpace#

The codomain of the operator.

property domain: VectorSpace#

The domain of the operator.

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

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

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

Parameters:

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

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

Returns:

The result of the dot product, A @ x.

Return type:

np.ndarray

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

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

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

Parameters:

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

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

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

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

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

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

Parameters:

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

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

Returns:

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

Return type:

np.ndarray

property dtype: OperatorDType#

The NumPy dtype.

matmat(X)#

Matrix-matrix multiplication.

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

Parameters:

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

Returns:

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

Return type:

{matrix, ndarray}

Notes

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

matvec(x)#

Matrix-vector multiplication.

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

Parameters:

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

Returns:

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

Return type:

{matrix, ndarray}

Notes

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

rdot(x: ndarray) → ndarray#

Compute the dot product of array with operator.

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

Parameters:

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

Returns:

The result of the dot product, x @ A.

Return type:

np.ndarray

rdot_h(x: ndarray) → ndarray#

Compute the dot product of array with operator adjoint.

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

Parameters:

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

Returns:

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

Return type:

np.ndarray

rmatmat(X)#

Adjoint matrix-matrix multiplication.

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

Parameters:

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

Returns:

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

Return type:

{matrix, ndarray}

Notes

This rmatmat wraps the user-specified rmatmat routine.

rmatvec(x)#

Adjoint matrix-vector multiplication.

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

Parameters:

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

Returns:

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

Return type:

{matrix, ndarray}

Notes

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

property shape: tuple[int, int]#

Returns the shape tuple of the class.

Returns:

The tuple containing the dimensions of the class.

Return type:

Tuple[int, …]

todense() → ndarray#

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

transpose()#

Transpose this linear operator.

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

class VectorSpace(*, sites: int, up_particle_numbers: Literal['even', 'odd'] | int | tuple[int, int], down_particle_numbers: Literal['even', 'odd'] | int | tuple[int, int])#

Vector space describing a spinful fermion system.

Create the vector space.

Note

From the set of allowed particle numbers only the physically relevant will be used.

Parameters:

  • sites (int) – The number of sites in the system.

  • up_particle_numbers ("even" | "odd" | int | tuple[int, int]) – The allowed particle numbers in the “up” sector. Set to “even” and “odd” allows for all even and odd particle numbers, respectively. Set to an integer allows only this particular particle number. Set to a tuple, defines the offset and the stride.

  • down_particle_numbers ("even" | "odd" | int | tuple[int, int]) – The allowed particle numbers in the “down” sector. Set to “even” and “odd” allows for all even and odd particle numbers, respectively. Set to an integer allows only this particular particle number. Set to a tuple, defines the offset and the stride.

__init__(*, sites: int, up_particle_numbers: Literal['even', 'odd'] | int | tuple[int, int], down_particle_numbers: Literal['even', 'odd'] | int | tuple[int, int]) → None#

Create the vector space.

Note

From the set of allowed particle numbers only the physically relevant will be used.

Parameters:

  • sites (int) – The number of sites in the system.

  • up_particle_numbers ("even" | "odd" | int | tuple[int, int]) – The allowed particle numbers in the “up” sector. Set to “even” and “odd” allows for all even and odd particle numbers, respectively. Set to an integer allows only this particular particle number. Set to a tuple, defines the offset and the stride.

  • down_particle_numbers ("even" | "odd" | int | tuple[int, int]) – The allowed particle numbers in the “down” sector. Set to “even” and “odd” allows for all even and odd particle numbers, respectively. Set to an integer allows only this particular particle number. Set to a tuple, defines the offset and the stride.

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

Iterator over all possible occupation configurations.

Returns:

The iterator.

Return type:

Iterator[tuple[list[int], list[int]]]

copy(*, up_particle_number_change: int = 0, down_particle_number_change: int = 0) → VectorSpace#

Create a modified copy of this vector space.

Parameters:

  • up_particle_number_change (int) – Added to the up_particle_numbers.

  • down_particle_number_change (int) – Added to the down_particle_numbers.

Returns:

The modified copy.

Return type:

VectorSpace

property dim: int#

The dimension of the vector space.

property dim_down: int#

The dimension of the “down” sector alone.

property dim_up: int#

The dimension of the “up” sector alone.

property down_particle_number_offset: int#

The particle number offset of the “down” sector.

Together with down_particle_number_stride, defines the set of allowed particle numbers in the “down” sector. The allowed particle numbers are down_particle_number_offset plus any multiple of down_particle_number_stride.

property down_particle_number_stride: int#

The particle number stride of the “down” sector.

Together with particle_number_offset, defines the set of allowed particle numbers in the “down” sector. The allowed particle numbers are down_particle_number_offset plus any multiple of down_particle_number_stride.

fock_state(up_occupation: list[int], down_occupation: list[int], dtype: DTypeLike = None) → np.ndarray#

Returns an element of the occupancy number basis.

Parameters:

  • up_occupation (list[int]) – The occupation number per site in the “up” sector.

  • down_occupation (list[int]) – The occupation number per site in the “down” sector.

  • dtype (DTypeLike) – The datatype of the returned array.

Returns:

The state vector.

Return type:

ndarray

classmethod from_spinless_vector_spaces(*, up_space: VectorSpace, down_space: VectorSpace) → VectorSpace#

Create a vector space by providing two spinless vector spaces.

Parameters:
classmethod from_total_quantum_numbers(*, sites: int, particle_numbers: Literal['even', 'odd'] | int | tuple[int, int], spin_z: int) → VectorSpace#

Create a vector space from providing total quantum numbers.

Parameters:

  • sites (int) – The number of sites.

  • particle_numbers ("even" | "odd" | int | tuple[int, int]) – The allowed total particle number. Set to “even” and “odd” allows for all even and odd particle numbers, respectively. Set to an integer allows only this particular particle number. Set to a tuple, defines the offset and the stride.

  • spin_z – The total spin polarization in z-direction.

Returns:

The constructed vector space.

Return type:

VectorSpace

occupation(fock_state: ndarray, *, decimal: int = 7) → tuple[int, list[int], list[int]]#

Given a fock state, returns the corresponding occupations.

Parameters:

  • fock_state (ndarray) – The state vector.

  • decimal (int) – The number of decimal places that the argument has to agree with a fock state.

Returns:

The sign, the occupation of

the up sector, and the occupation of the down sector, respectively.

Return type:

tuple[int, list[int], list[int]]

property sites: int#

The number of sites in the system.

property total_particle_number_offset: int#

The stride of the allowed total particle numbers.

Together with total_particle_number_stride specifies the possible values of the total number of fermions in the system. The possible values are total_particle_number_offset plus any multiple of total_particle_number_stride.

property total_particle_number_stride: int#

The offset of the allowed total particle numbers.

Together with total_particle_number_offset specifies the possible values of the total number of fermions in the system. The possible values are total_particle_number_offset plus any multiple of total_particle_number_stride.

property total_spin_z: int#

The total spin polarization in z-direction.

Note

This value is only exact when total_particle_number_stride is zero. Otherwise the total spin polarization is only defined modulo total_particle_number_stride.

property up_particle_number_offset: int#

The particle number offset of the “up” sector.

Together with up_particle_number_stride, defines the set of allowed particle numbers in the “up” sector. The allowed particle numbers are up_particle_number_offset plus any multiple of up_particle_number_stride.

property up_particle_number_stride: int#

The particle number stride of the “up” sector.

Together with particle_number_offset, defines the set of allowed particle numbers in the “up” sector. The allowed particle numbers are up_particle_number_offset plus any multiple of up_particle_number_stride.

down(down_expression: Expression[MatrixEntryGenerator]) → Expression[MatrixEntryGenerator]#

Applies a spinless operator only to the “down” sector.

Defines the term \(I \otimes \Omega\), where \(\Omega\) is the given operator.

Parameters:

down_expression – Defines \(\Omega\).

Returns:

The operator expression.

Return type:

Expression

expression_terms(fermionic_expression: ExpressionSpinful | ExpressionSpinful_complex) → Expression[MatrixEntryGenerator]#

A spinful-fermion operator term given by a ExpressionSpinful object.

Parameters:

fermionic_expression (ExpressionSpinful) – The Lattice Function expression.

Returns:

The converted expression.

Return type:

(Expression)

intersite_interaction(coef: ndarray) → Expression[MatrixEntryGenerator]#

Inter-site interaction terms.

Defines the term

\[\begin{split}\sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} U_{jk} \, (\hat{n}_{\uparrow j} + \hat{n}_{\downarrow j}) \, (\hat{n}_{\uparrow k} + \hat{n}_{\downarrow k}) \,,\end{split}\]

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

Note

This function expects the diagonal of \(U\) to be zero.

Parameters:

coef (ndarray) – The coefficients.

Returns:

The operator expression.

Return type:

Expression

onsite_and_intersite_interaction(coef: ndarray) → Expression[MatrixEntryGenerator]#

On-site and inter-site interaction terms.

Defines the term

\[\begin{split}\sum_{j=0}^{M-1} U_{jj} \, (\hat{n}_{\uparrow j} - 1/2) (\hat{n}_{\downarrow j} - 1/2) + \sum_{\substack{j,k=0 \\ j \not= k}}^{M-1} U_{jk} \, (\hat{n}_{\uparrow j} + \hat{n}_{\downarrow j}) \, (\hat{n}_{\uparrow k} + \hat{n}_{\downarrow k}) \,,\end{split}\]

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

Parameters:

coef (ndarray) – The coefficients.

Returns:

The operator expression.

Return type:

Expression

onsite_interaction(coef: ndarray) → Expression[MatrixEntryGenerator]#

On-site interaction terms.

Defines the term

\[\sum_{j=0}^{M-1} U_{jj} \, (\hat{n}_{\uparrow j} - 1/2) (\hat{n}_{\downarrow j} - 1/2)\]

where \(U_{j}\) are the given coefficients.

Parameters:

coef (ndarray) – The coefficients.

Returns:

The operator expression.

Return type:

Expression

up(up_expression: Expression[MatrixEntryGenerator]) → Expression[MatrixEntryGenerator]#

Applies a spinless operator only to the “up” sector.

Defines the term \(\Omega \otimes I\), where \(\Omega\) is the given operator.

Parameters:

up_expression – Defines \(\Omega\).

Returns:

The operator expression.

Return type:

Expression