Merge branch 'main' into better-plumed

README.md

@@ -1,10 +1,9 @@
-i-PI: a Universal Force Engine
-==============================
+# i-PI: a Universal Force Engine
 
 A Python interface for ab initio path integral molecular dynamics simulations (and more).
-i-PI is a Python server (that does not need to be compiled and only requires a relatively 
-recent version of Python and Numpy) that applies an algorithm to update the positions of 
-the nuclei. One of many compatible external codes acts as client, and computes the 
+i-PI is a Python server (that does not need to be compiled and only requires a relatively
+recent version of Python and Numpy) that applies an algorithm to update the positions of
+the nuclei. One of many compatible external codes acts as client, and computes the
 electronic energy and forces.
 
 This is typically a patched version of an electronic structure code, but a
@@ -13,17 +12,17 @@ potentials is included for test purposes.
 
 i-PI was originally developed to simulate the quantum mechanical nature of light
 nuclei by performing path integral molecular dynamics simulations,
-and it implements most of the state-of-the-art methods to accelerate this kind of 
-calculations. It has since grown to also provide all sorts of simulation 
-strategies, from replica exchange to geometry optimization. 
+and it implements most of the state-of-the-art methods to accelerate this kind of
+calculations. It has since grown to also provide all sorts of simulation
+strategies, from replica exchange to geometry optimization.
 
 If you use i-PI in your research, please cite the accompanying publication:
-for version 3, the relevant paper is 
-[Litman et al., *J. Chem. Phys.* 161, 062504 (2024)](https://doi.org/10.1063/5.0215869)
+for version 3, the relevant paper is
+[Litman et al., _J. Chem. Phys._ 161, 062504 (2024)](https://doi.org/10.1063/5.0215869)
 
 ```
 @article{litman2024ipi,
-title={i-PI 3.0: a flexible and efficient framework for advanced atomistic simulations},     
+title={i-PI 3.0: a flexible and efficient framework for advanced atomistic simulations},
 author={Yair Litman and Venkat Kapil and Yotam M. Y. Feldman and Davide Tisi and Tomislav Begušić and Karen Fidanyan and Guillaume Fraux and Jacob Higer and Matthias Kellner and Tao E. Li and Eszter S. Pós and Elia Stocco and George Trenins and Barak Hirshberg and Mariana Rossi and Michele Ceriotti},
 journal = {J. Chem. Phys.},
 pages   = {062505},
@@ -32,8 +31,7 @@ year    = {2024}
 }
 ```
 
-Quick Setup
------------
+## Quick Setup
 
 To use i-PI with an existing driver, install and update using `pip`:
 
@@ -49,8 +47,11 @@ Last Release:
 pip install -U ipi
 ```
 
-Source installation
--------------------
+## Documentation 
+
+You can find the online documentation at [https://docs.ipi-code.org](https://docs.ipi-code.org/). Alternatively, you can build it locally by following instructions in the `docs/README.md` file.
+
+## Source installation
 
 To develop i-PI or test it with the self-contained driver, follow these
 instructions. It is assumed that i-PI will
@@ -63,11 +64,10 @@ git clone https://github.com/i-pi/i-pi.git
 ```
 
 Source the environment settings file `env.sh` as `source env.sh` or `.
-env.sh`.  It is useful to put this in your `.bashrc` or other settings file if
+env.sh`. It is useful to put this in your `.bashrc` or other settings file if
 you always want to have i-PI available.
 
-
-### Compile the driver code
+## Compile the driver code
 
 The built-in driver requires a FORTRAN compiler, and can be built as
 
@@ -78,22 +78,22 @@ cd ../..
 ```
 
 There is also a Python driver available in `drivers/py`, which however has limited
-functionalities. 
+functionalities.
 
-### Examples and demos
+## Examples and demos
 
 The `examples` and `demos` folders contain inputs for many different types of
 calculations based on i-PI. Examples are typically minimal use-cases of specific
 features, while demos are more structured, tutorial-like examples that show how
-to realize more complex setups, and also provide a brief discussion of the 
+to realize more complex setups, and also provide a brief discussion of the
 underlying algorithms.
 
 To run these examples, you should typically start i-PI, redirecting the output to
 a log file, and then run a couple of instances of the driver code. The progress
 of the wrapper is followed by monitoring the log file with the `tail` Linux command.
 
 Optionally, you can make a copy of the directory with the example somewhere
-else if you want to keep the i-PI directory clean. For example
+else if you want to keep the i-PI directory clean. For example, after sourcing the `env.sh` file, 
 
 ```bash
 cd demos/para-h2-tutorial/tutorial-1/
@@ -105,7 +105,12 @@ tail -f log
 
 The monitoring can be interrupted with CTRL+C when the run has finished (5000 steps).
 
-### Run the automatic test suite
+## Tutorials and online resources
+
+The i-PI [documentation](https://docs.ipi-code.org/onlinereso.html) has a list of
+available tutorials, recipes and other useful online resources.
+
+## Run the automatic test suite
 
 The automatic test suite can be run by calling the i-pi-tests script.
 You need to have the `pytest` package installed
@@ -118,8 +123,7 @@ You may also need to install some dependencies, listed in `requirements.txt`.
 
 See more details in the README file inside the `ipi_tests` folder.
 
-Contributing
-------------
+## Contributing
 
 If you have new features you want to implement into i-PI, your contributions are much welcome.
 See `CONTRIBUTING.md` for a brief set of style guidelines and best practices. Before embarking

bin/i-pi

@@ -58,7 +58,7 @@ def main(fn_input, options):
             raise ImportError('Profiling requires the `yappi` package.')            
 
     # construct simulation based on input file
-    simulation = Simulation.load_from_xml(fn_input, request_banner=True, custom_verbosity=options.verbosity, sockets_prefix=options.sockets_prefix)
+    simulation = Simulation.load_from_xml(open(fn_input), request_banner=True, custom_verbosity=options.verbosity, sockets_prefix=options.sockets_prefix)
 
     # run the simulation
     simulation.run()

demos/2D-IR-Raman/noneqm-traj.py

@@ -175,7 +175,7 @@ def main(fn_input, options):
     tree.write(fn_input_noneqm)
 
     simulation = Simulation.load_from_xml(
-        fn_input_noneqm, request_banner=False, custom_verbosity=options.verbosity
+        open(fn_input_noneqm), request_banner=False, custom_verbosity=options.verbosity
     )
     spec.run(simulation, options.tfirst, options.tlast)
     softexit.trigger(status="success", message=" @ SIMULATION: Exiting cleanly.")

demos/te-pigs/1_dataset_curation/get_pigs_dataset.py

@@ -11,7 +11,6 @@
     iread(centroid_force_filename),
     iread(physical_force_filename),
 ):
-
     atoms = a_pos.copy()
 
     atoms.arrays["centroid_force"] = a_cforce.arrays["f_centroid"]

docs/README → docs/README.md

@@ -1,13 +1,12 @@
-i-PI documentation
-==================
+## i-PI documentation
 
-This folder contains the files needed to build the documentation for i-PI. 
+This folder contains the files needed to locally build the documentation for i-PI. 
 
 * `latex/`  contains the "legacy" TeX manual, that includes also autogenerated input reference
 * `scripts/`  contains automatic scripts to build the input reference
 * `src/` contains RST files that are compiled by sphynx into the HTML documentation.
 
 
-To make the docs, make sure you have all the needed packages in `requirements.txt` installed, and type `make html`. The local documentation will be generated in `_build/html`. 
+To make the docs, make sure you have all the needed packages in `requirements.txt` installed, which can be achieved with `pip install -r requirements.txt`, and type `make html`. The local documentation will be generated in `_build/html`. 
 
 To make the TeX docs follow the instructions in `latex`.

docs/_static/custom_styles.css

@@ -0,0 +1,8 @@
+figcaption {
+    font-style: italic; /* makes text italic */
+    font-size: 0.9em; /* reduces font size to 90% of the surrounding text */
+}
+
+img.white-background {
+    background-color: white;
+}

docs/latex/README.md

@@ -0,0 +1,45 @@
+
+## Documentation Directory
+
+This directory contains all the documentation for the program.
+
+### Directories
+
+- **figures**: Holds the figures used in the manual.
+- **input_docs**: Generated by the Makefile to hold the automatically generated input reference sections of the manual.
+
+### Files
+
+- `../scripts/create_man.py`: Python script that automatically generates LaTeX help files for all the classes, used in the manual.
+- `../scripts/help_list.py`: Python script to generate custom help files for the output classes, used in the manual.
+- `../scripts/help.py`: Python script to generate custom help files for each of the input classes, used in the manual.
+- `Makefile`: Makefile for generating the manual automatically.
+- `manual.tex`: TeX file serving as the template for the manual.
+- `mybib.bib`: Bibliography file for the manual.
+- `elsarticle-num-names.bst`: Bibliography style file.
+- `etoolbox.sty`: LaTeX package used by `manual.tex`.
+
+### Notes
+
+Some of the files listed above are used to automatically generate sections of the user manual and to create an XML file showing the class hierarchy. The sections of the user manual are generated in the `input_docs` directory. The user manual itself is created in two files:
+
+- **manual.pdf**: The main user manual file, explaining how to run the code, the syntax for input and output files, and the design paradigm for i-PI. It also contains a tutorial that goes step-by-step through an example calculation.
+- **manual.xml**: An XML file that contains all the input names, along with descriptions of their purpose and the expected values for each.
+
+### Commands
+
+- **Generate Help Files**:
+  ```bash
+  make
+  ```
+
+- **Clean Up (Remove Input Reference Sections and LaTeX Compiled Files)**:
+  ```bash
+  make clean
+  ```
+
+- **Full Clean (Remove All Generated Files)**:
+  ```bash
+  make distclean
+  ```
+

docs/requirements.txt

@@ -1,5 +1,6 @@
 sphinx >= 3.2
-jinja2 < 3.1
+jinja2
 sphinxcontrib-bibtex==2.1.4
 numpy
 pathlib
+furo

docs/scripts/help.py

@@ -68,6 +68,8 @@
     "dynamics": motion.dynamics.InputDynamics(),
     "constrained_dynamics": motion.constrained_dynamics.InputConstrainedDynamics(),
     "driven_dynamics": motion.driven_dynamics.InputDrivenDynamics(),
+    "bec": motion.driven_dynamics.InputBEC(),
+    "efield": motion.driven_dynamics.InputElectricField(),
     "csolver": motion.constrained_dynamics.InputConstraintSolver(),
     "constraint": motion.constrained_dynamics.InputConstraint(),
     "t_ramp": motion.ramp.InputTemperatureRamp(),
@@ -87,6 +89,7 @@
     "h0": cell.InputCell(),
     "forcefield": forcefields.InputForceField(),
     "ffsocket": forcefields.InputFFSocket(),
+    "ffdirect": forcefields.InputFFDirect(),
     "fflj": forcefields.InputFFLennardJones(),
     "ffdebye": forcefields.InputFFDebye(),
     "ffplumed": forcefields.InputFFPlumed(),

docs/src/conf.py

@@ -54,11 +54,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "agogo"
+html_title = "i-PI documentation pages"
+html_theme = "furo"
 html_theme_options = {
-    "rightsidebar": "false",
+    "top_of_page_buttons": [],
 }
-
+html_favicon = "../_static/favicon-ipi.png"
 html_logo = "../figures/ipi-logo.svg"
 
 html_css_files = [

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/distributed.rst

@@ -213,6 +213,7 @@ example above.
 .. _fig-network:
 
 .. figure:: ../figures/ipi-network.*
+   :class: white-background
    :width: 90.0%
 
    A schematic representation of the network layout one

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
@@ -415,6 +435,7 @@ nodes, and to queue and manage computational jobs.
 .. _fig-running:
 
 .. figure:: ../figures/ipi-running.*
+   :class: white-background   
    :width: 90.0%
 
    Different approaches to run i-PI and a number of