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

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

expression_terms(*args, **kwargs)

Alias for expression_term.

identity()

The identity operator.

intersite_interaction(coef)

Inter-site interaction terms.

lattice_term(lattice)

Returns the terms corresonding to a Lattice Builder configuration or instance.

lattice_terms(*args, **kwargs)

Alias for lattice_term.

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

Wraps a function into a MatrixEntryGenerator.

EntryBuffer

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

InteractionGenerator

Generates matrix entries for the onsite and intersite interaction.

MatrixEntryGenerator

ABC for a class providing the add_entries method.

Operator

Operator acting on a space representing spinful fermions.

OperatorInfo

The properties of an operator excluding the matrix elements.

VectorSpace

Vector space describing a spinful fermion system.
class Operator#

Operator acting on a space representing spinful fermions.

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: VectorSpace, codomain: VectorSpace | None = None, dtype: DTypeLike | None = None, operator_type: SparseMatrixFactory | 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.

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

Vector space describing a spinful fermion system.

The space is spanned by vectors of the form

\[\prod_{\sigma \in \{ \uparrow, \downarrow \}} \prod_{j=0}^{M-1} (c_{j\sigma}^\dagger)^{n_{j\sigma}} \ket{0} \quad\text{where}\quad n_{j\sigma} \in \{ 0, 1 \},\]

and \(c_{j\sigma}^\dagger\) is the creation operator for site \(j\) and spin polarization \(\sigma\).

The vector space contains all vectors from the set above where the total number of particles with \(\uparrow\) polarization is equal to

\[\left( \texttt{particle_number_offset_up} + k_\uparrow \cdot \texttt{particle_number_stride_up} \right)\]

and the total number of particles with \(\downarrow\) polarization is equal to

\[\left( \texttt{particle_number_offset_down} + k_\downarrow \cdot \texttt{particle_number_stride_down} \right)\]

for some \(k_\uparrow, k_\downarrow \in \mathbb{Z}\).

__init__(*, sites: int, particle_numbers_up: Literal['even', 'odd'] | int | tuple[int, int], particle_numbers_down: 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.

  • particle_numbers_up ("even" | "odd" | int | tuple[int, int]) –

    Restricts the states of the system.

    "even"

    Restricts to states having an even number of particles with “up” polarization.

    "odd"

    Restricts to states having an odd number of particle with “up” polarization.

    int

    Restricts to states that have the the given number of particles with “up”. polarization.

    tuple[int, int]

    Given the tuple (offset, stride) restricts to states that have a particle number with “up” polarization equal to offset plus an integer multiple of stride.

  • particle_numbers_down ("even" | "odd" | int | tuple[int, int]) –

    Restricts the states of the system.

    "even"

    Restricts to states having an even number of particles with “down” polarization.

    "odd"

    Restricts to states having an odd number of particle with “down” polarization.

    int

    Restricts to states that have the the given number of particles with “down”. polarization.

    tuple[int, int]

    Given the tuple (offset, stride) restricts to states that have a particle number with “down” polarization equal to offset plus an integer multiple of 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(*, particle_number_change_up: int = 0, particle_number_change_down: int = 0) → VectorSpace#

Create a modified copy of this vector space.

Parameters:

  • particle_number_change_up (int) – Added to the particle_numbers_up.

  • particle_number_change_down (int) – Added to the particle_numbers_down.

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.

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

Returns an element of the occupancy number basis.

Parameters:

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

  • occupation_down (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(*, space_up: VectorSpace, space_down: VectorSpace) → VectorSpace#

Create a vector space by providing two spinless vector spaces.

Parameters:
classmethod from_total_quantum_numbers(*, sites: int, particle_numbers: int, spin_z: int) → VectorSpace#

Create a vector space from providing total quantum numbers.

Parameters:

  • sites (int) – The number of sites.

  • particle_numbers – Restricts the states of the system to have the given number of particles.

  • spin_z – Restricts the states of the system. Allows only states that have a total spin polarization of spin_z.

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 particle_number_offset_down: int#

The particle number offset of the “down” sector.

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

property particle_number_offset_up: int#

The particle number offset of the “up” sector.

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

property particle_number_stride_down: int#

The particle number stride of the “down” sector.

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

property particle_number_stride_up: int#

The particle number stride of the “up” sector.

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

property sites: int#

The number of sites in the system.

property total_particle_number_offset: int#

The total particle number.

Note

This property can only be accessed if particle_number_stride_up and particle_number_stride_down are zero.

property total_spin_z: int#

The total spin polarization in z-direction.

Note

This property can only be accessed if particle_number_stride_up and particle_number_stride_down are zero.

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

expression_terms(*args, **kwargs) → Expression[MatrixEntryGenerator]#

Alias for expression_term.

Warning

Deprecated: use expression_term() instead.

identity() → Expression[MatrixEntryGenerator]#

The identity operator.

Returns:

Term describing the identity operator.

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

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

Returns the terms corresonding to a Lattice Builder configuration or instance.

Parameters:

lattice (dict | LatticeBuilderInputSpinful | lattice_builder.Builder) – The lattice description.

Returns:

The converted expression.

Return type:

Expression

lattice_terms(*args, **kwargs) → Expression[MatrixEntryGenerator]#

Alias for lattice_term.

Warning

Deprecated: use lattice_term() instead.

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} - \tfrac12) (\hat{n}_{\downarrow j} - \tfrac12) + \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_{j} \, (\hat{n}_{\uparrow j} - \tfrac12) (\hat{n}_{\downarrow j} - \tfrac12)\]

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

Contents