qpe_toolbox.hamiltonian.chemistry
=================================

.. py:module:: qpe_toolbox.hamiltonian.chemistry


Functions
---------

.. autoapisummary::

   qpe_toolbox.hamiltonian.chemistry.chemistry_hamiltonian
   qpe_toolbox.hamiltonian.chemistry.do_pyscf
   qpe_toolbox.hamiltonian.chemistry.make_qubit_hamiltonian
   qpe_toolbox.hamiltonian.chemistry.make_fermionic_hamiltonian
   qpe_toolbox.hamiltonian.chemistry.terms_from_openfermion


Module Contents
---------------

.. py:function:: chemistry_hamiltonian(molecule, hf_mode, *, encoding='original', do_fci=False, do_ccsd=False)

   Build a molecular electronic Hamiltonian mapped to qubits.

   This function performs a PySCF Hartree-Fock calculation, optionally followed
   by FCI and/or CCSD, constructs the second-quantized fermionic Hamiltonian,
   and maps it to a qubit Hamiltonian using the Jordan-Wigner transformation.

   :param molecule: PySCF molecule object defining geometry and basis.
   :type molecule: :pyscf-api:`pyscf.gto.Mole <gto.html#pyscf.gto.mole.Mole>`
   :param hf_mode: Type of Hartree-Fock calculation. Default is ``'rhf'``.
   :type hf_mode: {'rhf', 'uhf'}, optional
   :param encoding: Encoding of two-body integrals:
                    - ``'original'``: full integrals
                    - ``'sf'``: single-factorized
                    - ``'df'``: double-factorized
   :type encoding: {'original', 'sf', 'df'}, optional
   :param do_fci: Whether to compute the FCI ground-state energy.
   :type do_fci: bool, optional
   :param do_ccsd: Whether to compute the CCSD energy.
   :type do_ccsd: bool, optional

   :returns: Qubit Hamiltonian with additional attributes:
             ``norb``, ``nelec``, ``e_hf``, and optionally ``e_fci`` and ``e_ccsd``.
   :rtype: Hamiltonian


.. py:function:: do_pyscf(molecule, hf_mode, do_fci, do_ccsd)

   Run PySCF electronic-structure calculations.

   Performs a Hartree-Fock calculation, and optionally FCI and CCSD,
   returning the HF object needed to extract molecular integrals.

   :param molecule: Molecular system.
   :type molecule: :pyscf-api:`pyscf.gto.Mole <gto.html#pyscf.gto.mole.Mole>`
   :param hf_mode: Hartree-Fock flavor.
   :type hf_mode: {'rhf', 'uhf'}
   :param do_fci: Whether to compute FCI energy.
   :type do_fci: bool
   :param do_ccsd: Whether to compute CCSD energy.
   :type do_ccsd: bool

   :returns: * **e_fci** (*float or None*) -- FCI ground-state energy.
             * **e_ccsd** (*float or None*) -- CCSD ground-state energy.
             * **hf** (:pyscf-api:`pyscf.scf.hf.SCF <scf.html>`) -- Hartree-Fock object containing molecular orbitals and integrals.


.. py:function:: make_qubit_hamiltonian(hf, hf_mode, encoding)

   Construct a qubit Hamiltonian from a PySCF Hartree-Fock object.

   :param hf: Converged HF object.
   :type hf: :pyscf-api:`pyscf.scf.hf.SCF <scf.html>`
   :param hf_mode: Hartree-Fock type.
   :type hf_mode: {'rhf', 'uhf'}
   :param encoding: Integral encoding scheme.
   :type encoding: {'original', 'sf', 'df'}

   :returns: Qubit Hamiltonian with constant energy shift stored in ``e_const``.
   :rtype: Hamiltonian


.. py:function:: make_fermionic_hamiltonian(ncas, ecore, hpq, hpqrs, hf_mode, encoding, *, verbosity=0)

   Build a fermionic second-quantized Hamiltonian.

   :param ncas: Number of active spatial orbitals.
   :type ncas: int
   :param ecore: Core (constant) energy contribution.
   :type ecore: float
   :param hpq: One-body integrals.
   :type hpq: ndarray
   :param hpqrs: Two-body integrals.
   :type hpqrs: ndarray or tuple of ndarray
   :param hf_mode: Hartree-Fock type.
   :type hf_mode: {'rhf', 'uhf'}
   :param encoding: Integral compression scheme.
   :type encoding: {'original', 'sf', 'df'}
   :param verbosity: Verbosity level.
   :type verbosity: int, optional

   :returns: Fermionic Hamiltonian operator.
   :rtype: :openfermion-ops:`FermionOperator`


.. py:function:: terms_from_openfermion(qubit_operator)

   Convert an OpenFermion qubit operator into quimb Hamiltonian terms.

   This function separates the constant (identity) contribution from
   Pauli-string terms and converts them into the format expected by
   the ``Hamiltonian`` class.

   :param qubit_operator: Qubit Hamiltonian expressed as a sum of Pauli strings.
   :type qubit_operator: :openfermion-ops:`QubitOperator`

   :returns: * **term_list** (*list of tuple*) -- List of Hamiltonian terms in quimb format:
               ``(coefficient, pauli_string, qubits)``.
             * **e_const** (*float*) -- Constant energy offset corresponding to the identity term.