.. _sphx_glr_examples_dispersion:

Dispersion Interactions
=======================

Examples demonstrating GPU-accelerated computation of DFT-D3
dispersion corrections with environment-dependent C6 coefficients.

These examples show how to:

* Compute dispersion energies and forces for molecules
* Process batches of crystal structures
* Integrate with PyTorch for differentiable workflows

Examples 01 to 03 use the direct real-space ``dftd3``, which handles molecules and
open boundary conditions.

Examples 04 and 05 use ``fourier_dftd3``, which evaluates the correction on a
particle mesh with no pair cutoff on the dispersion sum. It is **periodic only**,
so both are crystal examples --- a CsCl cell built from the published DFT-D3
tables:

* ``04_fourier_dftd3_crystal.py`` --- the Torch API, and how to check mesh
  sensitivity
* ``05_jax_fourier_dftd3_crystal.py`` --- the JAX API under ``jax.jit``


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to compute the DFT-D3 dispersion energy and forces for a single molecular system using GPU-accelerated kernels.">

.. only:: html

  .. image:: /examples/dispersion/images/thumb/sphx_glr_01_dftd3_molecule_thumb.png
    :alt:

  :doc:`/examples/dispersion/01_dftd3_molecule`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">DFT-D3 Dispersion Correction for a Molecule</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates GPU-accelerated DFT-D3 calculations for batches of periodic crystal structures. Batch processing is essential for high-throughput computational materials screening and allows efficient parallelization across multiple structures simultaneously.">

.. only:: html

  .. image:: /examples/dispersion/images/thumb/sphx_glr_02_dftd3_batch_crystals_thumb.png
    :alt:

  :doc:`/examples/dispersion/02_dftd3_batch_crystals`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">DFT-D3 Dispersion Correction for Batched Crystals</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to compute the DFT-D3 dispersion energy and forces for a single molecular system using the JAX API with GPU-accelerated Warp kernels.">

.. only:: html

  .. image:: /examples/dispersion/images/thumb/sphx_glr_03_jax_dftd3_molecule_thumb.png
    :alt:

  :doc:`/examples/dispersion/03_jax_dftd3_molecule`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">JAX DFT-D3 Dispersion Correction for a Molecule</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The DFT-D3 dispersion correction decays as 1/r^6. Summed over three dimensions that leaves a truncation error decaying only as 1/r^3, so converging it in real space needs a neighbour list far larger than a machine-learned force field&#x27;s own, and building that list comes to dominate the simulation step.">

.. only:: html

  .. image:: /examples/dispersion/images/thumb/sphx_glr_04_fourier_dftd3_crystal_thumb.png
    :alt:

  :doc:`/examples/dispersion/04_fourier_dftd3_crystal`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">FourierD3: Periodic Particle-Mesh Dispersion</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="FourierD3 evaluates the DFT-D3(BJ) correction on a particle mesh, so the dispersion sum carries no pair cutoff. The one real-space cutoff that remains is the short coordination-number list. The JAX binding is the counterpart of nvalchemiops.torch.interactions.dispersion.fourier_dftd3, and the argument list is the same minus device.">

.. only:: html

  .. image:: /examples/dispersion/images/thumb/sphx_glr_05_jax_fourier_dftd3_crystal_thumb.png
    :alt:

  :doc:`/examples/dispersion/05_jax_fourier_dftd3_crystal`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">JAX FourierD3: Periodic Particle-Mesh Dispersion Under jax.jit</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/dispersion/01_dftd3_molecule
   /examples/dispersion/02_dftd3_batch_crystals
   /examples/dispersion/03_jax_dftd3_molecule
   /examples/dispersion/04_fourier_dftd3_crystal
   /examples/dispersion/05_jax_fourier_dftd3_crystal