move some text and images from paper to docs

Author: PicoCentauri

README.rst

@@ -9,14 +9,13 @@ torch-pme
 
 .. marker-introduction
 
-``torch-pme`` enables efficient, auto-differentiable computation of long-range
+``torch-pme`` enables efficient and auto-differentiable computation of long-range
 interactions in *PyTorch*. Auto-differentiation is supported for particle *positions*,
-*charges*, and *cell* parameters, allowing not only the automatic computation of forces
-but also enabling general applications in machine learning tasks. The library offers
-classes for Particle-Particle Particle-Mesh Ewald (``P3M``), Particle Mesh Ewald (``PME``),
-standard ``Ewald``, and non-periodic methods, with the flexibility to calculate
-potentials beyond :math:`1/r` electrostatics, including arbitrary order :math:`1/r^p`
-potentials.
+*charges*, and *cell* parameters, allowing not only the computation of forces but also
+enabling general applications in machine learning tasks. The library offers classes for
+Particle-Particle Particle-Mesh Ewald (``P3M``), Particle Mesh Ewald (``PME``), standard
+``Ewald``, and non-periodic methods, with the flexibility to calculate potentials beyond
+:math:`1/r` electrostatics, including arbitrary order :math:`1/r^p` potentials.
 
 Optimized for both CPU and GPU devices, ``torch-pme`` is fully `TorchScriptable`_,
 allowing it to be converted into a format that runs independently of Python, such as in
@@ -55,8 +54,8 @@ or conda
 
 and ``import torchpme`` to use it in your projects!
 
-We also provide bindings to `metatensor <https://docs.metatensor.org>`_ which
-can optionally be installed together and used as ``torchpme.metatensor`` via
+We also provide bindings to `metatensor <https://docs.metatensor.org>`_ which can
+optionally be installed together and used as ``torchpme.metatensor`` via
 
 .. code-block:: bash
 

docs/src/about.rst

@@ -1,15 +1,39 @@
 What is torch-pme
 =================
 
-``torch-pme`` provides an interface in which the positions of the atoms in a structure
-are stored in :class:`torch.Tensor` objects, or in a :class:`metatensor.System
+``torch-pme`` provides an interface in which the ``positions`` of the atoms in a
+structure are stored in :class:`torch.Tensor` objects, or in a :class:`metatensor.System
 <metatensor.torch.atomistic.System>` object.
 
-torch-pme can be used as an end-to-end library computing the potential from
-positions/charged and as a modular library to construct complex Fourier-domain
-architectures.
+The primary goal is to design a library to compute long-range interactions that can be
+easily integrated with existing short-range machine learning (ML) architectures,
+essentially providing an easy-to-use framework to build range separated models for
+atomistic machine learning. To this end, our reference ``torch-pme`` library provides
 
-To use ``torch-pme`` as an end-to-end library the main entry point are
+1. A modular implementation of range-separated potentials working for arbitrary unit
+   cells including triclinic ones, as well as for systems with free (non-prediodic)
+   boundary condistions.
+2. Full integration with PyTorch, featuring differentiable and learnable parameters,
+3. Efficient particle-mesh-based computation with automatic hyperparameter tuning,
+4. Pure long-range descriptors, free of noisy short-range contributions,
+5. Support for arbitrary invariant and equivariant features and ML architectures.
+
+``torch-pme`` can be used as an *end-to-end* library computing the potential from
+positions and charges and as a *modular* library to construct complex Fourier-domain
+architectures. To use ``torch-pme`` as an end-to-end a library the main entry points are
 :ref:`calculators`, that compute pair :ref:`potentials` combining real-space and k-space
 components. They take a description of a structure as input and return the calculated
-potential at the atomic positions as output.
+potential at the atomic positions as output. To use torch-pme as a modular library, we
+provide a set of building blocks that can be combined to build custom range-separated
+architectures, as shown in the figure below.
+
+.. figure:: ../static/images/pme-structure.*
+    :width: 650px
+    :align: center
+
+    A schematic representation of the main building blocks that are contained inside a
+    :ref:`calculators` of a range-separated architecture, that combines an evaluation of
+    the short-range part of the :ref:`potentials` :math:`v_\mathrm{SR}(r)` based on
+    local interatomic distance information with the evaluation of the long-range part
+    :math:`v_\mathrm{LR}(k)` using grids via a :ref:`mesh_interpolator` and a
+    :ref:`kspace_filter`.

docs/src/references/lib/kspace_filter.rst

@@ -1,3 +1,5 @@
+.. _kspace_filter:
+
 Kspace filter
 #############
 

docs/src/references/lib/mesh_interpolator.rst

@@ -1,3 +1,5 @@
+.. _mesh_interpolator:
+
 Mesh Interpolator
 #################