Merge branch 'main' into hamiltonian_learning

.github/workflows/docs.yml

@@ -19,7 +19,7 @@ jobs:
 
       - id: collectExamples
         run: |
-          echo examplesjson=$(./developer/get_examples.py) >> $GITHUB_OUTPUT
+          echo examplesjson=$(./src/get_examples.py) >> $GITHUB_OUTPUT
 
   generate-example:
     needs: setup

examples/gaas-map/gaas-map.py

@@ -1,4 +1,4 @@
-"""
+r"""
 PCA/PCovR Visualization for the rattled GaAs training dataset
 =============================================================
 
@@ -12,6 +12,10 @@
 description of the dataset, that is then visualized using
 ``chemiscope``.
 
+This example uses the dataset from
+`Imbalzano (2021) <http://doi.org/10.1103/PhysRevMaterials.5.063804>`_
+and the principal covariate regression scheme as implemented in
+`Helfrecht (2020) <http://doi.org/10.1088/2632-2153/aba9ef>`_.
 """
 
 import os

examples/pi-metad/pi-metad.py

@@ -49,11 +49,14 @@
 # Metadynamics for the Zundel cation
 # ----------------------------------
 #
-# Metadynamics is a metnod to accelerate sampling of rare events - microscopic processes
+# Metadynamics is a method to accelerate sampling of rare events - microscopic processes
 # that are too infrequent to be observed over the time scale (ns-µs) accessible to
 # molecular dynamics simulations. You can read one of the many excellent reviews
 # on metadynamics (see e.g.
-# `Bussi and Branduardi (2015) <https://doi.org/10.1002/9781118889886.ch1>`_).
+# `Bussi and Branduardi (2015) <https://doi.org/10.1002/9781118889886.ch1>`_),
+# or follow a
+# `lecture from the PLUMED masterclass
+# <https://www.plumed-tutorials.org/lessons/21/004/data/NAVIGATION.html>`_.
 # In short, during a metadynamics simulation an adaptive biasing potential is
 # built as a superimposition of Gaussians centered over configurations that have
 # been previously visited by the trajectory. This discourages the system from remaining
@@ -233,6 +236,7 @@
 # If you run this in a notebook, you can go ahead and start loading
 # output files *before* i-PI has finished running by skipping this cell
 
+# wait for simulations to finish
 if ipi_process is not None:
     ipi_process.wait()
     for process in driver_process:
@@ -495,8 +499,8 @@ def moving_average(arr, window_size):
 # is important to distinguish between the free-energy computed
 # as the logarithm of the probability of observing a given
 # configuration (that depends on the distribution of the
-# replicas) and the free-energy taken as a mean to estimate
-# and reaction  rates :math:`k` in a transition-state theory
+# replicas) and the free-energy taken as a tool to estimate
+# reaction  rates :math:`k` in a transition-state theory
 # fashion :math:`k\propto e^{-\Delta E^\ddagger/kT}`,
 # where the energy barrier :math:`\Delta E^\ddagger`
 # is better estimated from the distribution of the centroid.
@@ -519,7 +523,7 @@ def moving_average(arr, window_size):
 #
 # The other changes are purely cosmetic, and the calculation
 # can be launched very easily, using several drivers to parallelize
-# the calculation over the beads (although this kind of calculations
+# the energy evaluation over the beads (although this kind of calculations
 # is not limited by the evaluation of the forces).
 
 # don't rerun if the outputs already exist
@@ -539,7 +543,7 @@ def moving_average(arr, window_size):
 # If you run this in a notebook, you can go ahead and start loading
 # output files _before_ i-PI has finished running by skipping this cell
 
-# don't rerun if the outputs already exist
+# wait for simulations to finish
 if ipi_process is not None:
     ipi_process.wait()
     for process in driver_process:

examples/roy-gch/roy-gch.py

@@ -13,6 +13,14 @@
 and uses the directional convex hull function from
 `scikit-matter <https://github.com/lab-cosmo/scikit-matter>`__
 to make the figure.
+
+The GCH construction aims at determining structures, among a collection of
+candidate configurations, that are stable or have the potential of being stabilized
+by appropriate thermodynamic boundary conditions (pressure, doping, external fields,
+...). It does so by using microscopic descriptors to determine the diversity of
+structures, and assumes that configurations that are stable relative to other
+configurations with similar descriptors are those that could be made
+"locally" stable by suitable synthesis conditions.
 """
 
 import chemiscope
@@ -45,7 +53,11 @@
 # -------------------
 #
 # The Directional Convex Hull routines can be used to compute a
-# conventional density-energy hull
+# conventional density-energy hull (see
+# `Hautier (2014)
+# <http://doi.org/10.1007/128_2013_486>`_ for a pedagogic
+# introduction to the convex hull construction in the context
+# of atomistic simulations).
 
 dch_builder = DirectionalConvexHull(low_dim_idx=[0])
 dch_builder.fit(density.reshape(-1, 1), energy)

noxfile.py

@@ -12,7 +12,7 @@
 ROOT = os.path.realpath(os.path.dirname(__file__))
 
 sys.path.insert(0, ROOT)
-from developer.get_examples import get_examples  # noqa: E402
+from src.get_examples import get_examples  # noqa: E402
 
 
 # global nox options
@@ -31,11 +31,11 @@
 # Files that need to be linted & formatted
 def get_lint_files():
     LINT_FILES = [
-        "ipynb-to-gallery.py",
-        "generate-gallery.py",
+        "src/ipynb-to-gallery.py",
+        "src/generate-gallery.py",
         "noxfile.py",
         "docs/src/conf.py",
-        "developer/get_examples.py",
+        "src/get_examples.py",
     ]
     return LINT_FILES + get_example_files()
 
@@ -159,7 +159,7 @@ def example(session, name=name):
                 f"examples/{name}/data", "zip", f"examples/{name}/", "data/"
             )
 
-        session.run("python", "generate-gallery.py", f"examples/{name}")
+        session.run("python", "src/generate-gallery.py", f"examples/{name}")
 
         os.unlink(f"docs/src/examples/{name}/index.rst")
 

generate-gallery.py → src/generate-gallery.py

@@ -7,7 +7,7 @@
 from chemiscope.sphinx import ChemiscopeScraper
 
 
-HERE = os.path.realpath(os.path.dirname(__file__))
+ROOT = os.path.realpath(os.path.join(os.path.dirname(__file__), "../"))
 
 
 class AttrDict(dict):
@@ -24,7 +24,7 @@ class PseudoSphinxApp:
 
     def __init__(self, example):
         gallery_dir = os.path.join(
-            HERE, "docs", "src", "examples", os.path.basename(example)
+            ROOT, "docs", "src", "examples", os.path.basename(example)
         )
         if os.path.exists(gallery_dir):
             shutil.rmtree(gallery_dir)
@@ -38,7 +38,7 @@ def __init__(self, example):
         self.config.default_role = ""
         self.config.sphinx_gallery_conf = {
             "filename_pattern": ".*",
-            "examples_dirs": os.path.join(HERE, example),
+            "examples_dirs": os.path.join(ROOT, example),
             "gallery_dirs": gallery_dir,
             "min_reported_time": 60,
             "copyfile_regex": r".*\.(sh|xyz|cp2k|yml|png|zip)",
@@ -48,7 +48,7 @@ def __init__(self, example):
         }
 
         self.builder = AttrDict()
-        self.builder.srcdir = os.path.join(HERE, "docs", "src")
+        self.builder.srcdir = os.path.join(ROOT, "docs", "src")
         self.builder.outdir = ""
         self.builder.name = os.path.basename(example)