Quantum Chemistry
=================

The :mod:`pyqed.qchem` package provides native quantum chemistry tools for
molecular integrals, Hartree-Fock references, post-HF correlation methods,
multiconfigurational methods, and excited-state calculations.

This page is a static overview. It avoids importing :mod:`pyqed.qchem` during
the documentation build because some optional compiled backends, such as
``libxc`` and integral libraries, may not be available on Read the Docs.

Core Workflow
-------------

A typical native calculation follows this structure:

.. code-block:: python

   from pyqed.qchem import Molecule

   mol = Molecule(
       atom="H 0 0 0; H 0 0 0.74",
       unit="angstrom",
       basis="sto-3g",
   )
   mol.build(driver="builtin", eri="auto")

   mf = mol.RHF().run()
   print(mf.e_tot)

Main Components
---------------

* ``pyqed.qchem.mol`` defines the molecular object, basis setup, and integral
  construction paths.
* ``pyqed.qchem.hf`` contains restricted and unrestricted Hartree-Fock drivers.
* ``pyqed.qchem.hf.analysis`` contains orbital, charge, and bond-order analysis
  helpers.
* ``pyqed.qchem.ci`` contains CI methods, including CISD and FCI utilities.
* ``pyqed.qchem.mcscf`` contains CASCI, CASSCF, state-averaged CASSCF, and
  second-order orbital optimization paths.
* ``pyqed.qchem.mp`` contains MP2 and orbital-optimized MP2 utilities.
* ``pyqed.qchem.tddft`` contains linear-response TDDFT functionality.
* ``pyqed.qchem.dft`` contains native DFT and grid functionality.
* ``pyqed.qchem.semiempirical`` contains semiempirical method interfaces,
  including the in-progress OM2/MRCI API.
* ``pyqed.qchem.dmrg`` contains DMRG and spin-adapted/non-Abelian development
  paths.
* ``pyqed.gw`` contains dense molecular GW, eigenvalue-self-consistent GW,
  qsGW, and BSE reference implementations.

Integral Backends
-----------------

The molecular build step can use different integral representations depending
on the calculation:

* ``driver="builtin"`` uses the native integral path.
* ``eri="auto"`` uses compact eight-fold exact storage for small systems and
  prefers native RI factors for larger systems when an auxiliary basis is
  available.
* ``eri="dense", aosym="s1"`` stores the four-index electron repulsion tensor
  explicitly.
* ``eri="dense", aosym="s4"`` stores the tensor in unique AO-pair form.
* ``eri="dense", aosym="s8"`` stores only unique AO-pair-pair values,
  exploiting the full eight-fold ERI permutation symmetry for memory.
* ``eri="direct"`` avoids dense AO ERI construction and uses compact ``s8``
  storage for cartesian J/K builds.
* ``eri="factors"`` stores a Cholesky/factorized representation when available.
* ``eri="dense+factors"`` keeps both representations for algorithms that need
  dense tensors and factorized contractions.
* ``eri="ri"`` builds native density-fitting factors from bundled auxiliary
  basis sets, without using PySCF. The default ``ri_purpose="jk"`` prefers
  JKFIT sets for SCF when available; use ``options={"ri_purpose": "ri"}`` to
  prefer RIFIT sets for correlation-style fitting.
* ``eri="dense+ri"`` keeps the dense tensor and the native RI factors.

Auxiliary bases can be selected explicitly:

.. code-block:: python

   mol.build(
       driver="builtin",
       eri="ri",
       auxbasis="cc-pvdz-rifit",
   )

The Cholesky and RI paths are useful for larger active-space and CASSCF
workflows because they avoid materializing dense transformed electron-repulsion
tensors when the solver can contract directly with factors. Cholesky factors
are an exact low-rank decomposition of the AO ERI tensor up to the selected
tolerance; RI factors are an auxiliary-basis approximation. Native RI builds
three-center tensors in packed AO-pair form, uses full factor storage by default
for the current faster RHF contraction path, supports ``ri_storage="packed"``
for memory-sensitive runs, applies a Cholesky-first metric solve with an
eigenvalue fallback, and supports optional three-center screening via
``ri_screen_tol``.

Multiconfigurational Methods
----------------------------

PyQED includes native CASCI/CASSCF implementations, including factorized
integral support and second-order orbital optimization paths. See the
dedicated guide for examples:

.. toctree::
   :maxdepth: 1

   guide/guide_qchem_mcscf
   guide/guide_qchem_om2_mrci

Related Topics
--------------

* :doc:`dvr`
* :doc:`backends`
* :doc:`examples`
* :doc:`hf_analysis`
* :doc:`mp2_comp2`
* :doc:`gw_bse`
* :doc:`tddft_ehrenfest`
* :doc:`qchem_architecture`
* :doc:`mps`
* :doc:`nonabelian_dmrg_design`