A "direct" FF using the same PES interfaces as the python driver (i-p…

…i#390)

This is a major restructuring of the python driver and the forcefield block. 
All PES drivers have been moved to an ipi/pes folder, and their API streamlined
with the possibility of providing both lists of arguments and named arguments.
A new FFDirect forcefield makes it possible to call the PES from i-PI directly, avoiding
the client/server setup that many find confusing. 
We converted most PES to the new interfaces, but several are possibly broken;
these now trigger a warning so that users can check and possibly fix them.


---------

Co-authored-by: Yair Litman <[email protected]>
Co-authored-by: Venkat Kapil <[email protected]>

docs/scripts/help.py

@@ -87,6 +87,7 @@
     "h0": cell.InputCell(),
     "forcefield": forcefields.InputForceField(),
     "ffsocket": forcefields.InputFFSocket(),
+    "ffdirect": forcefields.InputFFDirect(),
     "fflj": forcefields.InputFFLennardJones(),
     "ffdebye": forcefields.InputFFDebye(),
     "ffplumed": forcefields.InputFFPlumed(),

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

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

docs/src/index.rst

@@ -26,16 +26,16 @@ This documentation is structured as follows:
    :maxdepth: 2
 
    introduction
-   onlinereso
-   features
    getting-started
+   features
    units
    input-files
    input-tags
    output-files
    output-tags
    distributed
    tutorials
+   onlinereso
    faq
    troubleshooting
    contributing

drivers/py/driver.py

@@ -3,12 +3,8 @@
 import argparse
 import numpy as np
 
-
-try:
-    from pes import *
-except ImportError:
-    # when in an installed i-PI package
-    from ipi._driver.pes import *
+from ipi.pes import *
+from ipi.utils.io.inputs import read_args_kwargs
 
 description = """
 Minimal example of a Python driver connecting to i-PI and exchanging energy, forces, etc.
@@ -205,8 +201,8 @@ def run_driver(
         "--mode",
         type=str,
         default="dummy",
+        choices=list(__drivers__.keys()),
         help="""Type of potential to be used to compute the potential and its derivatives.
-                Currently implemented: [dummy, harmonic]
         """,
     )
     parser.add_argument(
@@ -227,10 +223,23 @@ def run_driver(
 
     args = parser.parse_args()
 
+    driver_args, driver_kwargs = read_args_kwargs(args.param)
+
     if args.mode in __drivers__:
-        d_f = __drivers__[args.mode](args.param, args.verbose)
+        try:
+            d_f = __drivers__[args.mode](
+                *driver_args, verbose=args.verbose, **driver_kwargs
+            )
+        except ImportError:
+            # specific errors have already been triggered
+            raise
+        except Exception as err:
+            print(f"Error setting up PES mode {args.mode}")
+            print(__drivers__[args.mode].__doc__)
+            print("Error trace: ")
+            raise err
     elif args.mode == "dummy":
-        d_f = Dummy_driver(args.param, args.verbose)
+        d_f = Dummy_driver(verbose=args.verbose)
     else:
         raise ValueError("Unsupported driver mode ", args.mode)