..
    : 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_examples:

Implementation Examples
=======================

This section provides concrete examples of implementing and registering new Hamiltonian blocks using the protocols outlined in the previous sections. The code snippets below are pulled directly from the PyBEST source files.

Understanding the Directory Routing
-----------------------------------

The target subfolder within ``eff_ham/blocks/`` is determined dynamically by sorting the block's rank and index groups into occupied (o) or virtual (v) footprints. For the detailed index classification tables and step-by-step path generation rules, see :ref:`directory_routing_rules`.

Example 1: Dense Block Implementation (Protocol A)
--------------------------------------------------

This is a practical example of how to implement a standard, cacheable block. We are implementing the ``X_ad`` block here.

* **Indices:** ``a`` (virtual), ``d`` (virtual) translates to the ``vv`` directory.
* **File Name:** ``x_ad.py``

.. literalinclude:: ../src/pybest/eff_ham/blocks/two_index/vv/x_ad.py
    :caption: eff_ham/blocks/two_index/vv/x_ad.py
    :lines: 27-


Example 2: Special Block Implementation (Protocol B)
----------------------------------------------------

This is an example of implementing Special blocks. Because Special blocks bypass the cache entirely regardless of the linear algebra factory, they only require the Protocol B implementation. We are implementing the ``X_iAjb_sigma`` and ``X_iAJB_sigma`` blocks.

* **Indices:** ``i, a, j, b`` (occupied, virtual, occupied, virtual) translates to the ``ovov`` directory.
* **File Name:** ``x_iajb.py``

Notice how both distinct spin blocks are implemented in the same lowercase file, but their exact casing is preserved in their respective method signatures. Also note how they compute directly into the developer-provided ``sigma`` output tensor.

.. literalinclude:: ../src/pybest/eff_ham/blocks/four_index/ovov/x_iajb.py
    :caption: eff_ham/blocks/four_index/ovov/x_iajb.py
    :lines: 27-


Example 3: Cholesky Block Implementation with Helper Functions (Protocols A & B)
--------------------------------------------------------------------------------

This is an example of a Cholesky block (belonging to ``GeneralEffHamCholeskyBlocks``). Because its execution depends on the active linear algebra factory, we **must** provide both the Dense (Protocol A) and the On-the-Fly Cholesky (Protocol B) implementations within the same file.

This example also demonstrates how to use **helper functions** (e.g., ``get_t1_t2_X_ajbc``). The dynamic loader binds them automatically because their names contain the exact block label.

* **Indices:** ``a, j, b, c`` (virtual, occupied, virtual, virtual) translates to the ``vovv`` directory.
* **File Name:** ``x_ajbc.py``

.. literalinclude:: ../src/pybest/eff_ham/blocks/four_index/vovv/x_ajbc.py
    :caption: eff_ham/blocks/four_index/vovv/x_ajbc.py
    :lines: 27-446