From 68a5a29e2aa7b348fffd489971b2f02948fcec84 Mon Sep 17 00:00:00 2001 From: svdenhau Date: Tue, 21 Nov 2023 19:27:14 +0100 Subject: [PATCH] update docs --- docs/execution.md | 5 +++-- docs/index.md | 41 ++++++++++++++++++++++++++++++++++++++++- docs/installation.md | 17 +++++++++-------- docs/learning.md | 2 +- 4 files changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/execution.md b/docs/execution.md index cb13489..c0cd7d1 100644 --- a/docs/execution.md +++ b/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" diff --git a/docs/index.md b/docs/index.md index 1086026..7c31780 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,7 @@ 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. @@ -23,6 +24,18 @@ 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). + +--- + + !!! 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: diff --git a/docs/installation.md b/docs/installation.md index d819593..343e313 100644 --- a/docs/installation.md +++ b/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). diff --git a/docs/learning.md b/docs/learning.md index ffa505a..2110701 100644 --- a/docs/learning.md +++ b/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)