Applications

Outline

• 1.1 Accepted input formats
• 1.2 Functionality: Spin-like orbital basis optimization
• 2.1 Preparation of input data for the Schrieffer-Wolff transformation
• 2.2 Functionality: Effective spin-bath model derivation
• 2.3 Extraction of tensor descriptions
• 2.4 Serialization with struqture

Functionality of the HQS Spin Mapper software package

HQS Spin Mapper software package contains a selection of modules which provide two major functionalities. The first functionality is the identification of orbital bases containing spin-like orbitals, i.e. orbitals with an occupancy of strictly a single electron. The second one derives effective spin-bath model Hamiltonians for the determined spin-like orbitals. The remaining modules handle input and output functionality.

1.1 Accepted input formats (hqs_spin_mapper.transformables)

HQS Spin Mapper currently accepts several different input formats for the Hamiltonian descriptions of a system (i.e. crystals and molecules). Some of the input formats store additional information about the system, which is, for example, needed for the determination of spin-like orbital bases or to reduce the computational of the spin-bath model derivation. There is also the possibility for the user to provide their own input format through the use of the supplied protocols.

Currently supported by default are:

• LatticeBuilder configuration object instances
• LatticeBuilder configuration data files as *.yml
• Struqture FermionHamiltonianSystem object instances
• Data container (Transformable_QuantumChemistry) including the one- and two-particle integrals specifying the Hamiltonian stored as numpy binary *.npy files.
• Data container (Transformable_Matrices) including the single particle picture matrices of the Hamiltonian as numpy array instances.

For each default input format, we provide a specific class derived from the Transformable class. The Transformable object serves as the necessary input argument of the essential methods of the hqs_spin_mapper package and are manipulated by these methods. The Transformable classes need to satisfy the Supports_SW_Transformation protocol. Any object satisfying the Supports_SW_Transformation protocol can be used with the functions provided by hqs_spin_mapper.

LatticeBuilder object instances and data files (Transformable_LatticeBuilder)

Given an instance of a LatticeBuilder object, it is easy to instantiate a Transformable_LatticeBuilder object from, which can then be used as the input for the subsequent functions. To instantiate the Transformable_LatticeBuilder object, use:

from hqs_spin_mapper.transformables import Transformable_LatticeBuilder

system = Transformable_LatticeBuilder(input_builder)

If the LatticeBuilder description of the system is stored in a valid *.yml file, the Transformable_LatticeBuilder object is instantiated in the same way.

from hqs_spin_mapper.transformables import Transformable_LatticeBuilder

system = Transformable_LatticeBuilder(input_lattice_builder_yaml)

Struqture FermionHamiltonianSystem instances (Transformable_Struqture)

A Transformable_Struqture object can be directly instantiated from a struqture_py.fermions.FermionHamiltonianSystem instance.

from hqs_spin_mapper.transformables import Transformable_Struqture

system = Transformable_Struqture(input_struqture)

Hamiltonians as numpy array instances (Transformable_Matrices)

The description of the Hamiltonian of a given system can be provided as a collection of matrices and/or tensors respectively, in the single particle picture. The matrices and tensors first need to be stored in a data container class called Hamiltonian_Matrices.

from hqs_spin_mapper.spin_mapper_protocols import Hamiltonian_Matrices

hamiltonian_matrices = Hamiltonian_Matrices(H0_uu=H0_uu,
                                            H0_dd=H0_dd,
                                            H0_ud=H0_ud,
                                            HU=HU,
                                            Jz=None,
                                            Jp=None,
                                            Jc=None)

The spin indices of the quadratic $c_{i\sigma }^{†}{c}_{j{\sigma }^{\prime }}$ fermionic terms H0_uu, H0_dd, H0_ud indicate the spin component of the electrons. If provided as a matrix, HU denotes density-density interaction terms. If HU is provided as a tensor, more complex four index interaction terms can be specified. The matrix Jz specifies $S_i^z{S}_j^z$ interactions, Jp specifies $S_i^{+}{S}_j^{-}$ interactions, and Jc specifies ${\vec{S}}_i\times {\vec{S}}_j$ interactions.

The quadratic Hamiltonian matrices H0_uu, H0_dd, H0_ud have to follow the convention

$$H_0=\sum _{ij,\sigma {\sigma }^{\prime }}{\left({\left[H_0\right]}_{\sigma {\sigma }^{\prime }}\right)}_{ij}{c}_{i\sigma }^{†}{c}_{j{\sigma }^{\prime }}$$

The matrices H0_uu, H0_dd, H0_ud have to be provided for three different combinations of the spin directions $\sigma {\sigma }^{\prime }$, i.e. $(\uparrow ,\uparrow )$, $(\downarrow ,\downarrow )$ and $(\uparrow ,\downarrow )$.

If provided as a matrix (2-tensor), HU has to conform to

$$H_U=\sum _{ij,\sigma {\sigma }^{\prime }}(H_U{)}_{ij}{n}_{i\sigma }^{†}{n}_{j{\sigma }^{\prime }}^{†}$$

and if provided as a 4-tensor to

$$H_U=\sum _{ijkl,\sigma {\sigma }^{\prime }}(H_U{)}_{ijkl}{c}_{i\sigma }^{†}{c}_{j{\sigma }^{\prime }}^{†}{c}_{k{\sigma }^{\prime }}{c}_{l{\sigma }^{\prime }}$$

Using the Hamiltonian_Matrices instance, one can instantiate a Transformable_Matrices object that satisfies the Supports_SW_Transformation protocol via

from hqs_spin_mapper.transformables import Transformable_Matrices

system = Transformable_Matrices(hamiltonian_matrices)

Electron integrals from electronic structure codes (Transformable_QuantumChemistry)

If the output of a preceding electronic structure calculations contains the one-electron and two-electron integrals specifying the Hamiltonian, e.g. stored as numpy binary *.npy files, one can construct a Transformable from the corresponding tensors via instantiation of a Transformable_Matrices object as shown in the previous section.

from hqs_spin_mapper.spin_mapper_protocols import Hamiltonian_Matrices
from hqs_spin_mapper.transformables import Transformable_Matrices

H0_uu = np.load('h0_uu.npy')
H0_dd = np.load('h0_dd.npy')
H0_ud = np.load('h0_ud.npy')
HU = np.load('hu.npy')

hamiltonian_matrices = Hamiltonian_Matrices(H0_uu=H0_uu,
                                            H0_dd=H0_dd,
                                            H0_ud=H0_ud,
                                            HU=HU,
                                            Jz=None,
                                            Jp=None,
                                            Jc=None)

system = Transformable_Matrices(hamiltonian_matrices)

If the results from the preceding electronic structure calculations furthermore include the one-electron density matrix (1-RDM) and the two-electron density matrix (2-RDM), one can instead instantiate a Transformable_QuantumChemistry object. The Transformable_QuantumChemistry object satisfies the Supports_Spin_Optimization protocol. This means that the object can be used as the input argument for the spin basis optimization functionality of hqs_spin_mapper.

from hqs_spin_mapper.transformables import Transformable_QuantumChemistry
from hqs_spin_mapper.spin_mapper_protocols import Hamiltonian_Matrices

hamiltonian_matrices = Hamiltonian_Matrices(H0_uu=H0_uu,
                                            H0_dd=H0_dd,
                                            H0_ud=H0_ud,
                                            HU=HU,
                                            Jz=None,
                                            Jp=None,
                                            Jc=None)

rdm1_uu = np.load('rdm1_uu.npy')
rdm1_dd = np.load('rdm1_dd.npy')
rdm1_ud = np.load('rdm1_ud.npy')
rdm2 = np.load('rdm2.npy')

system = Transformable_QuantumChemistry(hamiltonian_matrices,
                                        rdm1=(rdm1_uu, rdm1_dd, rdm1_ud),
                                        rdm2=rdm2,
                                        tolerance=1e-1)

The input reduced density matrices have to adhere to specific conventions. The spin orbital optimization will otherwise yield non-physical results. We expect the following conventions for the reduced density matrices:

• single 1-RDM:

$${\rho }_{ij}^{(1)}=\sum _{\sigma }⟨c_{i\sigma }^{†}{c}_{j\sigma }⟩$$

• spin-resolved 1-RDMs:

$${{\rho }_{ij}^{(1)}|}_{\sigma {\sigma }^{\prime }}=⟨c_{i\sigma }^{†}{c}_{j{\sigma }^{\prime }}⟩$$

• single 2-RDM:

$${\rho }_{ijkl}^{(2)}=⟨c_{i\uparrow }^{†}{c}_{j\downarrow }^{†}{c}_{k\downarrow }{c}_{l\uparrow }⟩$$

Input exclusively for spin-like orbital optimization (SpinFinder)

If the spin-bath model derivation functionality is not required, the user can instantiate a SpinFinder object, which is the valid minimum input for the functions pertaining to the determination of the spin-like orbital basis.

from hqs_spin_mapper.transformables import SpinFinder

rdm1_uu = np.load('rdm1_uu.npy')
rdm1_dd = np.load('rdm1_dd.npy')
rdm1_ud = np.load('rdm1_ud.npy')
rdm2 = np.load('rdm2.npy')

system = SpinFinder(rdm1=(rdm1_uu, rdm1_dd, rdm1_ud),
                    rdm2=rdm2)

Keyworded constructor arguments for Transformable objects

Attributes required by the Supports_SW_Transformation protocol:

• system_size: Optional[int] = None: Number of orbitals in the system. This is automatically derived from the model description. (available for Transformable_Matrices, Transformable_QuantumChemistry)
• rotation_matrix: Optional[numpy.ndarray] = None: Basis transformation matrix $U_{iq}$ between different orbital bases. The index $i$ denotes the orbital in the old basis and $q$ the orbital in the new basis. Default is the identity. (available for Transformable_LatticeBuilder, Transformable_Matrices, Transformable_QuantumChemistry)
• prefactor_cutoff: float = 1e-6: Terms of the Hamiltonian with coupling constant of absolute value smaller than the chosen value are discarded in the derivation of the spin-bath model (Schrieffer-Wolff transformation). (available for Transformable_LatticeBuilder, Transformable_Struqture, Transformable_Matrices, Transformable_QuantumChemistry)
• site_type: str = "spinful_fermions": Type of particles occupying the orbitals. (available for Transformable_Matrices, Transformable_QuantumChemistry)
• spin_indices: Optional[Set[int]] = None: User choice of orbitals to be treated as spin-like. The spin-like orbital optimization will add indices to this set. (available for Transformable_LatticeBuilder, Transformable_Struqture, Transformable_Matrices, Transformable_QuantumChemistry)

Attributes required by the Supports_Spin_Optimization protocol:

• tolerance: float = 1e-1: Chosen discrepancy $\Delta$ used in $P_i\le (-1+\Delta )$ for a basis orbital $i$ to be considered spin-like, where $P_i$ denotes the local parity. (available for Transformable_QuantumChemistry, SpinFinder)
• optimization_steps: int = 4: Number of optimization loops to be performed. Parities are typically converged after 4 loops. (available for Transformable_QuantumChemistry, SpinFinder)

Other mutable attributes of Transformable objects

Attributes required by the Supports_SW_Transformation protocol:

• generator: Union[ExpressionSpinful, ExpressionSpinful_complex]: Result for the generator of the Schrieffer-Wolff transformation.
• transformed_hamiltonian: Union[ExpressionSpinful, ExpressionSpinful_complex]: Result for the transformed fermionic Hamiltonian.

Atrributes required by the Supports_Spin_Optimization protocol:

• immutable_indices: Set[int]: Indices of orbitals that are exempt from parity optimization.

Custom Transformable objects (hqs_spin_mapper.spin_mapper_protocols)

The user can create their own custom input format by implementing a class that satisfies the protocols Supports_Spin_Optimization and/or Supports_SW_Transformation.

1.2 Functionality: Spin-like orbital basis optimization (hqs_spin_mapper.orbital_optimization)

HQS Spin Mapper provides the functionality to determine the optimal single-particle orbital basis, in which a subset of the basis orbitals exhibits the maximum possible spin-like character. We quantify the spin-like character of basis orbitals on the basis of their local parity $P_i=(-1{)}^{n_{i\uparrow }+n_{i\downarrow }}$. For more details about the use of the local parity as a measure for spin-like character, please consult the Theory section. An orbital $q$ in the optimized basis is stored as spin-like if its local parity satisfies $P_q\le (-1+\Delta )$, where $\Delta$ corresponds to the value stored in the tolerance field of the Transformable.

The spin_orbital_optimization function in the orbital_optimization module determines a basis transformation which would optimize the local parities and stores the corresponding (proposed) basis transformation in the rotation_matrix field of the Transformable object. The respective indices of the spin-like orbitals in this optimized basis are stored in the spin_indices field of the Transformable object. The spin_orbital_optimization function requires Transformable objects that satisfy the Supports_Spin_Optimization protocol.

from hqs_spin_mapper.orbital_optimization import spin_orbital_optimization

spin_orbital_optimization(system)

Keyworded arguments

• space_reduction: bool = True: If flag is set, the optimization is restricted to the indices not contained in the immutable_indices field of the Transformable.
• fast_mode: bool = False: If flag is set, the rotations of the 2-RDM are performed approximately to reduce computation time.
• target: str = "minimum": Type of extremum to optimize for. Avalailable options are: minimum, maximum, and extremum.
• _delta_sufficiently_spin_like: float = 1e-3: Exclude orbitals with initial parities $P_i<(-1+\delta )$ and $P_i>(+1-\delta )$ from the optimization search.

The function spin_orbital_optimization transforms the rdm1 and rdm2 to the optimized basis (in order to save memory). The Hamiltonian tensors are not transformed. For the transformation of the Hamiltonian tensors see the section on preconditioning of the input data.

The results of the optimized system are subsequently stored in the corresponding fields of the Transformable object:

spin_indices = system.spin_indices
rotation_matrix = system.rotation_matrix

rdm1 = system.rdm1
rdm2 = system.rdm2

2.1 Preparation of input data for the Schrieffer-Wolff transformation (hqs_spin_mapper.preconditioning)

For the derivation of the spin-bath model, the spin_indices: Set[int] field of the Transformable instance first requires a finite amount of indices. If the spin orbital optimization feature was used, spin_indices of the Transformable have been set to feature the obtained spin orbitals automatically. Otherwise spin_indices needs to be set manually by the user as e.g.:

spin_like_orbital_indices: Set[int] = {4, 9}

system.spin_indices = spin_like_orbital_indices

An intuitive choice for spin-like orbitals are orbitals with particularly strong repulsive local (i.e. on-site) interactions ${\left[H_U\right]}_{iiii}\gg 0$.

The preconditioning of the input data necessary for the subsequent Schrieffer-Wolff transformation is done automatically by calling the preconditioning function on the Transformable object once. Due to the side effects of the preconditioning function, we advise against multiple calls of the preconditioning functions on the same Transformable object.

from hqs_spin_mapper.preconditioning import preconditioning

preconditioning(system)

The following tasks are performed by the preconditioning function:

• Generalization of the input interaction tensors HU, Jz, Jp, Jc to a four index tensor description.
• Rotation of the matrix and tensor descriptions to the optimized basis by rotation with the rotation_matrix $U_{iq}$.

$$H_0=\sum _{ij}{\left[H_0\right]}_{ij}{U}_{iq}{U}_{jp}$$ $$H_U=\sum _{ijkl}{\left[H_U\right]}_{ijkl}{U}_{iq}{U}_{jp}{U}_{kr}{U}_{ls}$$

• If apply_pre_diagonalization = True: Mean-field decoupling (if Supports_Spin_Optimization) i.e. removal of bath exclusive interaction terms.

$${\tilde{H}}_0^{\mathrm{bath}}=\sum _{qp\in \mathrm{bath}}\sum _{\sigma {\sigma }^{\prime }}{t}_{qp}^{\sigma {\sigma }^{\prime }}{c}_{q\sigma }^{†}{c}_{p{\sigma }^{\prime }}-\sum _{qprs\in \mathrm{bath}}{V}_{qprs}\left(⟨c_{q\uparrow }^{†}{c}_{s\uparrow }⟩c_{p\downarrow }^{†}{c}_{r\downarrow }-⟨c_{p\downarrow }^{†}{c}_{r\downarrow }⟩c_{q\uparrow }^{†}{c}_{s\uparrow }-⟨c_{q\uparrow }^{†}{c}_{r\downarrow }⟩c_{p\downarrow }^{†}{c}_{s\uparrow }-⟨c_{p\downarrow }^{†}{c}_{s\uparrow }⟩c_{q\uparrow }^{†}{c}_{r\downarrow }\right)$$

• If apply_pre_diagonalization = True: Diagonalization of the quadratic bath Hamiltonian ${\tilde{H}}_0$ and transformation of the Hamiltonian tensors to the diagonal basis.
• If apply_cross_geometry = True: Re-indexing to place the spin indices in the middle of the system at $x_0+q$, with $x_0$ defined as

x0 = (system.system_size // 2) - (len(system.spin_indices) // 2)

Keyworded arguments

• apply_pre_diagonalization: bool = False: Perform a simplification of bath exclusive interactions and a diagonalization of the resulting quadratic bath Hamiltonian.
• apply_cross_geometry: bool = False: Move the spin indices to the center of the system (can speed up subsequent DMRG calculations).

2.2 Functionality: Effective spin-bath model derivation (hqs_spin_mapper.schrieffer_wolff)

With the input data preconditioned, the effective spin-bath model derivation becomes a simple call to schrieffer_wolff on the Transformable object.

from hqs_spin_mapper.schrieffer_wolff import schrieffer_wolff

schrieffer_wolff(system)

The results of the derivation, namely the transformed Hamiltonian $H$ and the generator of the transformation $S$ in $$H=H_0+V+\left[S,H_0\right]+\left[S,V\right]+\mathcal{O}(S^2)$$ are stored in the Transformable object instances as:

transformed_hamiltonian = system.transformed_hamiltonian
generator = system.generator

Keyworded arguments

• _max_length: int = 5: Size limit for the terms included in the generator.
• _vector_space_cap: int = 1500000: Size limit of the vector space that the generator is determined from.
• _max_krylov_space_dimension: int = 200: Size restriction of the Krylov space used in the SVD.
• rdm2: Optional[numpy.ndarray] = None: 2RDM for use in decoupling (currently not activated).

2.3 Extract tensor descriptions for the spin-bath model (hqs_spin_mapper.extract_couplings)

Using the functions contained in the extract_couplings module, one can retrieve the matrix and tensor descriptions respectively of the spin-bath model Hamiltonian.

from hqs_spin_mapper.extract_couplings import extract_quadratic, extract_quartic

(H0_uu, H0_dd, H0_ud) = extract_quadratic(system)
HU = extract_quartic(system)

The matrices and tensor only contain the quadratic and quartic terms of the Hamiltonian respecitvely. The terms containing in excess of $(n\ge 5)$ fermionic operators are not extracted.

2.4 Serialize the spin-bath model Hamiltonian with struqture (hqs_spin_mapper.struqture_interface)

The transformed Hamiltonian can be exported to an instance of struqture_py.mixed_systems.MixedHamiltonianSystem for use in other HQS software or for serialization.

from hqs_spin_mapper.struqture_interface import get_struqture_description

struqture_description = get_struqture_description(system)