hqs_quantum_solver.protocols

hqs_quantum_solver.protocols#

Definitons of protocol classes to be used throughout the repository.

Classes

`FermionProtocol`(args, *kwargs)	Protocol for fermion definitions.
`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(v: 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 @ v.

Parameters:

v (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 @ v.

Return type:

np.ndarray

dot_add(v: 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 @ v).

Parameters:

v (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(v: 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 @ v. Though transpose returns only a view of a matrix, conjugate returns a copy, hence this method.

Parameters:

v (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 @ v.

Return type:

np.ndarray

rdot(v: ndarray) → ndarray#

Compute the dot product of array with operator.

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

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

rdot_h(v: ndarray) → ndarray#

Compute the dot product of array with operator adjoint.

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

Parameters:: v (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, v @ 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(v: 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 @ v.

Parameters:

v (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 @ v.

Return type:

np.ndarray

dot_add(v: 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 @ v).

Parameters:

v (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 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 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(v: 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 @ v.

Parameters:

v (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 @ v.

Return type:

np.ndarray

dot_add(v: 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 @ v).

Parameters:

v (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(v: 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 @ v. Though transpose returns only a view of a matrix, conjugate returns a copy, hence this method.

Parameters:

v (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 @ v.

Return type:

np.ndarray

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(v: ndarray) → ndarray#

Compute the dot product of array with operator.

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

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

rdot_h(v: ndarray) → ndarray#

Compute the dot product of array with operator adjoint.

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

Parameters:: v (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, v @ 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 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).

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 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(v: 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 @ v.

Parameters:

v (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 @ v.

Return type:

np.ndarray

dot_add(v: 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 @ v).

Parameters:

v (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(v: 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 @ v. Though transpose returns only a view of a matrix, conjugate returns a copy, hence this method.

Parameters:

v (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 @ v.

Return type:

np.ndarray

property mod_N: int#

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

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

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(v: ndarray) → ndarray#

Compute the dot product of array with operator.

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

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

rdot_h(v: ndarray) → ndarray#

Compute the dot product of array with operator adjoint.

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

Parameters:: v (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, v @ 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).

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

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(v: 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 @ v.

Parameters:

v (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 @ v.

Return type:

np.ndarray

dot_add(v: 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 @ v).

Parameters:

v (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(v: 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 @ v. Though transpose returns only a view of a matrix, conjugate returns a copy, hence this method.

Parameters:

v (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 @ v.

Return type:

np.ndarray

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(v: ndarray) → ndarray#

Compute the dot product of array with operator.

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

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

rdot_h(v: ndarray) → ndarray#

Compute the dot product of array with operator adjoint.

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

Parameters:: v (np.ndarray) – The vector/array to dot product with.
Returns:: The result of the dot product, v @ 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, …]

hqs_quantum_solver.protocols

Contents

hqs_quantum_solver.protocols#