Source code for hqs_spin_mapper.extract_couplings

r"""Determine the matrix- and tensor descriptions of the effective spin-bath model."""

# Copyright © 2021-2025 HQS Quantum Simulations GmbH. All Rights Reserved.
import numpy as np
from typing import Tuple

from hqs_spin_mapper.spin_mapper_protocols import (
    Supports_SW_Transformation,
)

__all__ = [
    "extract_quadratic",
    "extract_quartic",
]




def extract_quadratic(
    transformable_system: Supports_SW_Transformation,
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    r"""Extract the coupling constants from the quadratic terms in the effective model Hamiltonian.

    Args:
        transformable_system (Supports_SW_Transformation):
            Container object for the transformed system data

    Returns:
        Tuple[np.ndarray, np.ndarray, np.ndarray]: Tuple of matrices for the coupling constants.

    Raises:
        ValueError: Encountered invalid operator
    """
    dim = transformable_system.system_size

    H0_uu = np.zeros((dim, dim))
    H0_dd = np.zeros((dim, dim))
    H0_ud = np.zeros((dim, dim))

    # Loop over each TermSpinful in the ExpressionSpinful of the quadratic Hamiltonian.
    for term in transformable_system.transformed_hamiltonian.normal_order(True):
        # Access operator content of the Term.
        ops = term.get_list()
        # Consider only quadratic terms. (Requires prior true normal ordering)
        if len(ops) == 2:
            # Access location index of the operators
            if ops[0].Op() == 16:  # c^+_up
                if ops[1].Op() == 1:  # c_down
                    H0_ud[ops[0].x(), ops[1].x()] += term.get_value()
                elif ops[1].Op() == 8:  # c_up
                    H0_uu[ops[0].x(), ops[1].x()] += term.get_value()
            elif ops[0].Op() == 2:  # c^+_down
                if ops[1].Op() == 1:  # c_down
                    H0_dd[ops[0].x(), ops[1].x()] += term.get_value()
            else:
                raise ValueError("Invalid operator!")

    return (H0_uu, H0_dd, H0_ud)





def extract_quartic(transformable_system: Supports_SW_Transformation) -> np.ndarray:
    r"""Extract the coupling constants from the quartic terms in the effective model Hamiltonian.

    Args:
        transformable_system (Supports_SW_Transformation):
            Container object for the transformed system data

    Returns:
        np.ndarray: Rank-4-Tensor of coupling constants 
        (:math:`c^{\dagger}_{\uparrow} c^{\dagger}_{\downarrow} c_{\downarrow} c_{\uparrow}`).
    """
    dim = transformable_system.system_size
    HU = np.zeros(shape=(dim, dim, dim, dim))

    for term in transformable_system.transformed_hamiltonian.normal_order(True):
        # Access operator content of the Term.
        ops = term.get_list()
        if len(ops) == 4:
            # Access location index of the operators
            xi = ops[0].x()
            xj = ops[1].x()
            xk = ops[2].x()
            xl = ops[3].x()
            # Add the prefactor of the term to the Hamiltonian tensor entry corresp. to the loc.
            HU[xi, xj, xk, xl] += term.get_value()

    return HU