diff --git a/examples/gaas-map/gaas-map.py b/examples/gaas-map/gaas-map.py index af40440f..4d6f2e0f 100644 --- a/examples/gaas-map/gaas-map.py +++ b/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) `_ +and the principal covariate regression scheme as implemented in +`Helfrecht (2020) `_. """ import os diff --git a/examples/pi-metad/pi-metad.py b/examples/pi-metad/pi-metad.py index 9f54f4d3..564af493 100644 --- a/examples/pi-metad/pi-metad.py +++ b/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) `_). +# `Bussi and Branduardi (2015) `_), +# or follow a +# `lecture from the PLUMED masterclass +# `_. # 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: diff --git a/examples/pi-metad/plumed-tutorials.zip b/examples/pi-metad/plumed-tutorials.zip new file mode 100644 index 00000000..8de4f58a Binary files /dev/null and b/examples/pi-metad/plumed-tutorials.zip differ diff --git a/examples/roy-gch/roy-gch.py b/examples/roy-gch/roy-gch.py index 94637daf..fd893561 100644 --- a/examples/roy-gch/roy-gch.py +++ b/examples/roy-gch/roy-gch.py @@ -13,6 +13,14 @@ and uses the directional convex hull function from `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) +# `_ 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) diff --git a/noxfile.py b/noxfile.py index ca10a1f0..d200d927 100644 --- a/noxfile.py +++ b/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") diff --git a/generate-gallery.py b/src/generate-gallery.py similarity index 89% rename from generate-gallery.py rename to src/generate-gallery.py index 850c8e4c..90f07fe4 100644 --- a/generate-gallery.py +++ b/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) diff --git a/developer/get_examples.py b/src/get_examples.py similarity index 100% rename from developer/get_examples.py rename to src/get_examples.py diff --git a/ipynb-to-gallery.py b/src/ipynb-to-gallery.py similarity index 100% rename from ipynb-to-gallery.py rename to src/ipynb-to-gallery.py