hqs_quantum_solver.types

Definitions of Types and TypeVars for use throughout the repository.

class DataType(dtype: Type[float] | Type[complex])

Parent class to hold the dtype property.

This class is not meant to be used on its own, instead it is meant to be inherited from to reduce code duplication for the specific implementations.

Sets the dtype of the operator.

Parameters:

dtype (float_or_complex_type) – The data type of the operator.

__init__(dtype: Type[float] | Type[complex]) → None

Sets the dtype of the operator.

Parameters:

dtype (float_or_complex_type) – The data type of the operator.

property dtype: Type[float] | Type[complex]

The data type of the operator, either float or complex.

Important for determining which kind of algebra is required.

Returns:

The data type of the operator.

Return type:

float_or_complex_type

class SpinInput(M: int, spin_representation: int = 1, Sz: int | None = None, mod_Sz: int = 2, Bx: int | ndarray | None = None, By: int | ndarray | None = None, Bz: int | ndarray | None = None, Jx: int | ndarray | None = None, Jy: int | ndarray | None = None, Jz: int | ndarray | None = None, Jp: int | ndarray | None = None, Jm: int | ndarray | None = None, hJz: ndarray | None = None, hJperp: ndarray | None = None, hJcross: ndarray | None = None, hJd: ndarray | None = None, spin_expression: ExpressionSpinful | None = None, sm: StateMap | None = None, sm_to: StateMap | None = None, enforce_complex: bool = False)

Defines a quantum mechanical operator for a spin system.

The detailed definition of the operator is given in Physics, HQS Lattice Documentation.

M

the number of sites.

Type:

int

spin_representation

the spin representation / spin quantum number, s, in units of ħ/2, i.e. an integer. If not specified it defaults to 1 (i.e. spin-1/2).

Type:

int

Sz

The total spin polarization in the z-axis, Sz, in units of ħ/2. abs(Sz) must be less than or equal to the number of sites times the spin representation, M * spin_representation.

Type:

int | None

mod_Sz

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

Type:

int

Bx

Specifies an explicit additional site-resolved magnetic field in the x-direction if given as array, or instantiates a new array with a 1 at this site. The latter is particularly useful for constructing operators internally.

Defining Bx adds \(\left(- \sum_{j=0}^{M-1} B^x_j \hat{S}^x_j \right)\) to the operator.

Type:

ndarray | int | None

By

Specifies an explicit additional site-resolved magnetic field in the y-direction if given as array, or instantiates a new array with a 1 at this site. The latter is particularly useful for constructing operators internally.

Defining By adds \(\left(- \sum_{j=0}^{M-1} B^y_j \hat{S}^y_j \right)\) to the operator.

Type:

ndarray | int | None

Bz

Specifies an explicit additional site-resolved magnetic field in the z-direction if given as array, or instantiates a new array with a 1 at this site. The latter is particularly useful for constructing operators internally.

Defining Bz adds \(\left(- \sum_{j=0}^{M-1} B^z_j \hat{S}^z_j \right)\) to the operator.

Type:

ndarray | int | None

Jx

Same as Bx but without the Hamiltonian minus sign.

Defining Jx adds \(\left(\sum_{j=0}^{M-1} J^x_j \hat{S}^x_j \right)\) to the operator.

Type:

ndarray | int | None

Jy

Same as By but without the Hamiltonian minus sign.

Defining Jy adds \(\left(\sum_{j=0}^{M-1} J^y_j \hat{S}^y_j \right)\) to the operator.

Type:

ndarray | int | None

Jz

Same as Bz without the Hamiltonian minus sign.

Defining Jz adds \(\left(\sum_{j=0}^{M-1} J^z_j \hat{S}^z_j \right)\) to the operator.

Type:

ndarray | int | None

Jp

Specifies an explicit additional site-resolved S^+ term if given as array, or instantiates a new array with a 1 at this site. The latter is particularly useful for constructing operators internally.

Defining Jp adds \(\left(\sum_{j=0}^{M-1} J^+_j \hat{S}^+_j \right)\) to the operator.

Type:

ndarray | int | None

Jm

Specifies an explicit additional site-resolved S^- term if given as array, or instantiates a new array with a 1 at this site. The latter is particularly useful for constructing operators internally.

Defining Jm adds \(\left(\sum_{j=0}^{M-1} J^-_j \hat{S}^-_j \right)\) to the operator.

Type:

ndarray | int | None

hJz

Array of prefactors for S^z S^z coupling.

Defining hJz adds

\[\sum_{j,k=0}^{M-1} h^{J^z}_{jk} \, \hat{S}^z_j \hat{S}^z_k\]

to the operator.

Type:

ndarray | int | None

hJperp

Array of prefactors for S_perp coupling.

Defining hJperp adds

\[\sum_{j,k=0}^{M-1} h^{J^\perp}_{jk} \, \left( \hat{S}^x_j \hat{S}^x_k + \hat{S}^y_j \hat{S}^y_k \right)\]

to the operator.

Type:

ndarray | None

hJcross

Array of prefactors for S_cross coupling.

Defining hJcross adds

\[\sum_{j,k=0}^{M-1} h^{J^\times}_{jk} \, \mathbf{e}_z \cdot \left( \hat{\mathbf{S}}_j \times \hat{\mathbf{S}}_k \right)\]

to the operator.

Type:

ndarray | None

hJd

Array of prefactors Jd for: Jd (S^+ S^+) + conj(Jd) (S^- S^-).

Defining hJd adds

\[\sum_{j,k=0}^{M-1} h^{J^d}_{jk} \, \hat{S}^+_j \hat{S}^+_k + \left(h^{J^d}_{jk}\right)^* \, \hat{S}^-_k \hat{S}^-_j\]

to the operator.

Type:

ndarray | None

spin_expression

Additional terms given by a spinful expression.

Type:

ExpressionSpinful | None

sm

Map containing initial state space as alternative to quantum numbers. If not provided, will be initialised based on the number of sites.

Type:

StateMap | None

sm_to

Map containing final state space as alternative to quantum numbers. If not provided, will be set to sm after it has been initialised.

Type:

StateMap | None

enforce_complex

Forces the output to be complex even if all inputs are real-valued.

Type:

bool

__init__(M: int, spin_representation: int = 1, Sz: int | None = None, mod_Sz: int = 2, Bx: int | ndarray | None = None, By: int | ndarray | None = None, Bz: int | ndarray | None = None, Jx: int | ndarray | None = None, Jy: int | ndarray | None = None, Jz: int | ndarray | None = None, Jp: int | ndarray | None = None, Jm: int | ndarray | None = None, hJz: ndarray | None = None, hJperp: ndarray | None = None, hJcross: ndarray | None = None, hJd: ndarray | None = None, spin_expression: ExpressionSpinful | None = None, sm: StateMap | None = None, sm_to: StateMap | None = None, enforce_complex: bool = False) → None

check_M_validity() → None

Checks suitability of M.

Raises:

ValueError – If M is less than 1.

check_Sz_validity() → None

Checks Sz input against the number of sites and the spin representation.

The (absolute of the) spin Sz number cannot exceed the number of spins multipled by the spin representation.

Raises:

ValueError – If abs(Sz) exceeds M * spin_representation.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_spin_representation_validity() → None

Checks suitability of the spin representation.

Raises:

ValueError – If the spin representation is not a non-negative integer.

property dtype: Type[float] | Type[complex]

Checks the inputs and returns the data type accordingly.

The operations are as follows:

• enforce_complex makes it complex no matter what.

• By, Jy and hJcross are all explicitly complex terms.

• Remaining terms are not explicitly complex so we check them individually.

Returns:

the dtype of the operator.

Return type:

float_or_complex_type

output_spin_triplets() → triplets

Process the SpinInput into its triplets representation using lattice_functions.

Returns:

The triplets output described by the sanitized inputs.

Return type:

triplets

class SpinInputBase(M: int, spin_representation: int = 1, Sz: int | None = None, mod_Sz: int = 2)

Holds the basic spin system information regardless of implementation.

M

the number of sites.

Type:

int

spin_representation

the spin representation / spin quantum number, s, in units of ħ/2, i.e. an integer. If not specified it defaults to 1 (i.e. spin-1/2).

Type:

int

Sz

The total spin polarization in the z-axis, Sz, in units of ħ/2. abs(Sz) must be less than or equal to the number of sites times the spin representation, M * spin_representation.

Type:

Optional[int]

mod_Sz

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

Type:

int

__init__(M: int, spin_representation: int = 1, Sz: int | None = None, mod_Sz: int = 2) → None

check_M_validity() → None

Checks suitability of M.

Raises:

ValueError – If M is less than 1.

check_Sz_validity() → None

Checks Sz input against the number of sites and the spin representation.

The (absolute of the) spin Sz number cannot exceed the number of spins multipled by the spin representation.

Raises:

ValueError – If abs(Sz) exceeds M * spin_representation.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_spin_representation_validity() → None

Checks suitability of the spin representation.

Raises:

ValueError – If the spin representation is not a non-negative integer.

class SpinfulFermionAnnihilationInput(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, c_i: int | ndarray, up_or_down: str, sm_up: StateMap | None = None, sm_up_to: StateMap | None = None, sm_down: StateMap | None = None, sm_down_to: StateMap | None = None)

An input dataclass typed for annihilation operators for spinless fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of spinful fermions in the system, N.

Type:

int

Sz

The total spin polarization (up - down) in the z-axis, Sz, in units of ħ/2.

Type:

int

mod_N

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

Type:

int

mod_Sz

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

Type:

int

c_i

A vector carry the site-wise coefficients for the annihilation operator or an index specifying which site to create an operator.

Type:

integer_or_array

up_or_down

Whether to annihilate an up or down fermion.

Type:

str

sm_up

The initial state map for up fermions.

Type:

Optional[StateMap]

sm_up_to

The target state map for up fermions.

Type:

Optional[StateMap]

sm_down

The initial state map for down fermions.

Type:

Optional[StateMap]

sm_down_to

The target state map for down fermions.

Type:

Optional[StateMap]

__init__(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, c_i: int | ndarray, up_or_down: str, sm_up: StateMap | None = None, sm_up_to: StateMap | None = None, sm_down: StateMap | None = None, sm_down_to: StateMap | None = None) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 32/64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds twice the number of sites.

check_Sz_validity() → None

Checks Sz input against the number of sites and the number of particles.

If the number of particles is odd/even, then the Sz must also be odd/even, |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Raises:

• ValueError – If parity of Sz does not match that of N

• ValueError – If |Sz| exceeds the allowed number for M, N.

check_mod_N_validity() → None

Checks the suitability of the mod_N input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

property dtype: Type[float] | Type[complex]

Return the dtype based on input.

Returns:

the dtype of the spinful annihilation operator.

Return type:

float_or_complex_type

output_triplets_down_or_dim() → triplets | int

Process SpinfulFermionAnnihilationInput spin-down triplets for lattice_functions.

Returns:

The triplets output described by the sanitized

inputs or an integer to note the size of the identity operator.

Return type:

Union[triplets, int]

Raises:

ValueError – If an up annihilation operator is used and the down spaces are not equal.

output_triplets_up_or_dim() → triplets | int

Process SpinfulFermionAnnihilationInput spin-up triplets for lattice_functions.

Returns:

The triplets output described by the sanitized

inputs or an integer to note the size of the identity operator.

Return type:

Union[triplets, int]

Raises:

ValueError – If a down annihilation operator is used and the up spaces are not equal.

class SpinfulFermionCreationInput(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, cdag_i: int | ndarray, up_or_down: str, sm_up: StateMap | None = None, sm_up_to: StateMap | None = None, sm_down: StateMap | None = None, sm_down_to: StateMap | None = None)

An input dataclass typed for creation operators for spinless fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of spinful fermions in the system, N.

Type:

int

Sz

The total spin polarization (up - down) in the z-axis, Sz, in units of ħ/2.

Type:

int

mod_N

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

Type:

int

mod_Sz

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

Type:

int

cdag_i

A vector carry the site-wise coefficients for the creation operator or an index specifying which site to create an operator.

Type:

integer_or_array

up_or_down

Whether to annihilate an up or down fermion.

Type:

str

sm_up

The initial state map for up fermions.

Type:

Optional[StateMap]

sm_up_to

The target state map for up fermions.

Type:

Optional[StateMap]

sm_down

The initial state map for down fermions.

Type:

Optional[StateMap]

sm_down_to

The target state map for down fermions.

Type:

Optional[StateMap]

__init__(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, cdag_i: int | ndarray, up_or_down: str, sm_up: StateMap | None = None, sm_up_to: StateMap | None = None, sm_down: StateMap | None = None, sm_down_to: StateMap | None = None) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 32/64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds twice the number of sites.

check_Sz_validity() → None

Checks Sz input against the number of sites and the number of particles.

If the number of particles is odd/even, then the Sz must also be odd/even, |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Raises:

• ValueError – If parity of Sz does not match that of N

• ValueError – If |Sz| exceeds the allowed number for M, N.

check_mod_N_validity() → None

Checks the suitability of the mod_N input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

property dtype: Type[float] | Type[complex]

Return the dtype of the spinful fermion creation operator based on input.

Returns:

the dtype of the spinful creation operator.

Return type:

float_or_complex_type

output_triplets_down_or_dim() → triplets | int

Process SpinfulFermionCreationInput spin-down triplets for lattice_functions.

Returns:

The triplets output described by the sanitized

inputs or an integer to note the size of the identity operator.

Return type:

Union[triplets, int]

Raises:

ValueError – If an up creation operator is used and the down spaces are not equal.

output_triplets_up_or_dim() → triplets | int

Process SpinfulFermionCreationInput spin-up triplets for lattice_functions.

Returns:

The triplets output described by the sanitized

inputs or an integer to note the size of the identity operator.

Return type:

Union[triplets, int]

Raises:

ValueError – If a down creation operator is used and the up spaces are not equal.

class SpinfulFermionHamiltonianInput(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, h0_uu: ndarray | None = None, h0_dd: ndarray | None = None, U0: ndarray | float | None = None, V_uu: ndarray | None = None, V_dd: ndarray | None = None, hBCS_uu: ndarray | None = None, hBCS_dd: ndarray | None = None, fermionic_expression: ExpressionSpinful | ExpressionSpinful_complex | None = None, sm_up: StateMap | None = None, sm_down: StateMap | None = None, enforce_complex: bool = False)

Defines a Hamiltonian of a spinful fermion system.

The detailed definition of the Hamiltonian is given in Physics, HQS Lattice Documentation.

M

The number of sites in the system.

Type:

int

N

The number of fermions in the system. Cannot exceed twice the number of sites.

Type:

int

Sz

The total spin polarization (up - down) in the z-axis, Sz, in units of ħ/2.

Type:

int

mod_N

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

Type:

int

mod_Sz

represents the extent of Sz violations allowed (in modular arithmetic).

Type:

int

h0_uu

The “hopping” matrix for the spin-up fermion subspace.

Defining h0_uu adds

\[\sum_{j,k=0}^{M-1} (h_0^\uparrow)_{jk} \; \hat{c}_{\uparrow,j}^\dagger \, \hat{c}_{\uparrow,k}\]

to the Hamiltonian.

Type:

np.ndarray

h0_dd

The “hopping” matrix for the spin-down fermion subspace.

Defining h0_dd adds

\[\sum_{j,k=0}^{M-1} (h_0^\downarrow)_{jk} \; \hat{c}_{\downarrow,j}^\dagger \, \hat{c}_{\downarrow,k}\]

to the Hamiltonian.

Type:

np.ndarray

U0

Onsite Hubbard like interaction strengths.

Defining U0 adds

\[\sum_{j=0}^{M-1} (U_0)_j \, \hat{n}_{\uparrow,j} \hat{n}_{\downarrow,j}\]

to the Hamiltonian.

Type:

np.ndarray | float | None

V_uu

The “interaction” matrix for spin-up fermions. Must be real.

Defining V_uu adds

\[\sum_{j,k=0}^{M-1} V^\uparrow_{jk} \; \left( \hat{n}_{\uparrow,j} - \tfrac12 \middle) \middle( \hat{n}_{\uparrow,k} - \tfrac12 \right)\]

to the Hamiltonian.

Type:

np.ndarray | None

V_dd

The “interaction” matrix for spin-down fermions. Must be real.

\[\sum_{j,k=0}^{M-1} V^\downarrow_{jk} \; \left( \hat{n}_{\downarrow,j} - \tfrac12 \middle) \middle( \hat{n}_{\downarrow,k} - \tfrac12 \right)\]

Type:

np.ndarray | None

hBCS_uu

The “anomalous pairing” matrix for spin-up fermions.

Defining hBCS_uu adds

\[\sum_{j,k=0}^{M-1} (h_\mathrm{BCS}^\uparrow)_{jk} \, \hat{c}_{\uparrow,j} \, \hat{c}_{\uparrow,k} + (h_\mathrm{BCS}^\uparrow)_{kj}^* \, \hat{c}_{\uparrow,k}^\dagger \, \hat{c}_{\uparrow,j}^\dagger\]

to the Hamiltonian.

Type:

np.ndarray | None

hBCS_dd

The “anomalous pairing” matrix for spin-down fermions.

Defining hBCS_dd adds

\[\sum_{j,k=0}^{M-1} (h_\mathrm{BCS}^\downarrow)_{jk} \, \hat{c}_{\downarrow,j} \, \hat{c}_{\downarrow,k} + (h_\mathrm{BCS}^\downarrow)_{kj}^* \, \hat{c}_{\downarrow,k}^\dagger \, \hat{c}_{\downarrow,j}^\dagger\]

to the Hamiltonian.

Type:

np.ndarray | None

fermionic_expression

Fermions description of the Hamiltonian

Type:

ExpressionSpinful | None

sm_up

The initial state map for spin-up fermions.

Type:

StateMap | None

sm_down

The initial state map for spin-down fermions.

Type:

StateMap | None

__init__(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int, h0_uu: ndarray | None = None, h0_dd: ndarray | None = None, U0: ndarray | float | None = None, V_uu: ndarray | None = None, V_dd: ndarray | None = None, hBCS_uu: ndarray | None = None, hBCS_dd: ndarray | None = None, fermionic_expression: ExpressionSpinful | ExpressionSpinful_complex | None = None, sm_up: StateMap | None = None, sm_down: StateMap | None = None, enforce_complex: bool = False) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 32/64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds twice the number of sites.

check_Sz_validity() → None

Checks Sz input against the number of sites and the number of particles.

If the number of particles is odd/even, then the Sz must also be odd/even, |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Raises:

• ValueError – If parity of Sz does not match that of N

• ValueError – If |Sz| exceeds the allowed number for M, N.

check_mod_N_validity() → None

Checks the suitability of the mod_N input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

clear_cached_triplets() → None

Delete the triplets that have been cached during operator instantiation.

property dtype: Type[float] | Type[complex]

Checks the inputs and returns the dtype accordingly.

The operations are as follows:

Enforce complex makes it complex no matter what. If any of the inputs are complex we use complex.

Returns:

the appropriate dtype for the system.

Return type:

float_or_complex_type

output_full_space_diagonal() → ndarray

Matrix entries describing on-site interactions.

Returns:

The triplets describing the matrix.

Return type:

triplets

output_triplets_down() → triplets

Matrix entries describing spin-down-spin-down interactions.

Returns:

The triplets describing the matrix.

Return type:

triplets

output_triplets_full_space() → triplets

Matrix entries describing remaining interactions.

All interactions that are not spin-up spin-up, spin-down spin-down, or on site.

Returns:

The triplets describing the matrix.

Return type:

triplets

output_triplets_up() → triplets

Matrix entries describing spin-up-spin-up interactions.

Returns:

The triplets describing the matrix.

Return type:

triplets

class SpinfulFermionInputBase(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int)

Covers the functionality that is standard of all spinful fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of spinful fermions in the system, N.

Type:

int

Sz

The total spin polarization (up - down) in the z-axis, Sz, in units of ħ/2.

Type:

int

mod_N

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

Type:

int

mod_Sz

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

Type:

int

__init__(M: int, N: int, Sz: int, mod_N: int, mod_Sz: int) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 32/64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds twice the number of sites.

check_Sz_validity() → None

Checks Sz input against the number of sites and the number of particles.

If the number of particles is odd/even, then the Sz must also be odd/even, |Sz| ≤ N for N ≤ M, and |Sz| ≤ 2M - N for N > M.

Raises:

• ValueError – If parity of Sz does not match that of N

• ValueError – If |Sz| exceeds the allowed number for M, N.

check_mod_N_validity() → None

Checks the suitability of the mod_N input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

check_mod_Sz_validity() → None

Checks the suitability of the mod_Sz input.

Raises:

ValueError – If mod_Sz is not a non-negative even integer.

class SpinlessFermionAnnihilationInput(M: int, N: int, mod_N: int, c_i: int | ndarray, sm: StateMap | None = None, sm_to: StateMap | None = None)

An input dataclass typed for annihilation operators for spinless fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of fermions in the system. Cannot exceed the number of sites.

Type:

int

mod_N

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

Type:

int

c_i

A vector carry the site-wise coefficients for the annihilation operator or an index specifying which site to create an operator.

Type:

integer_or_array

sm

The initial state map.

Type:

Optional[StateMap]

sm_to

The target state map.

Type:

Optional[StateMap]

__init__(M: int, N: int, mod_N: int, c_i: int | ndarray, sm: StateMap | None = None, sm_to: StateMap | None = None) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds the number of sites.

check_mod_N_validity() → None

Checks that mod_N, the fermion number violation in modular arithmetic, is suitable.

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

Raises:

ValueError – If mod_N is not a non-negative even integer.

property dtype: Type[float] | Type[complex]

Return the dtype based on input.

Returns:

the dtype of the operator.

Return type:

float_or_complex_type

output_triplets() → triplets

Process the SpinlessFermionInput into its triplets rep using lattice_functions.

Returns:

The triplets output described by the sanitized inputs.

Return type:

triplets

class SpinlessFermionCreationInput(M: int, N: int, mod_N: int, cdag_i: int | ndarray, sm: StateMap | None = None, sm_to: StateMap | None = None)

An input dataclass typed for creation operators for spinless fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of fermions in the system. Cannot exceed the number of sites.

Type:

int

mod_N

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

Type:

int

cdag_i

A vector carry the site-wise coefficients for the creation operator or an index specifying which site to create an operator.

Type:

integer_or_array

sm

The initial state map.

Type:

Optional[StateMap]

sm_to

The target state map.

Type:

Optional[StateMap]

__init__(M: int, N: int, mod_N: int, cdag_i: int | ndarray, sm: StateMap | None = None, sm_to: StateMap | None = None) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds the number of sites.

check_mod_N_validity() → None

Checks that mod_N, the fermion number violation in modular arithmetic, is suitable.

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

Raises:

ValueError – If mod_N is not a non-negative even integer.

property dtype: Type[float] | Type[complex]

Return the dtype based on input.

Returns:

the dtype of the spinless creation operator.

Return type:

float_or_complex_type

output_triplets() → triplets

Process the SpinlessFermionInput into its triplets rep using lattice_functions.

Returns:

The triplets output described by the sanitized inputs.

Return type:

triplets

class SpinlessFermionHamiltonianInput(M: int, N: int, mod_N: int, h0: ndarray, V: ndarray | None = None, hBCS: ndarray | None = None, sm: StateMap | None = None, enforce_complex: bool = False)

Defines a Hamiltonian of a spinless fermion system.

The detailed definition of the Hamiltonian is given in Physics, HQS Lattice Documentation.

M

The number of sites in the system.

Type:

int

N

The number of fermions in the system. Cannot exceed the number of sites.

Type:

int

mod_N

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

Type:

int

h0

The “hopping” matrix. The diagonal elements of \(h_0\) define the vector \(\varepsilon\) from the HQS Lattice Documentation, and the off-diagonal elements the matrix \(t\). In other words, defining the attribute h0 adds

\[\sum_{j,k=0}^{M-1} (h_0)_{jk} \, \hat{c}_j^\dagger \hat{c}_k = \sum_{j\not=k} (h_0)_{jk} \, \hat{c}_j^\dagger \hat{c}_k + \sum_{j=0}^{M-1} (h_0)_{jj} \, \hat{n}_j\]

to the Hamiltonian to be defined.

Type:

np.ndarray

V

The “interaction” matrix. To define the interaction part (defined by the matrix \(U\) in the HQS Lattice Documentation), you should define the upper triangular part of the matrix V. Defining V, adds

\[\sum_{j,k=0}^{M-1} V_{jk}\, \left(\hat{n}_j - \tfrac12\middle) \middle(\hat{n}_k - \tfrac12\right)\]

to the Hamiltonian to be defined.

Type:

np.ndarray

hBCS

The “anomalous pairing” matrix. The upper triangular part of hBSC is the matrix \(D\) from the HQS Lattice Documentation. Defining this matrix adds

\[\sum_{j,k=0}^{M-1} (h_\mathrm{BCS})_{jk} \, \hat{c}_j \hat{c}_k + (h_\mathrm{BCS})_{kj}^* \, \hat{c}_k^\dagger \hat{c}_j^\dagger\]

to the Hamiltonian.

Type:

np.ndarray

sm

The initial state map.

Type:

StateMap | None

__init__(M: int, N: int, mod_N: int, h0: ndarray, V: ndarray | None = None, hBCS: ndarray | None = None, sm: StateMap | None = None, enforce_complex: bool = False) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds the number of sites.

check_V_validity() → None

Checks that V is a valid input.

Raises:

ValueError – If V is not a valid input.

check_mod_N_validity() → None

Checks that mod_N, the fermion number violation in modular arithmetic, is suitable.

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

Raises:

ValueError – If mod_N is not a non-negative even integer.

property dtype: Type[float] | Type[complex]

Checks the inputs and returns the data type accordingly.

The operations are as follows:

Enforce complex makes it complex no matter what. If any of the inputs are complex we use complex.

Returns:

the appropriate dtype for the system.

Return type:

float_or_complex_type

output_triplets() → triplets

Process the SpinlessFermionInput into its triplets rep using lattice_functions.

Returns:

The triplets output described by the sanitized inputs.

Return type:

triplets

class SpinlessFermionInputBase(M: int, N: int, mod_N: int)

Covers the functionality that is standard of all spinless fermion systems.

M

The number of sites in the system.

Type:

int

N

The number of fermions in the system. Cannot exceed the number of sites.

Type:

int

mod_N

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

Type:

int

__init__(M: int, N: int, mod_N: int) → None

check_M_validity() → None

Checks suitability of M, the number of sites.

Raises:

• ValueError – If M is less than 1.

• ValueError – If M is larger than the maximum allowed value, typically 64.

check_N_validity() → None

Checks that N, the number of fermions, is suitable given the other inputs.

Raises:

• ValueError – If N is a negative integer.

• ValueError – If N exceeds the number of sites.

check_mod_N_validity() → None

Checks that mod_N, the fermion number violation in modular arithmetic, is suitable.

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

Raises:

ValueError – If mod_N is not a non-negative even integer.

find_mixed_dtype(left: SupportsDataType, right: SupportsDataType) → Type[float] | Type[complex]

Inspects the two objects to be multiplied and infers their mixed dtype.

Parameters:

• left (SupportsDataType) – The first object to be multiplied.

• right (SupportsDataType) – The second object to be multiplied.

Returns:

The mixed dtype of the two objects.

Return type:

float_or_complex_type