Written basic plumed documentation for metatensor

A page with a description of the module will now appear in the manual as well as a page describing the action

src/metatensor/metatensor.cpp

@@ -12,6 +12,35 @@
 #include "core/ActionRegister.h"
 #include "core/PlumedMain.h"
 
+//+PLUMEDOC METATENSOR_COLVAR METATENSOR
+/*
+Use metatensor to calculate a CV.  
+
+For more details of how to use metatensor visit [the metatensor website](https://lab-cosmo.github.io/metatensor/latest/).
+
+\par Examples
+
+The following input shows how you can call metatensor and evaluate the model that is described in the file soap_cv.pt from PLUMED.
+To evluate this model plumed is required to use code that is included in the directory extensions which has been specified using the EXTENSIONS_DIRECTORY flag.
+Numbered SPECIES labels are used to indicate the list of indices that belong to each atomic species in the model.  The 
+SPECIES_TO_TYPE keyword then provies information on the atom type for each species.  The first number here is the atomic number of the atoms
+that have been speciefied using the SPECIES1 flag, the second number is the atomic number of the atoms that have been specified using the SPECIES2 flag and so on.
+
+\plumedfile
+oap: METATENSOR ...
+      MODEL=soap_cv.pt
+      EXTENSIONS_DIRECTORY=extensions
+
+      SPECIES1=1-26
+      SPECIES2=27-62
+      SPECIES3=63-76
+      SPECIES_TO_TYPES=6,1,8
+...
+\endplumedfile
+
+*/
+//+ENDPLUMEDOC
+
 
 #if !defined(__PLUMED_HAS_LIBTORCH) || !defined(__PLUMED_HAS_METATENSOR)
 

src/metatensor/README.md → user-doc/METATENSOR.md

@@ -1,26 +1,38 @@
-# Metatensor module for PLUMED
+\page metatensor Metatensor interface 
 
+<!--
+description: Module that implements interface with metatensor 
+authors: Guillaume Fraux
+reference: 
+-->
 
-## Building the code
+The metatensor module allows one to call metatensor, which is a specialized dat storage format for atomistic machine learning, from PLUMED.
+You can learn more about metatensor by reading [the metatensor manual](https://lab-cosmo.github.io/metatensor/latest/).
 
-1. You'll need to fist install libtorch, either by installing PyTorch itself
-   with Python, or by downloading the prebuilt C++ library from
-   https://pytorch.org/get-started/locally/.
+To use metatensor from plumed you use the \ref METATENSOR action.
 
-```bash
+\section metatensor-build Building PLUMED with metatensor
+
+You'll need to fist install libtorch, either by installing PyTorch itself
+with Python, or by downloading the prebuilt C++ library from
+[here](https://pytorch.org/get-started/locally/).  Once you have installed libtorch you 
+need to set the following options in bash.
+
+\verbatim
 # point this to the path where you extracted the C++ libtorch
 TORCH_PREFIX=../../..
 # if you used Python to install torch, you can do this:
 TORCH_CMAKE_PREFIX=$(python -c "import torch; print(torch.utils.cmake_prefix_path)")
 TORCH_PREFIX=$(cd "$TORCH_CMAKE_PREFIX/../.." && pwd)
 
 TORCH_INCLUDES="-I$TORCH_PREFIX/include -I$TORCH_PREFIX/include/torch/csrc/api/include"
-```
+\endverbatim
 
-2. a) build and install metatensor-torch from source. You'll need a rust
-      compiler on your system, the easiest way is by using https://rustup.rs/
+You can then either build and install metatensor-torch from source. You'll need a rust
+compiler on your system.  The easiest way to install a rust compiler is to use [the following site](https://rustup.rs/).
+Once the rust compiler is installed you should then follow the instructions that follow: 
 
-```bash
+\verbatim
 # patch a bug from torch's MKL detection
 cd <PLUMED/DIR>
 ./src/metatensor/patch-torch.sh "$TORCH_PREFIX"
@@ -44,21 +56,22 @@ cmake -DBUILD_SHARED_LIBS=ON \
       ..
 
 cmake --build . --target install --parallel
-```
+\endverbatim
 
-2. b) alternatively, use metatensor-torch from Python (`pip install metatensor[torch]`)
+Instead of doing the above, you can alternatively, use metatensor-torch from Python (`pip install metatensor[torch]`).
+Once the installation has completed you then enter the following commands:
 
-```bash
+\verbatim
 METATENSOR_CMAKE_PREFIX=$(python -c "import metatensor; print(metatensor.utils.cmake_prefix_path)")
 METATENSOR_PREFIX=$(cd "$METATENSOR_CMAKE_PREFIX/../.." && pwd)
 
 METATENSOR_TORCH_CMAKE_PREFIX=$(python -c "import metatensor.torch; print(metatensor.torch.utils.cmake_prefix_path)")
 METATENSOR_TORCH_PREFIX=$(cd "$METATENSOR_TORCH_CMAKE_PREFIX/../.." && pwd)
-```
+\endverbatim
 
-3. build Plumed itself
+Once these two steps are completed you can then install plumed itself using the following commands:
 
-```bash
+\verbatim
 cd <PLUMED/DIR>
 
 # set the rpath to make sure plumed executable will be able to find the right libraries
@@ -78,7 +91,7 @@ RPATH="-Wl,-rpath,$TORCH_PREFIX/lib -Wl,-rpath,$METATENSOR_PREFIX/lib -Wl,-rpath
     CXXFLAGS="-D_GLIBCXX_USE_CXX11_ABI=0"
 
 make -j && make install
-```
+\endverbatim
 
 
 <!-- TODO: explain vesin update process -->