1.1. Usage Guide for GeneralEffHam

1.1.1. Folder Structure

The effective Hamiltonian blocks are organized dynamically based on their orbital index patterns (Occupied/Virtual). Maintain this structure to ensure the GeneralEffHam dynamic loader can find your implementations:

pybest/
├── src/
│   └── pybest/
│       ├── eff_ham/
│       │   ├── General_Effective_Hamiltonian.py # Core Orchestrator
│       │   ├── GeneralEffHam_library.py         # BLOCK_LIBRARY (ref/flavor mapping)
│       │   └── blocks/
│       │       ├── two_index/
│       │       │   ├── oo/                      # e.g., x_im.py
│       │       │   └── vv/                      # e.g., x_ad.py
│       │       ├── four_index/
│       │       │   ├── vvvv/                    # e.g., x_abcd.py
│       │       │   └── ovov/                    # e.g., x_iajb.py
│       ├── featuredlists.py                     # Category registration

1.1.2. Key Components

General_Effective_Hamiltonian.py: Contains the GeneralEffHam class orchestrator. It manages a local cache, resolves which blocks to load based on the method “flavor,” and dispatches contractions.
GeneralEffHam_library.py: Holds the BLOCK_LIBRARY dictionary, mapping reference methods (e.g., RCCSD), flavors, and parameters to their expected block lists.
featuredlists.py: Registers which blocks belong to which execution category (GeneralEffHamBlocks, GeneralEffHamCholeskyBlocks, GeneralEffHamSpecialBlocks).

1.1.3. Initializing the Hamiltonian

The GeneralEffHam class needs to be initialized to centralize block executions. To do this, instantiate the class in your set_hamiltonian method and return its internal cache.

def set_hamiltonian(self, ham_1_ao, ham_2_ao, mos) -> Cache:

    method_specs = {            # 'ref' and 'flavor' are strictly required
        "ref": self.reference,
        "flavor": self.acronym,
        "alpha": self.alpha,    # Optional parameter used in BLOCK_LIBRARY
    }

    self.eff_ham = GeneralEffHam(
        method_specs,
        self._lf,          # LinalgFactory
        self.disconnected, # Bool: include disconnected terms
        True,              # Dump blocks to disk
        ham_1_ao,
        ham_2_ao,
        mos,
        self.rcc_iodata,   # Contains amplitudes (t1, t2, etc.)
    )

    return self.eff_ham._cache

When defining the initialization dictionary, ref and flavor are strictly required. This dictionary is directly compared against the BLOCK_LIBRARY during initialization to determine exactly which blocks the instance will load and bind.

1.1.4. Using the contract() API

The GeneralEffHam class centralizes and standardizes all Hamiltonian block executions. Instead of manually caching tensors, checking for LinalgFactory types, and calling specific methods, you use the unified contract() API. It automatically handles parsing, cache resolution, and execution dispatching.

1.1.4.1. Example Usage

# Binary contraction (X_im * bvec -> out_vec)
self.eff_ham.contract(
    operands=["X_im", bvec, out_vec],
    subscript="ab,bc->ac",
    force_update=True,
    factor=2.0,
)

# Unary contraction (Extracting from X_ad directly into out_vec)
self.eff_ham.contract(
    operands=["X_ad", None, out_vec],
    subscript="ad->ad"
)

1.1.4.2. Argument Breakdown

operands: Always a 3-element list: [operand 1, operand 2, output]. One of the first two must be the block label string (e.g., "X_im"). If it is a unary operation, pass None as the second operand.
subscript: Standard np.einsum notation defining the contraction mapping.
force_update: A special boolean argument that forces the recomputation of the block even if it is already present in the cache. Defaults to False.
**kwargs: Standard PyBEST tensor contraction arguments passed directly to the underlying tensor math (e.g., factor=2.0).