Best practices for the HQS Spin Mapper

The HQS Spin Mapper software package contains a selection of modules which provide two major functionalities that are described in the Applications section in details. On a high level, 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 tasks.

This section describes the best practices for the applications 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, 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 dropped 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 to perform the Schrieffer-Wolff transformation at the currently set 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 raise the value of the field prefactor_cutoff and to check the estimated memory requirement again.

Post-processing of the transformed Hamiltonian

The result of the model Hamiltonian derivation is stored as an ExpressionSpinful 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 of the ExpressionSpinful class.

• normalize(eps = 0.0): Orders the operators in the terms of the Hamiltonian in a standardized fashion and removes terms with an absolute prefactor smaller than eps.
• normal_order: Rewrites operators as creators and annihilators and normal orders them (creators to the left of annihilators).
• 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)