docs: revision SAG (#49)

* docs: index page review

* docs: cli page review

* docs: new benchmark page review

* docs: category split modification

* docs: stability docs review

* docs: scaling docs review

* docs: typo benchmarks index

* docs: conformers new figures

* docs: dihedral-scan reviewed

* docs: non-covalent interactions reviewed

* docs: ring-planarity reviewed

* docs: tautomers reviewed

* docs: minimization reviewed, new figure pending

* docs: bond length reviewed

* docs: reactivity reviewed

* docs: rdf molecular liquids reviewed

* docs: folding stability review 1

* docs: folding stability review 2

* docs: sampling reviewed

* docs: folding-stability index.rst typo

* docs: folding-stability index.rst typo 2

* docs: changes requestedby Christoph and Lucien

* docs: new minimization benchmark figure

* docs: slight improvements + grammar

* chore: linting

---------

Co-authored-by: lwalew <[email protected]>

Author: sacostagutz

docs/source/benchmarks/biomolecules/folding_stability/index.rst

@@ -6,20 +6,36 @@ Folding Stability Benchmark
 Purpose
 -------
 
-This benchmark evaluates the performance of a machine-learned interatomic potential
-(**MLIP**) in preserving the structural integrity of experimentally determined protein
+This benchmark evaluates the ability of a machine-learned interatomic potential
+(**MLIP**) to maintain the structural integrity of experimentally determined protein
 conformations during molecular dynamics (**MD**) simulations.
-Starting from an experimentally derived X-ray or NMR structure, the benchmark assesses
-the **MLIP** model ability to maintain the native protein fold throughout the simulation.
 
-Specifically, it evaluates the  maintain of the original protein fold, retention of
-secondary structure elements, and overall compactness across a set of known protein
-structures. This is quantified using various metrics, including  **RMSD**  (Root Mean Square Deviation),
-**TM-score** (Template Modeling score), **Secondary Structure matching** (using DSSP),
-and **Compactness** (radius of gyration analysis).
+Description
+-----------
+
+Starting from an experimentally derived X-ray or NMR structure, the benchmark performs an **MD** simulation using the **MLIP**
+model in the **NVT** ensemble at **300 K** for **100,000 steps** (100ps), leveraging the `jax-md <https://github.com/google/jax-md>`_,
+as integrated via the `mlip <https://github.com/instadeepai/mlip>`_ library, starting from a solvated structure.
 
+Performance is quantified using the following metrics:
 
+- Retention of the original protein fold, via **RMSD** and **TM-score**.
+- Retention of secondary structure elements, via **Secondary Structure matching** (using DSSP).
+- Overall compactness, via **Compactness** (radius of gyration analysis).
 
+For more information on each metric, please refer to the following pages:
+
+.. toctree::
+   :maxdepth: 1
+
+   RMSD & TM-score <folding_stability>
+   Compactness (Radius of gyration) <compactness>
+   Secondary Structure matching <secondary_structure>
+
+Dataset
+-------
+The dataset is composed by a series of protein structures taken from the `PDB <https://www.rcsb.org/>`_ databank.
+They have the following IDs:
 
 .. list-table::
    :widths: 25 25 25 25
@@ -43,43 +59,9 @@ and **Compactness** (radius of gyration analysis).
           :figclass: align-center
 
           Amyloid-beta (PDBid: 1BA6)
-     - .. figure:: ../img/1cq0.png
+     - .. figure:: ../img/hypocretin.png
           :width: 100%
           :align: center
           :figclass: align-center
 
           Hypocretin-2 (PDBid: 1CQ0)
-
-
-Dataset
--------
-
-TRP-cage (PDBid: 2JOF)
-
-Chignolin  (PDBid: 1UAO)
-
-Amyloid-beta  (PDBid: 1BA6)
-
-Hypocretin-2 (PDBid: 1CQ0)
-
-Description
------------
-
-The benchmark performs an **MD** simulation using the **MLIP** model in the **NVT**
-ensemble at **300 K** for **100,000 steps**,
-leveraging the `jax-md <https://github.com/google/jax-md>`_, as integrated via the
-`mlip <https://github.com/instadeepai/mlip>`_ library. The starting configuration is an
-experimentally determined structure (X-ray or NMR).
-
-For each system, the benchmark compares the following metrics to the reference structure
-for each trajectory frame.
-
-
-.. toctree::
-   :maxdepth: 1
-
-   Folding Stability (RMSD & TM-score) <folding_stability>
-   Compactness (Radius of gyration) <compactness>
-   Secondary Structure matching <secondary_structure>
-
-(For detailed descriptions and implementations of each metric, please refer to the pages linked above)

docs/source/benchmarks/biomolecules/img/amyloid.png

@@ -12,7 +12,7 @@ reference data \ [#f1]_ and outliers are detected.
 
 Description
 -----------
-This benchmark performs an MD simulation using the **MLIP** model in the **NVT** ensemble at **350 K** for **150,000 steps**. The
+This benchmark performs an MD simulation using the **MLIP** model in the **NVT** ensemble at **350 K** for **150,000 steps** (150ps). The
 sampled probability distribution of backbone and side chain dihedrals is compared to a reference distribution. The main metrics are
 the **RMSD** and the **Hellinger distance** between the sampled and reference distributions. We also compute the **outliers ratio**
 of the sampled dihedrals. An outlier is defined as a conformation that is far away from any point of the reference data.
@@ -23,10 +23,9 @@ Dataset
 
 Each sequence was prepared to have a neutral total charge.
 
-Systems were prepared with tleap, using larger boxes to enable proper handeling of long range cutoffs
-and minimised and equilibrated with the NPT ensemble with the AMBER force field using openMM.
-
-Boxes of 300 molecules of water were then extracted from the equilibrated systems.
+Systems were prepared with **AmberTools25** \ [#f2]_, using larger boxes of pre-equilibrated **TIP3P** \ [#f3]_ water to enable
+proper handeling of long range cutoffs,and then minimised and equilibrated in the NPT ensemble (1atm, 350K) with the AMBER99SB-ILDN \ [#f4]_,
+force field using openMM \ [#f5]_. After equilibration, boxes of 300 molecules of water were extracted to optimise benchmark runtimes.
 
 The sequences are as follows:
 
@@ -52,3 +51,7 @@ MLIP with an outlier ratio higher than 0.3 should be considered as not sampling
 References
 ----------
 .. [#f1] Lovell, S.C., Word, J.M., Richardson, J.S. and Richardson, D.C. (2000),The penultimate rotamer library. Proteins, 40: 389-408. https://doi.org/10.1002/1097-0134(20000815)40:3<389::AID-PROT50>3.0.CO;2-2
+.. [#f2] AmberTools25, Case, D.A.; et al. Amber 2025. University of California, San Francisco (2025).
+.. [#f3] TIP3P, Jorgensen, W. L.; Chandrasekhar, J.; Madura, J. D.; Impey, R. W.; Klein, M. L. J. Chem. Phys. 79 (1983) 926–935. doi:10.1063/1.445869
+.. [#f4] Lindorff-Larsen, K.; Piana, S.; Palmo, K.; Maragakis, P.; Klepeis, J. L.; Dror, R. O.; Shaw, D. E. Proteins 78 (2010) 1950–1958. doi:10.1002/prot.22711
+.. [#f5] P. Eastman; et al. “OpenMM 8: Molecular Dynamics Simulation with Machine Learning Potentials.” J. Phys. Chem. B 128(1), pp. 109-116 (2023).

docs/source/benchmarks/biomolecules/img/chignolin.png

@@ -17,16 +17,17 @@ Description
 
 For each system in the dataset, the benchmark performs a **MD** simulation using the  **MLIP** model in the **NVT** ensemble at **300 K**
 for **1000 steps** (1 ps), leveraging the `jax-md <https://github.com/google/jax-md>`_, as integrated via the
-`mlip <https://github.com/instadeepai/mlip>`_ library. During each simulation, a timer tracks the duration of each episode, and the average episode time (excluding the first episode)
-is recorded. After all simulations are complete, the benchmark reports the **average inference time per episode as a function of
-system size**, providing a direct measure of how the **MLIP** implementation's computational cost grows with increasing molecular
-complexity. This allows for the identification of scaling bottlenecks and informs optimization strategies for large-scale
-simulations.
+`mlip <https://github.com/instadeepai/mlip>`_ library. During each simulation, a timer tracks the duration of each episode,
+and the average episode time (excluding the first episode to ignore the compilation time) is recorded. After all simulations are complete, the benchmark reports
+the **average inference time per averagestep as a function of system size**, providing a direct measure of how the **MLIP** implementation's
+computational cost grows with increasing molecular complexity. This allows for the identification of scaling bottlenecks and informs
+optimization strategies for large-scale simulations.
 
 Dataset
 -------
 
-The structures that are tested for stability are a series of protein structures, RNA fragments, peptides and inhibitors taken from the PDB.
+The scaling dataset is composed of a series of protein structures, RNA fragments,
+peptides and small-molecules experimental structures taken from the `PDB <https://www.rcsb.org/>`_ databank.
 They have the following ids:
 
 * 1JRS

docs/source/benchmarks/biomolecules/img/hypocretin.png

@@ -7,7 +7,7 @@ Purpose
 -------
 
 To assess the long-term dynamical stability of a machine-learned interatomic potential (**MLIP**) during realistic,
-production-scale molecular dynamics (**MD**) simulations.
+molecular dynamics (**MD**) simulations.
 
 Description
 -----------
@@ -16,8 +16,8 @@ For each system in the dataset, the benchmark performs a **MD** simulation using
 **NVT** ensemble at **300 K** for **100,000 steps** (100 ps), leveraging the
 `jax-md <https://github.com/google/jax-md>`_, as integrated via the `mlip <https://github.com/instadeepai/mlip>`_
 library. The test monitors the system for signs of instability by detecting abrupt temperature spikes
-(**“explosions”**) and hydrogen atom drift. These indicators help determine whether the **MLIP** maintains
-stable and physically consistent dynamics over extended simulation times.
+(explosions) and hydrogen atom drift. These indicators help determine whether the **MLIP** maintains
+stable and physically consistent dynamics over simulation times.
 
 Our **stability score** is computed as:
 
@@ -36,7 +36,8 @@ the frame at which the first H atom detaches.
 Dataset
 -------
 
-The structures that are tested for stability are a series of protein structures, RNA fragments, peptides and inhibitors taken from the PDB.
+The stability dataset is composed by a series of protein structures, RNA fragments,
+peptides and small-molecules experimental structures taken from the `PDB <https://www.rcsb.org/>`_ databank.
 They have the following ids:
 
 * 1JRS (Leupeptin)

docs/source/benchmarks/biomolecules/img/trp.png

@@ -16,4 +16,5 @@ implement your own benchmarks.
 
     General <general/index>
     Small Molecules <small_molecules/index>
+    Molecular Liquids <molecular_liquids/index>
     Biomolecules <biomolecules/index>