Integrator
==========

Overview
--------
The :class:`gauxc.Integrator` is the main engine for XC and exact-exchange
computations. It supports RKS/UKS, gradients, and optional GPU execution.

Constructors
------------
Exact-exchange only:

.. code-block:: python

   Integrator(where, mol, basis, molgrid, nbytes=0, fill_fraction=0.7)

With XC:

.. code-block:: python

   Integrator(where, mol, basis, molgrid,
              func_names, func_coeffs,
              polar=False, nbytes=0, fill_fraction=0.7)

Parameters
----------
* **where** *(ExecutionSpace)* — Host or Device.
* **mol** *(Molecule)* — molecular geometry.
* **basis** *(Basis)* — Gaussian basis.
* **molgrid** *(Molgrid)* — quadrature grid.
* **func_names** *(list[str], optional)* — XC functional identifiers.
* **func_coeffs** *(list[float], optional)* — mixing coefficients.
* **polar** *(bool)* — UKS if ``True``.
* **nbytes** *(int)* — GPU memory (bytes); 0 means use ``fill_fraction``.
* **fill_fraction** *(float)* — fraction of available GPU memory (default 0.7).

Properties
----------
* ``polar``, ``func_names``, ``func_coeffs``, ``hfx_total``.
* GPU memory configuration via ``nbytes`` / ``fill_fraction``.

Methods
-------

compute_vxc (RKS)
-----------------
Compute XC energy and potential for closed-shell systems.

.. code-block:: python

   exc, vxc = integrator.compute_vxc(density, tol_xc=1e-12)

Parameters
* **density** *(ndarray, (N,N))* — AO density matrix.
* **tol_xc** *(float, optional)* — grid screening tolerance.

Returns
* **exc** *(float)* — XC energy (Hartree).
* **vxc** *(ndarray, (N,N))* — XC potential matrix.

compute_vxc (UKS)
-----------------
Compute XC for open-shell systems:

.. code-block:: python

   exc, vxc_alpha, vxc_beta = integrator.compute_vxc(density_alpha, density_beta)

compute_k
---------
Compute exact-exchange matrix:

.. code-block:: python

   K = integrator.compute_k(density, tol_e=1e-10, tol_k=1e-10)

compute_kder
------------
Compute nuclear gradients of the exact-exchange energy. Returns flattened
gradients by shell: shape ``(N_shells*3,)`` (pattern ``[x1,y1,z1,x2,y2,z2,...]``).

compute_exc_grad
----------------
Compute nuclear gradients of the XC energy. Returns ``(3, N_atoms)`` with
each column equal to ``[dE/dx, dE/dy, dE/dz]`` for an atom.

Notes
-----
* The K gradients are computed with respect to shell centers; users should
  assemble atomic gradients as required.
* For GPU runs, allocate sufficient memory via ``nbytes`` or ``fill_fraction``.