Merge branch 'main' into update_doc

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

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

@@ -224,6 +224,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

@@ -435,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

docs/src/introduction.rst

@@ -27,6 +27,7 @@ A schematic representation of the code structure and the server-client communica
 
 .. figure:: ../figures/ipi-structure-v3.*
    :width: 90.0%
+   :class: white-background
 
    Figure 1. Schematic representation of the i-PI code structure and the server-client communication.
 
@@ -81,6 +82,7 @@ machinery in i-PI might appear complicated at first, and deserves a
 brief discussion.
 
 .. figure:: ../figures/ipi-forces.*
+   :class: white-background   
    :width: 90.0%
 
    Schematic representation of the different objects that
@@ -146,6 +148,7 @@ a “depend” object class, which is given the parameters on which it
 depends and a function used to calculate its value.
 
 .. figure:: ../figures/ipi-depend.*
+   :class: white-background   
    :width: 90.0%
 
    Schematic overview of the functioning of the