Best practices

The HQS Spin Mapper software package contains a selection of modules which provide two major functionalities which are described in the "Applications" section in detail. On a high level, the first functionality is the identification of orbital bases containing spin-like basis orbitals, i.e. orbitals occupied by strictly a single electron. The second functionality facilitates the derivatioon of effective spin-bath model Hamiltonians for the detected spin-like orbitals. The remaining modules handle input and output functionality.

This section describes best practices in the application of HQS Spin Mapper.

Avoiding local extrema in the orbital optimization

Depending on the initial basis, it is possible that a single call to spin_orbital_optimization fails to determine the true parity optimized basis. The pairwise optimization algorithm can get stuck in local parity extrema of the parameter manifold. This behavior can be discouraged by using the following procedure:

• Call the spin_orbital_optimization function on the input data with target="minimum".
• Add the orbital indices that became spin-like to the immutable_indices of the Transformable instance.
• Call the spin_orbital_optimization function a second time on the updated input data with either target="extremum" or target="maximum".
• Call the spin_orbital_optimization function on the input data a final time with target="minimum".

Choosing a sensible value for prefactor_cutoff (Important to avoid memory overflow!)

To limit the system memory required for the Schrieffer-Wolff transformation algorithm, we recommend adjusting the value of prefactor_cutoff. The terms of the input Hamiltonian in the optimized basis, with an absolute coupling constant smaller than prefactor_cutoff will be excluded from the Hamiltonian prior to the Schrieffer-Wolff transformation step. This is done because a large number of small coupling constant terms slows down the SVD step of the transformation significantly, while not significantly changing the result. In the evaluation of the commutators that yield the transformed Hamiltonian, a larger number of terms can cause memory usage to exceed the system memory and resulting in a fatal error. We recommend inspecting the size of the coupling constants of the input Hamiltonian and choosing a value of prefactor_cutoff larger than the coupling constants that can be considered insignificant. When in doubt, choose a larger value for prefactor_cutoff first and then rerun the calculation with a slightly smaller value of prefactor_cutoff to check whether the result is sensitive to the change in prefactor_cutoff. If the result remains sensitive, we recommend gradually decreasing prefactor_cutoff and observing the memory usage.

We recommend to run the scripts or notebooks using the hqs_spin_mapper in an environment with a set ulimit. The ulimit can be set in the terminal before running the Python interpreter via:

ulimit -v {maximum_desired_memory_in_kilobytes}

This way the process gets safely terminated without potentially crashing the system.

Estimation of the required memory

We provide a method for a rough estimate of the required memory resources to perform the Schrieffer-Wolff transformation algorithm at the currently set value of prefactor_cutoff. The function can be called on the Transformable object using:

from hqs_spin_mapper.preconditioning import (
    estimate_required_memory
)

estimate_required_memory(data)

The function estimate_required_memory prints an estimate of the necessary memory in GB. If the estimated value exceeds the realistically available system memory, we recommended to increase the value of the field prefactor_cutoff and to check the estimated memory requirement again.

Post-processing of the spin-bath model Hamiltonian

The result of the model Hamiltonian derivation is stored as an ExpressionSpinful object in the transformed_hamiltonian field of the Transformable object. These objects offer a set of methods that can be used for further manipulation of the transformed Hamiltonian. Here we list some useful methods provided by the ExpressionSpinful class.

• normalize(eps = 0.0): Sorts the operators in the terms of the Hamiltonian in a standardized fashion and removes terms with an absolute prefactor smaller than the value eps.
• normal_order: Rewrites operators as creators and annihilators and normal orders them (creation operators to the left of annihilation operators).
• sort_descending: Sorts the terms in the expression by the absolute value of the coupling constants in descending order.
• sort_ascending: Sorts the terms in the expression by the absolute value of the coupling constants in ascending order.
• find(fermion): Returns the prefactor of the term containing the input operator.
• project_on_local_hilbert_subspace(x, condition): Projects the Hamiltonian on a subspace of the Hilbert space where the condition is satisfied for site x. condition is the integer corresponding to a bit string, where the 1-bit indicates the x-local $|0⟩$ state, the 2-bit indicates $|\uparrow ⟩$, the 4-bit indicates $|\downarrow ⟩$, and the 8-bit indicates $|\uparrow \downarrow ⟩$. The argument condition=6=4+2 thus corresponds to $\text{span}(|\downarrow ⟩,|\uparrow ⟩)$, namely the singly occupied site x.
• convert_to_spin_model(positions): Replace fermionic operators acting on the positions with spin operators assuming the identity $n_{i\uparrow }+n_{i\downarrow }\equiv 1$.

A simple script to convert the transformed fermionic Hamiltonian to a true spin-bath Hamiltonian description is given by:

spin_bath_system = system.transformed_hamiltonian

for n in cast(List[int], system.spin_indices):
    spin_bath_system.project_on_local_hilbert_subspace(n, 6)

spin_bath_system = spin_bath_system.convert_to_spin_model(system.spin_indices)