From 51121320b8fc65f2ab8e3289869992af9b28f48e Mon Sep 17 00:00:00 2001
From: Michele Ceriotti <michele.ceriotti@gmail.com>
Date: Tue, 12 Nov 2024 21:24:52 +0100
Subject: [PATCH] Added some docs for ffdirect

---
 docs/scripts/help.py         |  3 ++-
 docs/src/contributing.rst    |  8 +++++++-
 docs/src/getting-started.rst | 26 +++++++++++++++++++++++---
 docs/src/index.rst           |  4 ++--
 4 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/scripts/help.py b/docs/scripts/help.py
index 541281e7e..964fb9d39 100644
--- a/docs/scripts/help.py
+++ b/docs/scripts/help.py
@@ -87,7 +87,8 @@
     "h0": cell.InputCell(),
     "forcefield": forcefields.InputForceField(),
     "ffsocket": forcefields.InputFFSocket(),
-    "fflj": forcefields.InputFFLennardJones(),
+    "ffdirect": forcefields.InputFFDirect(),
+    "fflj": forcefields.InputFFLennardJones(),    
     "ffdebye": forcefields.InputFFDebye(),
     "ffplumed": forcefields.InputFFPlumed(),
     "ffyaff": forcefields.InputFFYaff(),
diff --git a/docs/src/contributing.rst b/docs/src/contributing.rst
index 7b2a9313d..32955b51c 100644
--- a/docs/src/contributing.rst
+++ b/docs/src/contributing.rst
@@ -1,3 +1,5 @@
+.. _contributing:
+
 Contributing
 ============
 
@@ -89,7 +91,11 @@ If your new development in i-PI is directly related to a specific client code or
 We very much welcome new interfaces and we will be happy to answer your questions. 
 
 If you want to enable the communication of a new client code with i-PI, it is not difficult: Please check an example of how it was  done in ``fortran`` and ``python`` in the `drivers` folder in the repository.
-
+It is especially simple to add a new potential energy that is evaluated in Python: it is sufficient to add a file in the `ipi/pes` folder, specifying 
+`__DRIVER_NAME__` (a string that will be used to refer to the PES from the i-PI input or the command line) and `__DRIVER_CLASS__`, the name of the 
+actual class, that should provide, directly or through inheritance, a `__call__(self, cell, pos)` function and return a tuple with
+`(potential, forces, virial, extras)`. See any of the existing PES files to use as templates - it is particularly simple to create a class that 
+piggybacs on an existing ASE-style calculator.
 
 
 Getting recognition for your contribution
diff --git a/docs/src/getting-started.rst b/docs/src/getting-started.rst
index fcc32010e..0d8c176ff 100644
--- a/docs/src/getting-started.rst
+++ b/docs/src/getting-started.rst
@@ -83,9 +83,29 @@ The built-in driver requires a FORTRAN compiler, and can be built as
    make
    cd ../..
 
+Python driver and PES
+^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the FORTRAN drive, the i-PI distribution contains also a Python 
+driver, available in `drivers/py` and through the command-line command 
+`i-pi-py_driver`, which evaluates potential energy surfaces evaluated by simple 
+driver classes, that can be found in `ipi/pes`. 
+
+These classes are particularly suitable to perform inference with machine-learning
+potentials implemented in Python, and it is reasonably simple to add your own,
+if you need to (see also the :ref:`contributing` section).
+
+These PES files can also be used directly, without the need to go through a 
+client-server interface, using a :ref:`ffdirect` forcefield, including in the
+XML input a block similar to 
+
+.. code-block::
+   
+   <ffdirect name="ff_name">
+      <pes> harmonic </pes>
+      <parameters> { k1: 1.0} </parameters>
+   </ffdirect>
 
-There is also a Python driver available in `drivers/py`, which however has limited
-functionalities.
 
 Alternative installation using the setup.py module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -266,7 +286,7 @@ The flags do the following:
 
 -S:
    Optional parameter. If given, overwrite the default socket prefix used in the creation of files for the socket communication.
-   (default "/tmp/ipi_")
+   (default "/tmp/ipi\_")
 
 This code should be fairly simple to extend to other pair-wise
 interaction potentials, and examples of its use can be seen in the
diff --git a/docs/src/index.rst b/docs/src/index.rst
index 37b4c4f72..a0eeb385d 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -26,9 +26,8 @@ This documentation is structured as follows:
    :maxdepth: 2
 
    introduction
-   onlinereso
-   features
    getting-started
+   features
    units
    input-files
    input-tags
@@ -36,6 +35,7 @@ This documentation is structured as follows:
    output-tags
    distributed
    tutorials
+   onlinereso
    faq
    troubleshooting
    contributing