hqs_quantum_solver.protocols

Definitons of protocol classes to be used throughout the repository.

Copyright © 2023-2024 HQS Quantum Simulations GmbH. All Rights Reserved.

Classes

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

class FermionProtocol(*args, **kwargs)

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.

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

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

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

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.

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

Combined Spin Operator Protocol.

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

Protocol for spin definitions.

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

Combined Spinful Fermion Operator Protocol.

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

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.

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

Combined Spinless Fermion Operator Protocol.

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

Protocol for Spinless Fermion definitions.

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

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

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, …]