Implement AlternativeSpinHamiltonian for Issue #179

[smandal21-pixel]

I have refactored the AlternativeSpinHamiltonian to inherit directly from HamHeisenberg. This allows the class to act as an adapter that maps custom spin topologies to the existing integral-based architecture, successfully avoiding dense Kronecker product constructions and leveraging the library's built-in fermion creation/annihilation operator mapping.

Changes include:

Updated AlternativeSpinHamiltonian to utilize HamHeisenberg for integral generation.

Added a new pytest suite in moha/test/test_alternative_spin.py to verify site connectivity and integral tensor shapes.

Ensured compatibility with downstream solvers by providing proper one-body and two-body integrals.

This is part of my GSoC 2026 application for Issue #179. All CI checks are passing.

[smandal21-pixel]

Note for reviewers: I am aware this Draft PR slightly exceeds the recommended 3 commits / 50 lines of code limit mentioned in the contributing guidelines. The extra lines are entirely due to the inclusion of the required pytest suite to verify the Heisenberg energy levels. I have kept the core logic as minimal as possible.

[RichRick1]

I don't think we need to manually code spin operators, as we have introduced mapping from spin-operators to fermion creation/annihilation operators

[smandal21-pixel]

Thank you for the review and the guidance, @RichRick1! I completely understand. Since I was working from a ground-up approach, I missed that the spin-to-fermion mapping was already introduced.

I see the existing HamHeisenberg class in moha/hamiltonians.py. I will scrap my manual dense matrix generation and pivot to utilizing the built-in fermion creation/annihilation operators instead. Could you point me to the specific file/module where the spin-to-fermion mapping functions are stored so I can review them?

[smandal21-pixel]

Following up on my previous message—I’ve just reviewed the newly updated docs/spin.rst and the HamHeisenberg / HamIsing classes. I see that the library is already set up to handle these as one-body and two-body integrals. I am currently refactoring my implementation to remove the manual dense matrix Kronecker products and instead utilize the alpha/beta fermion mapping to generate the integral equivalents. This will ensure full compatibility with the existing moha solvers.

[smandal21-pixel]

Hi @RichRick1, I've pushed the final refactor. AlternativeSpinHamiltonian now inherits the fermion mapping directly from HamHeisenberg, fully bypassing the dense Kronecker products. I also resolved the merge conflicts and updated the test suite. All CI checks are passing green! Let me know if you need anything else before merging