hqs_quantum_solver.protocols

Definitons of protocol classes to be used throughout the repository.

Classes

FermionProtocol	Protocol for fermion definitions.
OperatorInfoProtocol	Information about the spaces an operator is defined on.
OperatorProtocol	Protocol for arbitrary operator definitions.
SimpleOperatorProtocol	Operator providing only basic operations.
SparseMatrixFactory	Requires an operator to be constructable from a list of matrix entries.
SparseMatrixProtocol	Protocol for operators that provide matrix-level operations.
SpinOperatorProtocol	Combined Spin Operator Protocol.
SpinProtocol	Protocol for spin definitions.
SpinfulFermionOperatorProtocol	Combined Spinful Fermion Operator Protocol.
SpinfulFermionProtocol	Protocol for Spinful Fermion definitions.
SpinlessFermionOperatorProtocol	Combined Spinless Fermion Operator Protocol.
SpinlessFermionProtocol	Protocol for Spinless Fermion definitions.
SupportsDataType	Generic type that supports dtype property.
SupportsShape	Generic type that supports shape property.

class FermionProtocol

Protocol for fermion definitions.

This protocol is unlikely to be used directly, instead it serves as a base for both the spinless and spinful fermion protocols.

Warning

This class is deprecated.

property N: int

The number of fermions in the system, N.

Returns:

The number of fermions in the system.

Return type:

int

__init__(*args, **kwargs)

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 non-negative 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.:

(-2 ≡ 2) mod 4 ; (5 ≡ 11) mod 3 ; (0 ≡ 2 ≡ 4) mod 2

Returns:

The modulus of the number of fermions.

Return type:

int

class OperatorProtocol

Protocol for arbitrary operator definitions.

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__(*args, **kwargs)

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.

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]

todense() → ndarray

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

class SimpleOperatorProtocol

Operator providing only basic operations.

In contrast to the OperatorProtocol, this protocol only requires the implementation of the multiplication from the right.

__init__(*args, **kwargs)

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

property dtype: OperatorDType

The type of the scalar elements of the vector space that is acted on.

property shape: Tuple[int, int]

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

Returns:

The shape of the operator.

Return type:

Tuple[int, int]

class SpinOperatorProtocol

Combined Spin Operator Protocol.

Warning

This class is deprecated.

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__(*args, **kwargs)

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.

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

todense() → ndarray

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

class SpinProtocol

Protocol for spin definitions.

Warning

This class is deprecated.

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__(*args, **kwargs)

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

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

class SpinfulFermionOperatorProtocol

Combined Spinful Fermion Operator Protocol.

Warning

This class is deprecated.

property N: int

The number of spinful fermions in the system, N.

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

Returns:

The number of spinful 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__(*args, **kwargs)

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.

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 non-negative 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.:

(-2 ≡ 1) mod 3 ; (6 ≡ 0) mod 3 ; (0 ≡ 2 ≡ 4) mod 2

Returns:

The modulus of the number of fermions.

Return type:

int

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

(-3 ≡ 3) mod 2 ; (7 ≡ 1) 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]

todense() → ndarray

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

class SpinfulFermionProtocol

Protocol for Spinful Fermion definitions.

Unlike spinless fermions, spinful has the extra properties of Sz and mod_Sz for description of its spin degree of freedom.

Warning

This class is deprecated.

property N: int

The number of spinful fermions in the system, N.

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

Returns:

The number of spinful 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__(*args, **kwargs)

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 non-negative 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.:

(-2 ≡ 1) mod 3 ; (6 ≡ 0) mod 3 ; (0 ≡ 2 ≡ 4) mod 2

Returns:

The modulus of the number of fermions.

Return type:

int

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

(-3 ≡ 3) mod 2 ; (7 ≡ 1) mod 2 ; (0 ≡ 2 ≡ 4) mod 2

Returns:

The modulus of the spin polarization.

Return type:

int

class SpinlessFermionOperatorProtocol

Combined Spinless Fermion Operator Protocol.

Warning

This class is deprecated.

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__(*args, **kwargs)

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.

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

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

todense() → ndarray

Return the operator as a dense matrix.

Returns:

The operator as a dense matrix.

Return type:

np.ndarray

class SpinlessFermionProtocol

Protocol for Spinless Fermion definitions.

Warning

This class is deprecated.

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__(*args, **kwargs)

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

(-5 ≡ 13) mod 6 ; (5 ≡ 9) mod 2 ; (0 ≡ 2 ≡ 4) mod 2

Returns:

The modulus of the number of fermions.

Return type:

int

class SupportsDataType

Generic type that supports dtype property.

__init__(*args, **kwargs)

property dtype: Any

Returns the dtype of the object.

Returns:

The data type of the object.

Return type:

Any

class SupportsShape

Generic type that supports shape property.

__init__(*args, **kwargs)

property shape: tuple[int, ...]

Returns the shape tuple of the class.

Returns:

The tuple containing the dimensions of the class.

Return type:

Tuple[int, …]