hqs_spin_mapper.transformables

Module containing the provided transformable objects for the HQS Spin Mapper.

Classes

SpinFinder(rdm1, rdm2[, tolerance, ...])

Data object for use in a spin determination calculation.

Transformable()

Base Transformable class to avoid code duplication between the transformables.

Transformable_LatticeBuilder(builder[, ...])

Transformable system from a LatticeBuilder input.

Transformable_Matrices(hamiltonians[, ...])

Transformable system from input matrices for the Hamiltonian.

Transformable_QuantumChemistry(hamiltonians, ...)

Transformable system from an electronic structure calculation input.

Transformable_Struqture(system[, ...])

Transformable system from a LatticeBuilder input.
class hqs_spin_mapper.transformables.Transformable

Base Transformable class to avoid code duplication between the transformables.

Construct empty base class (variables specified for linting purposes only!).

__init__() → None

Construct empty base class (variables specified for linting purposes only!).

property hamiltonians: Hamiltonian_Matrices

Return the matrix descriptions of the terms in the system Hamiltonian.

Returns:

The stored Hamiltonian matrices

Return type:

Hamiltonian_Matrices

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property site_type: str

Return the type of orbitals (e.g. spinful_fermions or spinless_fermions).

Returns:

The type of the system sites

Return type:

str

property prefactor_cutoff: float

Return the cutoff for the prefactors of terms to be considered in the transformation.

Returns:

The cutoff below which terms are dropped for the transformation

Return type:

float

property generator: ExpressionSpinful | ExpressionSpinful_complex

Return the generator \(S\) of the Schrieffer-Wolff transformation.

Returns:

The generator of the Schrieffer-Wolff transformation

Return type:

Union[ExpressionSpinful, ExpressionSpinfulComplex]

property transformed_hamiltonian: ExpressionSpinful | ExpressionSpinful_complex

Return the Schrieffer-Wolff transformed Hamiltonian \(\tilde{H}\).

Returns:

The transformed Hamiltonian

Return type:

Union[ExpressionSpinful, ExpressionSpinful_complex]

_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
class hqs_spin_mapper.transformables.Transformable_Matrices(hamiltonians: Hamiltonian_Matrices, system_size: int | None = None, rotation_matrix: ndarray | None = None, prefactor_cutoff: float = 1e-06, site_type: str = 'spinful_fermions', spin_indices: Set[int] | None = None)

Transformable system from input matrices for the Hamiltonian.

Construct the transformable system obtained from a matrix collection input.

Parameters:

  • hamiltonians (Hamiltonian_Matrices) – Collection of matrix descriptions of the system

  • Hamiltonian

  • system_size (int) – Number of orbitals in the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • site_type (str) – Type of excitations in the orbitals.

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

__init__(hamiltonians: Hamiltonian_Matrices, system_size: int | None = None, rotation_matrix: ndarray | None = None, prefactor_cutoff: float = 1e-06, site_type: str = 'spinful_fermions', spin_indices: Set[int] | None = None) → None

Construct the transformable system obtained from a matrix collection input.

Parameters:

  • hamiltonians (Hamiltonian_Matrices) – Collection of matrix descriptions of the system

  • Hamiltonian

  • system_size (int) – Number of orbitals in the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • site_type (str) – Type of excitations in the orbitals.

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

_spin_indices: Set[int]
_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
property generator: ExpressionSpinful | ExpressionSpinful_complex

Return the generator \(S\) of the Schrieffer-Wolff transformation.

Returns:

The generator of the Schrieffer-Wolff transformation

Return type:

Union[ExpressionSpinful, ExpressionSpinfulComplex]

property hamiltonians: Hamiltonian_Matrices

Return the matrix descriptions of the terms in the system Hamiltonian.

Returns:

The stored Hamiltonian matrices

Return type:

Hamiltonian_Matrices

property prefactor_cutoff: float

Return the cutoff for the prefactors of terms to be considered in the transformation.

Returns:

The cutoff below which terms are dropped for the transformation

Return type:

float

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property site_type: str

Return the type of orbitals (e.g. spinful_fermions or spinless_fermions).

Returns:

The type of the system sites

Return type:

str

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property transformed_hamiltonian: ExpressionSpinful | ExpressionSpinful_complex

Return the Schrieffer-Wolff transformed Hamiltonian \(\tilde{H}\).

Returns:

The transformed Hamiltonian

Return type:

Union[ExpressionSpinful, ExpressionSpinful_complex]

class hqs_spin_mapper.transformables.Transformable_Struqture(system: FermionHamiltonian, prefactor_cutoff: float = 1e-06, spin_indices: Set[int] | None = None)

Transformable system from a LatticeBuilder input.

Construct the transformable system obtained from a Struqture input.

Parameters:

  • system (FermionHamiltonian) – Fermionic input Hamiltonian as struqture2 object

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

ValueError – Struqture incompatible with HQS Spin Mapper

__init__(system: FermionHamiltonian, prefactor_cutoff: float = 1e-06, spin_indices: Set[int] | None = None) → None

Construct the transformable system obtained from a Struqture input.

Parameters:

  • system (FermionHamiltonian) – Fermionic input Hamiltonian as struqture2 object

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

ValueError – Struqture incompatible with HQS Spin Mapper

_spin_indices: Set[int]
_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
property generator: ExpressionSpinful | ExpressionSpinful_complex

Return the generator \(S\) of the Schrieffer-Wolff transformation.

Returns:

The generator of the Schrieffer-Wolff transformation

Return type:

Union[ExpressionSpinful, ExpressionSpinfulComplex]

property hamiltonians: Hamiltonian_Matrices

Return the matrix descriptions of the terms in the system Hamiltonian.

Returns:

The stored Hamiltonian matrices

Return type:

Hamiltonian_Matrices

property prefactor_cutoff: float

Return the cutoff for the prefactors of terms to be considered in the transformation.

Returns:

The cutoff below which terms are dropped for the transformation

Return type:

float

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property site_type: str

Return the type of orbitals (e.g. spinful_fermions or spinless_fermions).

Returns:

The type of the system sites

Return type:

str

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property transformed_hamiltonian: ExpressionSpinful | ExpressionSpinful_complex

Return the Schrieffer-Wolff transformed Hamiltonian \(\tilde{H}\).

Returns:

The transformed Hamiltonian

Return type:

Union[ExpressionSpinful, ExpressionSpinful_complex]

class hqs_spin_mapper.transformables.Transformable_LatticeBuilder(builder: Builder | str, rotation_matrix: ndarray | None = None, prefactor_cutoff: float = 1e-06, spin_indices: Set[int] | None = None)

Transformable system from a LatticeBuilder input.

Construct the transformable system obtained from a LatticeBuilder input.

Parameters:

  • builder (Union[Builder, str]) – LatticeBuilder input describing the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

  • AssertionError – Input is not conforming to lattice validator requirements.

  • TypeError – The type of the input is incorrect.

__init__(builder: Builder | str, rotation_matrix: ndarray | None = None, prefactor_cutoff: float = 1e-06, spin_indices: Set[int] | None = None) → None

Construct the transformable system obtained from a LatticeBuilder input.

Parameters:

  • builder (Union[Builder, str]) – LatticeBuilder input describing the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

  • AssertionError – Input is not conforming to lattice validator requirements.

  • TypeError – The type of the input is incorrect.

_spin_indices: Set[int]
property particle_hole_symmetry_shift: float

Return the constant energy shift due to the particle-hole symetry of the interaction.

Returns:

The the value of the constant energy shift

Return type:

float

_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
property generator: ExpressionSpinful | ExpressionSpinful_complex

Return the generator \(S\) of the Schrieffer-Wolff transformation.

Returns:

The generator of the Schrieffer-Wolff transformation

Return type:

Union[ExpressionSpinful, ExpressionSpinfulComplex]

property hamiltonians: Hamiltonian_Matrices

Return the matrix descriptions of the terms in the system Hamiltonian.

Returns:

The stored Hamiltonian matrices

Return type:

Hamiltonian_Matrices

property prefactor_cutoff: float

Return the cutoff for the prefactors of terms to be considered in the transformation.

Returns:

The cutoff below which terms are dropped for the transformation

Return type:

float

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property site_type: str

Return the type of orbitals (e.g. spinful_fermions or spinless_fermions).

Returns:

The type of the system sites

Return type:

str

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property transformed_hamiltonian: ExpressionSpinful | ExpressionSpinful_complex

Return the Schrieffer-Wolff transformed Hamiltonian \(\tilde{H}\).

Returns:

The transformed Hamiltonian

Return type:

Union[ExpressionSpinful, ExpressionSpinful_complex]

class hqs_spin_mapper.transformables.Transformable_QuantumChemistry(hamiltonians: Hamiltonian_Matrices, rdm1: ndarray | Tuple[ndarray, ...], rdm2: ndarray, system_size: int | None = None, rotation_matrix: ndarray | None = None, tolerance: float = 0.1, prefactor_cutoff: float = 1e-06, optimization_steps: int = 4, site_type: str = 'spinful_fermions', spin_indices: Set[int] | None = None)

Transformable system from an electronic structure calculation input.

Construct the transformable system obtained from ab-initio calculation input.

Parameters:

  • hamiltonians (Hamiltonian_Matrices) – Collection of matrix descriptions of the system

  • Hamiltonian

  • rdm1 (Union[np.ndarray, Tuple[np.ndarray, ...]]) – Matrix description of the 1-RDM

  • rdm2 (np.ndarray) – Tensor description of the 2-RDM

  • system_size (int) – Number of orbitals in the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • tolerance (float) – Parity tolerance \(P_i=(-1 + \delta)\) for an orbital to be

  • spin-like

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • optimization_steps (int) – Number of optimization loops.

  • site_type (str) – Type of excitations in the orbitals.

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

  • ValueError – HU does not conform to the requirements needed for basis rotation

  • ValueError – The 2-RDM does not conform to the requirements needed for spin optimization

__init__(hamiltonians: Hamiltonian_Matrices, rdm1: ndarray | Tuple[ndarray, ...], rdm2: ndarray, system_size: int | None = None, rotation_matrix: ndarray | None = None, tolerance: float = 0.1, prefactor_cutoff: float = 1e-06, optimization_steps: int = 4, site_type: str = 'spinful_fermions', spin_indices: Set[int] | None = None) → None

Construct the transformable system obtained from ab-initio calculation input.

Parameters:

  • hamiltonians (Hamiltonian_Matrices) – Collection of matrix descriptions of the system

  • Hamiltonian

  • rdm1 (Union[np.ndarray, Tuple[np.ndarray, ...]]) – Matrix description of the 1-RDM

  • rdm2 (np.ndarray) – Tensor description of the 2-RDM

  • system_size (int) – Number of orbitals in the system

  • rotation_matrix (np.ndarray) – Transformation matrix \(U_{iq}\) to the spin-optimized

  • basis

  • tolerance (float) – Parity tolerance \(P_i=(-1 + \delta)\) for an orbital to be

  • spin-like

  • prefactor_cutoff (float) – Cutoff for the absolute value of the coupling strength of

  • transformation. (terms to be considered in the Schrieffer-Wolff)

  • optimization_steps (int) – Number of optimization loops.

  • site_type (str) – Type of excitations in the orbitals.

  • spin_indices (Set[int]) – Set of indices of the dedicated spin-like orbitals.

Raises:

  • ValueError – HU does not conform to the requirements needed for basis rotation

  • ValueError – The 2-RDM does not conform to the requirements needed for spin optimization

_spin_indices: Set[int]
_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
property generator: ExpressionSpinful | ExpressionSpinful_complex

Return the generator \(S\) of the Schrieffer-Wolff transformation.

Returns:

The generator of the Schrieffer-Wolff transformation

Return type:

Union[ExpressionSpinful, ExpressionSpinfulComplex]

property hamiltonians: Hamiltonian_Matrices

Return the matrix descriptions of the terms in the system Hamiltonian.

Returns:

The stored Hamiltonian matrices

Return type:

Hamiltonian_Matrices

property prefactor_cutoff: float

Return the cutoff for the prefactors of terms to be considered in the transformation.

Returns:

The cutoff below which terms are dropped for the transformation

Return type:

float

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property site_type: str

Return the type of orbitals (e.g. spinful_fermions or spinless_fermions).

Returns:

The type of the system sites

Return type:

str

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property transformed_hamiltonian: ExpressionSpinful | ExpressionSpinful_complex

Return the Schrieffer-Wolff transformed Hamiltonian \(\tilde{H}\).

Returns:

The transformed Hamiltonian

Return type:

Union[ExpressionSpinful, ExpressionSpinful_complex]

property tolerance: float

Return the tolerated parity deviation \(\delta\) in \(P=(-1+\delta)\) to be considered a spin-orbital.

Returns:

The stored value for the tolerance :maht:`delta` of the parity

Return type:

float

property optimization_steps: int

Return the number of optimization loops.

Returns:

The number of optimization loops

Return type:

int

property immutable_indices: Set[int]

Return the orbital indices that should remained unaltered by the optimization.

Returns:

The set of immutable indices

Return type:

Set[int]

property rdm1: ndarray | Tuple[ndarray, ...]

Return the matrix descriptions of the 1-RDM (\(\langle c^{\dagger}_{i\sigma} c_{j\sigma'}\rangle\)).

Returns:

The (spin-resolved) 1-RDM(s)

Return type:

Union[np.ndarray, Tuple[np.ndarray, …]]

property rdm2: ndarray

Return the tensor of the 2-RDM (\(\langle c^{\dagger}_{i\uparrow} c^{\dagger}_{j\downarrow} c_{k\downarrow} c_{l\uparrow}\rangle\)).

Returns:

Tensor description of the 2-RDM

Return type:

np.ndarray

class hqs_spin_mapper.transformables.SpinFinder(rdm1: ndarray | Tuple[ndarray, ...], rdm2: ndarray, tolerance: float = 0.1, optimization_steps: int = 4, spin_indices: Set[int] | None = None)

Data object for use in a spin determination calculation.

Construct the object ab-initio calculation input.

Parameters:

  • rdm1 (Union[np.ndarray, Tuple[np.ndarray, ...]]) – Matrix descriptions of the 1-RDM

  • rdm2 (np.ndarray) – Tensor description of the 2-RDM

  • tolerance (float) – Parity tolerance \(delta\) in \(P=(-1 + \delta)\) for an

  • spin-like (orbital to be)

  • optimization_steps (int) – Number of optimization loops

  • spin_indices (Set[int]) – Set of indices of the dedicated spinful orbitals

Raises:

ValueError – The 2-RDM does not conform to the requirements needed for spin optimization

_abc_impl = <_abc._abc_data object>
_is_protocol = False
_is_runtime_protocol = True
__init__(rdm1: ndarray | Tuple[ndarray, ...], rdm2: ndarray, tolerance: float = 0.1, optimization_steps: int = 4, spin_indices: Set[int] | None = None) → None

Construct the object ab-initio calculation input.

Parameters:

  • rdm1 (Union[np.ndarray, Tuple[np.ndarray, ...]]) – Matrix descriptions of the 1-RDM

  • rdm2 (np.ndarray) – Tensor description of the 2-RDM

  • tolerance (float) – Parity tolerance \(delta\) in \(P=(-1 + \delta)\) for an

  • spin-like (orbital to be)

  • optimization_steps (int) – Number of optimization loops

  • spin_indices (Set[int]) – Set of indices of the dedicated spinful orbitals

Raises:

ValueError – The 2-RDM does not conform to the requirements needed for spin optimization

property rotation_matrix: ndarray

Return the rotation matrix that transforms the system to the spin-optimized basis.

Returns:

The stored rotation matrix \(U_{iq}\)

Return type:

np.ndarray

property spin_indices: Set[int]

Return the set of indices of the spin-like orbitals.

Returns:

The indices of the spin-like orbitals

Return type:

Set[int]

property system_size: int

Return the system size i.e. the number of orbitals.

Returns:

The combined size of the system

Return type:

int

property tolerance: float

Return the tolerated parity deviation \(\delta\) in \(P=(-1+\delta)\) to be considered a spin-orbital.

Returns:

The stored parity tolerance

Return type:

float

property optimization_steps: int

Return the number of optimization loops.

Returns:

The number of optimization loops

Return type:

int

property immutable_indices: Set[int]

Return the orbital indices that should remained unaltered by the optimization.

Returns:

The set of immutable indices

Return type:

Set[int]

property rdm1: ndarray | Tuple[ndarray, ...]

Return the matrix/ces of the 1-RDM (\(\langle c^{\dagger}_{i\sigma} c_{j\sigma'}\rangle\)).

Returns:

The matrix descriptions of the 1-RDM

Return type:

Union[np.ndarray, Tuple[np.ndarray, …]

property rdm2: ndarray

Return the tensor description of the 2-RDM (\(\langle c^{\dagger}_{i\uparrow} c^{\dagger}_{j\downarrow} c_{k\downarrow} c_{l\uparrow}\rangle\)).

Returns:

The tensor description of the 2-RDM

Return type:

np.ndarray