Quickstart
==========

XC calculation (B3LYP)
----------------------

.. code-block:: python

   import numpy as np
   import gauxc as gxc
   from gauxc import tools
   from pyscf import gto, scf

   # Build an H2O molecule using PySCF
   hoh = gto.Mole()
   hoh.atom = '''
   O  0.000000  0.000000  0.000000
   H  0.000000 -0.757160  0.586260
   H  0.000000  0.757160  0.586260
   '''
   hoh.basis = 'def2-svp'
   hoh.build()

   # Build a basis set
   mol = gxc.tools.get_mol(hoh)
   basis = gxc.tools.get_basis(hoh)

   # Make a molecular grid for numerical integration
   grid = gxc.Molgrid(mol, quality=gxc.GridQuality.FineGrid)

   # Initialize an integrator for the RKS XC calculation
   integrator = gxc.Integrator(
       gxc.ExecutionSpace.Host,
       mol, basis, grid,
       func_names=['HYB_GGA_XC_B3LYP'],
       func_coeffs=[1.0]
   )

   # Compute the XC energy and potential
   density = np.eye(basis.nao) # Some density matrix for closed-shell KS DFT
   exc, vxc = integrator.compute_vxc(density)

Exact exchange calculation
--------------------------

.. code-block:: python

   integrator = gxc.Integrator(gxc.ExecutionSpace.Host, mol, basis, grid)
   K_matrix = integrator.compute_k(density, tol_e=1e-10, tol_k=1e-10)

.. note::
   When working with hybrid functionals you can reuse the integrator instance
   from the XC calculation


GPU execution
-------------
To run on GPU, use ``ExecutionSpace.Device``.

It is highly recommended to manually set ``nbytes`` or
``fill_fraction`` to avoid GauXC allocating too much GPU memory: the default
is to allocate 70% of the currently unoccupied memory on the device. Example: allocate 8 GiB:

.. code-block:: python

   integrator = gxc.Integrator(
       gxc.ExecutionSpace.Device,
       mol, basis, grid,
       func_names=['HYB_GGA_XC_B3LYP'],
       func_coeffs=[1.0],
       nbytes=8*1024**3
   )