Jengine
=======

Overview
--------
Jengine is the density-fitted Coulomb ("J") engine for computing Coulomb
matrices, potentials and gradients using an auxiliary (density-fitting) basis.
The J-engine accepts primary and auxiliary libintx.Basis objects and a two-center
auxiliary metric :math:`V = (P|Q)` and uses an internal DFSolver that applies :math:`V^{-1}`
to vectors.

Constructor
-----------

.. code-block:: python

   Jengine(basis, aux_basis, V,
           vinv_type='cholesky', vinv_device='cuda',
           vinv_mem_fraction=0.5)

Parameters
----------
* **basis** *(libintx.Basis)* - primary basis (collection of Gaussian shells).
* **aux_basis** *(libintx.Basis)* - auxiliary basis used for density fitting.
* **V** *(ndarray, shape (naux, naux))* - two-center metric :math:`(P|Q)`.
* **vinv_type** *(str)* - solver type: ``"cholesky" | "lu" | "cholesky_inv" | "cholesky_mp"``.
* **vinv_device** *(str)* - computation device: ``"cuda"`` or ``"host"``.
* **vinv_mem_fraction** *(float)* - max fraction of GPU memory used by the solver (default ``0.5``).

Properties
----------
* ``basis``, ``aux_basis`` - read-only.
* ``nao`` - number of atomic orbitals in primary basis.
* ``naux`` - number of auxiliary AOs.
* ``vinv`` - internal :class:`libintx.DFSolver` instance.
* ``cutoff`` - screening cutoff (get/set) when screening is configured.

Methods
-------
* ``set_screening(pp, ijij, cutoff=1e-20)`` - configure Schwarz-type ERI screening:
  * **pp** (naux) - per-aux-shell screening estimates.
  * **ijij** (nsh x nsh) - per-shell-pair estimates for the primary basis.
* ``compute_j(D, scale=0.5)`` - compute the Coulomb matrix :math:`J` (returns row-major symmetric matrix).
* ``compute_pot(D)`` - compute Coulomb potential vector :math:`\sum_{kl}(P|kl) D_{kl}`.
* ``compute_jgrad(D)`` - compute gradients; returns a tuple `(Jgrad, X, Xgrad)`.

Notes
-----
* The default scaling ``scale=0.5`` corresponds to the RHF PySCF convention.
* The J-engine uses a DFSolver object to represent the :math:`V^{-1}` operator which
  may execute on GPU or host depending on the constructor arguments.