..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    : --

.. _dev_geh_intro:

Usage Guide for GeneralEffHam
=============================

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:

.. code-block:: text

    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


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``).


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.

.. code-block:: python

    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.


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.

Example Usage
^^^^^^^^^^^^^

.. code-block:: python

    # 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"
    )

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``).