qpe_toolbox.hamiltonian.pyscf_converter ======================================= .. py:module:: qpe_toolbox.hamiltonian.pyscf_converter .. autoapi-nested-parse:: PySCF integral conversion utilities. Functions for extracting one- and two-electron integrals from PySCF mean-field objects (RHF, UHF, ROHF, CASCI) and assembling them into :openfermion-ops:`InteractionOperator` Hamiltonians, with optional single factorization (SF) and double factorization (DF). Functions --------- .. autoapisummary:: qpe_toolbox.hamiltonian.pyscf_converter.get_integrals_rhf qpe_toolbox.hamiltonian.pyscf_converter.get_integrals_uhf qpe_toolbox.hamiltonian.pyscf_converter.get_integrals_rhf_cas qpe_toolbox.hamiltonian.pyscf_converter.get_integrals_uhf_cas qpe_toolbox.hamiltonian.pyscf_converter.make_fermionic_hamiltonian_rhf qpe_toolbox.hamiltonian.pyscf_converter.make_fermionic_hamiltonian_uhf qpe_toolbox.hamiltonian.pyscf_converter.make_fermionic_hamiltonian_auto qpe_toolbox.hamiltonian.pyscf_converter.do_sf qpe_toolbox.hamiltonian.pyscf_converter.do_df Module Contents --------------- .. py:function:: get_integrals_rhf(rhf) Obtain one- and two-electron integrals for spin-restricted systems. :param rhf: Converged restricted Hartree-Fock object. :type rhf: :pyscf-api:`pyscf.scf.RHF ` :returns: * **ncas** (*int*) -- Number of molecular orbitals. * **nelec** (*int*) -- Total number of electrons. * **nuclear_energy** (*float*) -- Nuclear repulsion energy (constant term). * **hpq** (:numpy-api:`ndarray`) -- One-electron integrals in the MO basis, shape ``(norb, norb)``. * **hpqrs** (:numpy-api:`ndarray`) -- Two-electron integrals in chemist notation, shape ``(norb, norb, norb, norb)``. .. py:function:: get_integrals_uhf(uhf) Obtain one- and two-electron integrals for spin-unrestricted systems. :param uhf: Converged unrestricted Hartree-Fock object. :type uhf: :pyscf-api:`pyscf.scf.UHF ` :returns: * **ncas** (*int*) -- Number of molecular orbitals. * **nelec** (*int*) -- Total number of electrons. * **nuclear_energy** (*float*) -- Nuclear repulsion energy (constant term). * **hpq** (tuple of :numpy-api:`ndarray`) -- One-electron integrals ``(h_up, h_down)``, each of shape ``(norb, norb)``. * **hpqrs** (tuple of :numpy-api:`ndarray`) -- Two-electron integrals in chemist notation ``(hpqrs_uu, hpqrs_ud, hpqrs_dd)``, each of shape ``(norb, norb, norb, norb)``. .. py:function:: get_integrals_rhf_cas(rhf, ncas, nelecas, *, ncore=None) Obtain one- and two-electron integrals for spin-restricted active-space systems. :param rhf: Converged restricted Hartree-Fock object. :type rhf: :pyscf-api:`pyscf.scf.RHF ` :param ncas: Number of active-space orbitals. :type ncas: int :param nelecas: Number of active-space electrons. :type nelecas: int or tuple of int :param ncore: Number of frozen core orbitals. Inferred from ``nelecas`` if ``None``. :type ncore: int or None, default: None :returns: * **ncas** (*int*) -- Number of active-space orbitals (as resolved by CASCI). * **nelec** (*int or tuple of int*) -- Number of active-space electrons (as resolved by CASCI). * **nuclear_energy** (*float*) -- Nuclear repulsion energy (constant term). * **hpq** (:numpy-api:`ndarray`) -- One-electron integrals in the active-space MO basis, shape ``(ncas, ncas)``. * **hpqrs** (:numpy-api:`ndarray`) -- Two-electron integrals in chemist notation, shape ``(ncas, ncas, ncas, ncas)``. .. py:function:: get_integrals_uhf_cas(uhf, ncas, nelecas, *, ncore=None) Obtain one- and two-electron integrals for spin-unrestricted active-space systems. :param uhf: Converged unrestricted Hartree-Fock object. :type uhf: :pyscf-api:`pyscf.scf.UHF ` :param ncas: Number of active-space orbitals. :type ncas: int :param nelecas: Number of active-space electrons. :type nelecas: int or tuple of int :param ncore: Number of frozen core orbitals. Inferred from ``nelecas`` if ``None``. :type ncore: int or None, default: None :returns: * **ncas** (*int*) -- Number of active-space orbitals (as resolved by UCASCI). * **nelec** (*int or tuple of int*) -- Number of active-space electrons (as resolved by UCASCI). * **nuclear_energy** (*float*) -- Nuclear repulsion energy (constant term). * **hpq** (tuple of :numpy-api:`ndarray`) -- One-electron integrals ``(h_up, h_down)``, each of shape ``(ncas, ncas)``. * **hpqrs** (tuple of :numpy-api:`ndarray`) -- Two-electron integrals in chemist notation ``(hpqrs_uu, hpqrs_ud, hpqrs_dd)``, each of shape ``(ncas, ncas, ncas, ncas)``. .. py:function:: make_fermionic_hamiltonian_rhf(constant, hpq, hpqrs, *, orbital_major=True) Construct an :openfermion-ops:`InteractionOperator` from RHF/CASCI integrals. Assembles the fermionic second-quantised Hamiltonian from the outputs of :func:`get_integrals_rhf` or :func:`get_integrals_rhf_cas`. :param constant: Zero-body (nuclear repulsion / core energy) term. :type constant: float :param hpq: One-electron integrals in the MO basis, shape ``(norb, norb)``. :type hpq: :numpy-api:`ndarray` :param hpqrs: Two-electron integrals in chemist notation, shape ``(norb, norb, norb, norb)``. :type hpqrs: :numpy-api:`ndarray` :param orbital_major: Spin-to-qubit mapping convention. If ``True``, qubits ``[0, norb)`` carry spin-up and qubits ``[norb, 2*norb)`` carry spin-down. If ``False``, even qubits carry spin-up and odd qubits carry spin-down. :type orbital_major: bool, default: True :returns: Second-quantised fermionic Hamiltonian. :rtype: :openfermion-ops:`InteractionOperator` .. py:function:: make_fermionic_hamiltonian_uhf(energy_constant, hpq, hpqrs, *, orbital_major=True) Construct an :openfermion-ops:`InteractionOperator` from UHF/UCASCI integrals. Assembles the fermionic second-quantised Hamiltonian from the outputs of :func:`get_integrals_uhf` or :func:`get_integrals_uhf_cas`. :param energy_constant: Zero-body (nuclear repulsion / core energy) term. :type energy_constant: float :param hpq: One-electron integrals ``(h_up, h_down)``, each of shape ``(norb, norb)``. :type hpq: tuple of :numpy-api:`ndarray` :param hpqrs: Two-electron integrals in chemist notation ``(hpqrs_uu, hpqrs_ud, hpqrs_dd)``, each of shape ``(norb, norb, norb, norb)``. :type hpqrs: tuple of :numpy-api:`ndarray` :param orbital_major: Spin-to-qubit mapping convention. If ``True``, qubits ``[0, norb)`` carry spin-up and qubits ``[norb, 2*norb)`` carry spin-down. If ``False``, even qubits carry spin-up and odd qubits carry spin-down. :type orbital_major: bool, default: True :returns: Second-quantised fermionic Hamiltonian. :rtype: :openfermion-ops:`InteractionOperator` .. py:function:: make_fermionic_hamiltonian_auto(mf, *, orbital_major=True) Construct an :openfermion-ops:`InteractionOperator` from any PySCF mean-field object. Dispatches to :func:`make_fermionic_hamiltonian_rhf` for :pyscf-api:`pyscf.scf.RHF ` / :pyscf-api:`pyscf.scf.ROHF ` objects and to :func:`make_fermionic_hamiltonian_uhf` for :pyscf-api:`pyscf.scf.UHF ` objects. :param mf: Converged PySCF mean-field object. :type mf: :pyscf-api:`pyscf.scf.RHF ` or :pyscf-api:`pyscf.scf.ROHF ` or :pyscf-api:`pyscf.scf.UHF ` :param orbital_major: Spin-to-qubit mapping convention passed through to the underlying assembly function. See :func:`make_fermionic_hamiltonian_rhf`. :type orbital_major: bool, default: True :returns: Second-quantised fermionic Hamiltonian. :rtype: :openfermion-ops:`InteractionOperator` .. py:function:: do_sf(hpqrs, *, threshold=0.0016) Perform eigenvalue-based single factorization of the two-electron integral tensor. Decomposes ``hpqrs`` via eigendecomposition of its matrix representation and truncates eigenvectors until the Frobenius-norm reconstruction error falls below ``threshold``. :param hpqrs: Two-electron integrals in chemist notation, shape ``(ncas, ncas, ncas, ncas)``. :type hpqrs: :numpy-api:`ndarray` :param threshold: Frobenius-norm convergence threshold for the truncated reconstruction. :type threshold: float, default: 1.6e-3 :returns: * **rank** (*int*) -- Number of eigenvectors retained. * **diff** (*float*) -- Frobenius norm of the truncation error. * **hpqrs_truncated** (:numpy-api:`ndarray`) -- Truncated two-electron integral tensor, shape ``(ncas, ncas, ncas, ncas)``. .. py:function:: do_df(hpqrs, *, threshold=0.0016) Perform double factorization of the two-electron integral tensor. First applies an outer eigendecomposition (single factorization), then diagonalises each factor and discards eigenvalues whose scaled magnitude falls below ``threshold``. Algorithm follows ``openfermion.resource_estimates.df.factorize_df``. :param hpqrs: Two-electron integrals in chemist notation, shape ``(ncas, ncas, ncas, ncas)``. :type hpqrs: :numpy-api:`ndarray` :param threshold: Per-factor eigenvalue truncation threshold. :type threshold: float, default: 1.6e-3 :returns: * **neig** (*int*) -- Total number of eigenvalues retained across all factors. * **rank** (*int*) -- Number of outer factors retained. * **df_factors** (:numpy-api:`ndarray`) -- Double-factorized tensor factors, shape ``(ncas, ncas, rank_retained)``. * **hpqrs_truncated** (:numpy-api:`ndarray`) -- Truncated two-electron integral tensor, shape ``(ncas, ncas, ncas, ncas)``. * **diff** (*float*) -- Frobenius norm of the truncation error.