update docs

Author: svandenhaute

docs/execution.md

@@ -101,7 +101,7 @@ In addition, it ensures that all nontrivial operations are executed using psiflo
 ---
 container:
   engine: 'apptainer'
-  uri: 'oras://ghcr.io/molmod/psiflow:3.0.0-cuda'
+  uri: 'oras://ghcr.io/molmod/psiflow:3.0.0_python3.9_cuda'
 ModelEvaluation:
   cores_per_worker: 1
   simulation_engine: 'yaff'
@@ -125,7 +125,7 @@ As an example of this, consider the following configuration:
 ---
 container:
   engine: "apptainer"
-  uri: "oras://ghcr.io/molmod/psiflow:2.0.0-cuda"
+  uri: "oras://ghcr.io/molmod/psiflow:3.0.0_python3.9_cuda"
 ModelEvaluation:
   cores_per_worker: 1
   simulation_engine: 'openmm'
@@ -154,6 +154,7 @@ ModelTraining:
     scheduler_options: "#SBATCH --clusters=dodrio\n#SBATCH --gpus=1\n"
 ReferenceEvaluation:
   max_walltime: 20
+  cpu_affinity: "alternating"  # avoid performance decrease in CP2K
   SlurmProvider:
     partition: "cpu_rome"
     account: "2022_069"

docs/index.md

@@ -16,13 +16,26 @@ To achieve this, psiflow implements the following high-level abstractions:
 - one or more **phase space sampling** algorithms (e.g. biased NPT, geometry optimization)
 - a reference **level of theory** (e.g. CP2K using PBE-D3(BJ) + TZVP)
 
+
 These three components are used to implement **online learning** algorithms,
 which essentially interleave phase space sampling with
 quantum mechanical energy evaluations and model training.
 In this way, the entire (relevant part of the) phase space of the system(s)
 of interest may be explored and learned by the model without ever having to
 perform *ab initio* molecular dynamics.
 
+!!! success  "**See what it looks like on [Weights & Biases](https://wandb.ai/svandenhaute/formic_acid?workspace=user-svandenhaute)!**"
+
+    The main channel through which you will analyze psiflow's output is Weights & Biases.
+    Click [here](https://wandb.ai/svandenhaute/formic_acid?workspace=user-svandenhaute)
+    to check out a few completed runs, in which we learn the energetics of the molecular
+    proton transfer reaction in a formic acid dimer!
+    For more information on the example as well as a full walkthrough on how to obtain
+    the reaction free energy based on a single input structure as starting point, check out the 
+    Jupyter [notebook](https://github.com/molmod/psiflow/blob/main/examples/notebook/tutorial.ipynb).
+
+---
+
 <!---
 ## Core functionality 
 
@@ -63,6 +76,7 @@ the definition of the computational graph itself.
 For more information, check out the psiflow [Configuration](config.md) page.
 --->
 
+
 !!! note "Citing psiflow"
 
     Psiflow is developed at the
@@ -657,7 +671,32 @@ reference.add_file('potential', 'POTENTIAL_UZH')
 reference.add_file('dftd3', 'dftd3.dat')
 ```
 
-### NWChem
+### PySCF
+The `PySCFReference` expects a string representation of the Python code that should be executed.
+You may assume that this piece of code will be executed in a larger Python script in which the correct
+PySCF `molecule` object has been initialized. The script should define the `energy` and `forces` Python
+variables (respectively `float` and `numpy.ndarray`) which should contain the energy and negative gradient
+in atomic units.
+
+See below for an example:
+```py
+from psiflow.reference import PySCFReference
+
+routine = """
+from pyscf import dft
+
+mf = dft.RKS(molecule)
+mf.xc = 'pbe,pbe'
+
+energy = mf.kernel()
+forces = -mf.nuc_grad_method().kernel()
+"""
+basis = 'cc-pvtz'
+spin = 0
+reference = PySCFReference(routine, basis, spin)
+```
+
+### NWChem (deprecated)
 For nonperiodic systems, psiflow provides an interface with [NWChem](https://nwchemgit.github.io/Home.html),
 which implements a plethora of DFT and post-HF methods for both periodic and nonperiodic systems.
 The `NWChemReference` class essentially wraps around the ASE calculator, and is similarly easy to use:

docs/installation.md

@@ -10,17 +10,18 @@ the main dependencies according to how they are used in psiflow:
 | --------------------  | --------  | -------   | :---------------: | :--------:  |
 | **QM evaluation**         | CP2K      | 2023.1    |  | :material-check: |
 |                       | NWChem    | 7.2       |  | :material-check: |
+|                       | PySCF     | 2.4       |  | |
 | **trainable potentials**  | MACE      | 0.2.0     | :material-check:  |
 |                       | NequIP    | 0.5.6     | :material-check:  |
 |                       | Allegro   | 0.2.0     | :material-check:  |
 | **molecular dynamics**| OpenMM    | 8.0       | :material-check:  |
 |                       | PLUMED    | 2.9.0     |  |
 |                       | YAFF      | 1.6.0     |  |
-| **miscellaneous**     | Parsl     | 2023.8.28 |  |
+| **miscellaneous**     | Parsl     | 2023.10.23 |  |
 |                       | e3nn      | 0.4.4     | :material-check:  |
 |                       | PyTorch   | 1.13.1    | :material-check:  |
 |                       | ASE       | 3.22.1    |  |
-|                       | Pymatgen  | 2023.8.10 |  |
+|                       | Pymatgen  | 2023.11.12 |  |
 |                       | wandb     | 0.15.8    |  |
 |                       | Python    | 3.9       |  |
 
@@ -47,9 +48,9 @@ Python environment requires barely anything, and is straightforward to install
 using `micromamba` -- a blazingly fast drop-in replacement for `conda`:
 
 ```console
-micromamba create -n psiflow_env -c conda-forge -y python=3.9 ndcctools=7.6.1 
+micromamba create -n psiflow_env -c conda-forge -y python=3.9
 micromamba activate psiflow_env
-pip install git+https://github.com/molmod/psiflow
+pip install parsl==2023.10.23 git+https://github.com/molmod/psiflow
 ```
 That's it! Before running actual calculations, it is still necessary to set up Parsl
 to use the compute resources you have at your disposal -- whether it's a local GPU,
@@ -61,15 +62,15 @@ a SLURM cluster, or a cloud computing provider; check out the
     Apptainer -- now the most widely used container system for HPCs -- is part of the
     Linux Foundation. It is easy to set up on most Linux distributions, as explained in the [Apptainer documentation](https://apptainer.org/docs/admin/main/installation.html#install-ubuntu-packages).
 
-    Psiflow's containers are hosted on the GitHub Container Registry (GHCR).
+    Psiflow's containers are hosted on the GitHub Container Registry (GHCR), for both Python 3.9 and 3.10.
     To download and run commands in them, simply execute:
 
     ```console
     # show available pip packages
-    apptainer exec oras://ghcr.io/molmod/psiflow:2.0.0-cuda11.8 /usr/local/bin/entry.sh pip list
+    apptainer exec oras://ghcr.io/molmod/psiflow:3.0.0_python3.9_cuda /usr/local/bin/entry.sh pip list
 
     # inspect cp2k version
-    apptainer exec oras://ghcr.io/molmod/psiflow:2.0.0-cuda11.8 /usr/local/bin/entry.sh cp2k.pmsp --version
+    apptainer exec oras://ghcr.io/molmod/psiflow:3.0.0_python3.9_cuda /usr/local/bin/entry.sh cp2k.pmsp --version
     ```
 
     Internally, Apptainer will store the container in a local cache directory such that it does not have to
@@ -131,4 +132,4 @@ pip install git+https://github.com/acesuit/MACE.git@55f7411 && \
     pip install git+https://github.com/svandenhaute/openmm-ml.git@triclinic
 pip install git+https://github.com/molmod/psiflow
 ```
-This is mostly a copy-paste from psiflow's [Dockerfile](https://github.com/molmod/psiflow/blob/main/Dockerfile).
+This is mostly a copy-paste from psiflow's [Dockerfiles](https://github.com/molmod/psiflow/blob/main/container).

docs/learning.md

@@ -92,7 +92,7 @@ The following keyword arguments are specific to `SequentialLearning`:
 
 - `niterations: int` : the number of active learning iterations to perform. Each iterations starts with phase space
 sampling, followed by reference evaluation and model training.
-- `temperature_ramp: Optional[tuple[float]] = None`: (new in v2.0.0) whether to gradually increase the temperature of the walkers 
+- `temperature_ramp: Optional[tuple[float, float, float]] = None`: (new in v2.0.0) whether to gradually increase the temperature of the walkers 
 over a certain number of iterations. If not `None`, this keyword argument expects a tuple of floats: (initial T, final T, nsteps).
 If this is `None`, then the temperature of the walkers is left as-is. 
 - `error_thresholds_for_reset: tuple[float, float] = (10, 200)` : (new in v2.0.0) determines the (energy, force)