Merge pull request autoatml#315 from naik-aakash/docs_build

Update docs dependencies

.github/workflows/docs.yml

@@ -37,6 +37,8 @@ jobs:
             micromamba activate autoplex_docs
             uv pip install --upgrade pip
             uv pip install --prerelease=allow .[docs,strict]
+            uv pip install --upgrade monty
+            uv pip install numpy==1.26.4
       - name: Build
         run: micromamba run -n autoplex_docs sphinx-build -W docs _build
       - name: Deploy to GitHub Pages

.github/workflows/python-package.yml

@@ -156,5 +156,7 @@ jobs:
             micromamba activate autoplex_docs
             uv pip install --upgrade pip
             uv pip install --prerelease=allow .[docs,strict]
+            uv pip install --upgrade monty
+            uv pip install numpy==1.26.4
       - name: Build
         run: micromamba run -n autoplex_docs sphinx-build -W docs _build

README.md

@@ -19,12 +19,21 @@
 
 `autoplex` is an evolving project and **contributions are very welcome**! To ensure that the code remains of high quality, please raise a pull request for any contributions, which will be reviewed before integration into the main branch of the code. Initially, [@JaGeo](https://github.com/JaGeo) will handle the reviews.
 
-# Documentation
+# Workflow overview
+
+We currently have two different types of automation workflows available:
+
+* Workflow to use random-structure searches for the systematic construction of interatomic potentials: [arXiv: 10.48550/arXiv.2412.16736](https://arxiv.org/abs/2412.16736).
+  The implementation automates ideas from the following articles: [*Phys. Rev. Lett.* **120**, 156001 (2018)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.156001) and [*npj Comput. Mater.* **5**, 99 (2019)](https://www.nature.com/articles/s41524-019-0236-6).
+* Workflow to train accurate interatomic potentials for harmonic phonon properties. The implementation automates the ideas from the following article: [*J. Chem. Phys.* **153**, 044104 (2020)](https://pubs.aip.org/aip/jcp/article/153/4/044104/1056348/Combining-phonon-accuracy-with-high).
+
+
+## Documentation
 
 You can find the `autoplex` documentation [here](https://autoatml.github.io/autoplex/index.html)!
 The documentation also contains tutorials that teach you how to use `autoplex` for different use cases for the RSS and phonon workflows and individual modules therein.
 
-# What to cite?
+## What to cite?
 
 Please cite our preprint on the random-structure searches (RSS) performed with `autoplex`:
 
@@ -46,7 +55,7 @@ This involves the following software packages:
 
 All of these software tools provide documentation and tutorials. Please take your time and check everything out! Please also cite the software packages if you are using them!
 
-# Setup
+## Setup
 
 To set up the mandatory prerequisites for using `autoplex,` please follow the [installation guide of atomate2](https://materialsproject.github.io/atomate2/user/install.html).
 
@@ -55,11 +64,11 @@ Set a number that is a divisor of the number of tasks you use for the VASP calcu
 
 # Installation
 
-### Python version
+## Python version
 
 Before the installation, please make sure that you are using one of the supported Python versions (see [pyproject.toml](https://github.com/autoatml/autoplex/blob/main/pyproject.toml))
 
-### Standard installation
+## Standard installation
 
 Please install `autoplex` using
 ```
@@ -82,7 +91,7 @@ Once installed in the terminal, run the following commands to get Julia ACEpoten
 julia -e 'using Pkg; Pkg.Registry.add("General"); Pkg.Registry.add(Pkg.Registry.RegistrySpec(url="https://github.com/ACEsuit/ACEregistry")); Pkg.add(Pkg.PackageSpec(;name="ACEpotentials", version="0.6.7")); Pkg.add("DataFrames"); Pkg.add("CSV")'
 ```
 
-### Enabling RSS workflows
+## Enabling RSS workflows
 
 Additionally, `buildcell` as a part of `AIRSS` needs to be installed if one wants to use the RSS functionality:
 
@@ -92,7 +101,7 @@ curl -O https://www.mtg.msm.cam.ac.uk/files/airss-0.9.3.tgz; tar -xf airss-0.9.3
 
 Please find out about licenses and citation requirements here: [https://airss-docs.github.io/](https://airss-docs.github.io/)
 
-### LAMMPS installation
+## LAMMPS installation
 
 You only need to install LAMMPS, if you want to use J-ACE as your MLIP.
 Recipe for compiling lammps-ace including the download of the `libpace.tar.gz` file:
@@ -136,14 +145,6 @@ LIB PACE flags (`-D PACELIB_MD5=$(md5sum libpace.tar.gz | awk '{print $1}')`).
 
 Please find out about licenses and citation requirements here: [https://www.lammps.org/](https://www.lammps.org/)
 
-### Contributing guidelines / Developer's installation
+# Contributing guidelines / Developer's installation
 
 A short guide to contributing to autoplex can be found [here](https://autoatml.github.io/autoplex/dev/contributing.html). Additional information for developers can be found [here](https://autoatml.github.io/autoplex/dev/dev_install.html).
-
-# Workflow overview
-
-We currently have two different types of automation workflows available:
-
-* Workflow to use random-structure searches for the systematic construction of interatomic potentials: [arXiv: 10.48550/arXiv.2412.16736](https://arxiv.org/abs/2412.16736).
-  The implementation automates ideas from the following articles: [*Phys. Rev. Lett.* **120**, 156001 (2018)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.156001) and [*npj Comput. Mater.* **5**, 99 (2019)](https://www.nature.com/articles/s41524-019-0236-6).
-* Workflow to train accurate interatomic potentials for harmonic phonon properties. The implementation automates the ideas from the following article: [*J. Chem. Phys.* **153**, 044104 (2020)](https://pubs.aip.org/aip/jcp/article/153/4/044104/1056348/Combining-phonon-accuracy-with-high).

docs/about/contributing.md

@@ -1,2 +1,6 @@
+---
+orphan: true
+---
+
 ```{include} ../../CONTRIBUTING.md
 ```

docs/conf.py

@@ -11,7 +11,7 @@
 import os
 import sys
 
-from atomate2 import __version__
+from autoplex import __version__
 
 sys.path.insert(0, os.path.abspath("../../"))
 
@@ -103,7 +103,7 @@
 language = "en"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-suppress_warnings = "etoc.toctree"
+suppress_warnings = ['toc.excluded', 'toc.not_readable']
 
 # autodoc options
 autosummary_imported_members = False

docs/glossary.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _glossary:
 
 Glossary

docs/user/jobflowremote.md

@@ -1,3 +1,7 @@
+---
+orphan: true
+---
+
 # Jobflow-remote setup
 
 This will result in a setup for automation where 

docs/user/mongodb.md

@@ -1,3 +1,7 @@
+---
+orphan: true
+---
+
 # MongoDB setup tutorial
 
 `autoplex` and `atomate2` use the MongoDB database framework to store the data output from the calculations. 

docs/user/rss.md

@@ -0,0 +1,3 @@
+---
+orphan: true
+---

docs/user/rss/flow/example/example.md

@@ -1,4 +1,4 @@
-(rss)=
+(example)=
 
 # Examples
 

docs/user/rss/flow/input/input.md

@@ -1,4 +1,4 @@
-(rss)=
+(input)=
 
 # Input YAML configuration file
 

docs/user/rss/flow/introduction/intro.md

@@ -1,4 +1,4 @@
-(rss)=
+(introduction)=
 
 # Brief overview
 

docs/user/rss/flow/quick_start/start.md

@@ -1,4 +1,4 @@
-(rss)=
+(rss-quickstart)=
 
 # Quick start
 
@@ -24,7 +24,7 @@ The `RssMaker` class in `autoplex` is the core interface for creating ML-RSS pot
 
 Parameters can be specified either through a YAML configuration file or as direct arguments in the `make` method.
 
-### Running the workflow with a YAML configuration file
+## Running the workflow with a YAML configuration file
 
 > **Recommendation**: This is currently our recommended approach for setting up and managing RSS workflows.
 
@@ -56,7 +56,7 @@ print(submit_flow(rss_job, worker="your worker", resources=resources, project="y
 
 For details on setting up `FireWorks`, see [FireWorks setup](../../../mongodb.md#fireworks-configuration) and for `jobflow-remote`, see [jobflow-remote setup](../../../jobflowremote.md).
 
-### Running the workflow with direct parameter specification
+## Running the workflow with direct parameter specification
 
 As an alternative to using a YAML configuration file, the RSS workflow can be initiated by directly specifying parameters in the `make` method. This approach is ideal for cases where only a few parameters need to be customized. You can override the default settings by passing them as keyword arguments, offering a more flexible and lightweight way to set up the workflow.
 
@@ -79,7 +79,7 @@ If you choose to use the direct parameter specification method, at a minimum, yo
 
 > **Note**: If both a YAML file and direct parameter specifications are provided, any overlapping parameters will be overridden by the directly specified values.
 
-### Building RSS models with various ML potentials
+## Building RSS models with various ML potentials
 
 Currently, `RssMaker` supports GAP (Gaussian Approximation Potential), ACE (Atomic Cluster Expansion), and three graph-based network models including NequIP, M3GNet, and MACE. You can specify the desired model using the `mlip_type` argument and adjust relevant hyperparameters within the `make` method. Default and adjustable hyperparameters are available in `autoplex/fitting/common/mlip-rss-defaults.json`.
 
@@ -93,7 +93,7 @@ rss_job = RssMaker(name="your workflow name").make(tag='SiO2',
 
 > **Note**: We primarily recommend the GAP-RSS model for now, as GAP has demonstrated great stability with small datasets. Other models have not been thoroughly explored yet. However, we encourage users to experiment with and test other individual models or combinations for potentially interesting results.
 
-### Resuming workflow from point of interruption
+## Resuming workflow from point of interruption
 
 To resume an interrupted RSS workflow, use the `resume_from_previous_state` argument, which accepts a dictionary containing the necessary state information. Additionally, ensure that `train_from_scratch` is set to `False` to enable resuming from the previous state. This way, you are allowed to continue the workflow from any previously saved state.
 

docs/user/setup.md

@@ -26,15 +26,15 @@ Once installed in the terminal, run the following commands to get Julia ACEpoten
 julia -e 'using Pkg; Pkg.Registry.add("General"); Pkg.Registry.add(Pkg.Registry.RegistrySpec(url="https://github.com/ACEsuit/ACEregistry")); Pkg.add(Pkg.PackageSpec(;name="ACEpotentials", version="0.6.7")); Pkg.add("DataFrames"); Pkg.add("CSV")'
 ```
 
-### Enabling RSS workflows
+## Enabling RSS workflows
 
 Additionally, `buildcell` as a part of `AIRSS` needs to be installed if one wants to use the RSS functionality:
 
 ```bash
 curl -O https://www.mtg.msm.cam.ac.uk/files/airss-0.9.3.tgz; tar -xf airss-0.9.3.tgz; rm airss-0.9.3.tgz; cd airss; make ; make install ; make neat; cd ..
 ```
 
-### LAMMPS installation
+## LAMMPS installation
 
 You only need to install LAMMPS, if you want to use J-ACE as your MLIP.
 Recipe for compiling lammps-ace including the download of the `libpace.tar.gz` file:

pyproject.toml

@@ -52,11 +52,11 @@ docs = [
     "autodoc_pydantic==2.2.0",
     "ipython",
     "jsonschema[format]",
-    "myst_parser==2.0.0",
+    "myst_parser==4.0.0",
     "numpydoc==1.8.0",
     "sphinx-copybutton==0.5.2",
-    "sphinx==7.2.6",
-    "sphinx_design==0.5.0",
+    "sphinx==8.1.3",
+    "sphinx_design==0.6.1",
     "myst-nb==1.0.0",
     "sphinx-book-theme==1.1.0",
     "sphinxcontrib-mermaid",

src/autoplex/__init__.py

@@ -6,3 +6,5 @@
 DFT-labelled data.
 
 """
+
+from autoplex._version import __version__

src/autoplex/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("autoplex")

src/autoplex/auto/rss/flows.py

@@ -53,17 +53,13 @@ def make(self, config_file: str | None = None, **kwargs):
         resume_from_previous_state: dict | None
             A dictionary containing the state information required to resume a previously interrupted
             or saved RSS workflow. When 'train_from_scratch' is set to False, this parameter is mandatory
-            for the workflow to pick up from a saved state.
-            Expected keys within this dictionary:
-                test_error: float
-                    The test error from the last completed training step.
-                pre_database_dir: str
-                    Path to the directory containing the pre-existing database for resuming.
-                mlip_path: str
-                    Path to the file of a previous MLIP model.
-                isolated_atom_energies: dict
-                    A dictionary of isolated atom energy values, with atomic numbers as keys
-                    and their energies as valuables.
+            for the workflow to pick up from a saved state.Expected keys within this dictionary are as follows
+
+            - 'test_error': float, The test error from the last completed training step.
+            - 'pre_database_dir': str, Path to the directory containing the pre-existing database for resuming.
+            - 'mlip_path': str, Path to the file of a previous MLIP model.
+            - 'isolated_atom_energies': dict, A dictionary with isolated atom energy values mapped to atomic numbers.
+
         generated_struct_numbers: list[int]
             Expected number of generated randomized unit cells by buildcell.
         buildcell_options: list[dict] | None
@@ -85,29 +81,26 @@ def make(self, config_file: str | None = None, **kwargs):
         rss_selection_method: str
             Method for selecting samples from the RSS trajectories:
             Boltzmann flat histogram in enthalpy first, then CUR.
-            Options include:
-                bcur1s: Execute bcur with one shot (1s)
-                bcur2i: Execute bcur with two iterations (2i)
+            Options are as follows
+
+            - 'bcur1s': Execute bcur with one shot (1s)
+            - 'bcur2i': Execute bcur with two iterations (2i)
+
         bcur_params: dict | None
-            Parameters for Boltzmann CUR selection. The default dictionary includes:
-                soap_paras: dict
-                   SOAP descriptor parameters:
-                l_max: int
-                    Maximum degree of spherical harmonics (default 12).
-                n_max: int
-                    Maximum number of radial basis functions (default 12).
-                atom_sigma: float
-                    Width of Gaussian smearing (default 0.0875).
-                cutoff: float
-                    Radial cutoff distance (default 10.5).
-                cutoff_transition_width: float
-                    Width of the transition region (default 1.0).
-                zeta: float
-                    Exponent for dot-product SOAP kernel (default 4.0).
-                average: bool
-                    Whether to average the SOAP vectors (default True).
-                species: bool
-                    Whether to consider species information (default True).
+            Parameters for Boltzmann CUR selection. The default dictionary includes following keys
+
+            soap_paras: dict
+                SOAP descriptor parameters dict with following acceptable keys
+
+            - 'l_max': int, Maximum degree of spherical harmonics (default 12).
+            - 'n_max': int, Maximum number of radial basis functions (default 12).
+            - 'atom_sigma': float, Width of Gaussian smearing (default 0.0875).
+            - 'cutoff': float, Radial cutoff distance (default 10.5).
+            - 'cutoff_transition_width': float, Width of the transition region (default 1.0).
+            - 'zeta': float,Exponent for dot-product SOAP kernel (default 4.0).
+            - 'average': bool, Whether to average the SOAP vectors (default True).
+            - 'species': bool, Whether to consider species information (default True).
+
             kb_temp: float
                 Temperature in eV for Boltzmann weighting (default 0.3).
             frac_of_bcur: float
@@ -152,9 +145,11 @@ def make(self, config_file: str | None = None, **kwargs):
         regularization: bool
             If True, apply regularization. This only works for GAP to date. Default is False.
         scheme: str
-            Method to use for regularization. Options are:
-                linear_hull: for single-composition system, use 2D convex hull (E, V)
-                volume-stoichiometry: for multi-composition system, use 3D convex hull of (E, V, mole-fraction)
+            Method to use for regularization. Options are
+
+            - 'linear_hull': for single-composition system, use 2D convex hull (E, V)
+            - 'volume-stoichiometry': for multi-composition system, use 3D convex hull of (E, V, mole-fraction)
+
         reg_minmax: list[tuple]
             List of tuples of (min, max) values for energy, force, virial sigmas for regularization.
         distillation: bool
@@ -180,13 +175,12 @@ def make(self, config_file: str | None = None, **kwargs):
             Number of processes used for fitting. Default is 1.
         device_for_fitting: str
             Device to be used for model fitting, either "cpu" or "cuda".
-        **fit_kwargs:
-            Additional keyword arguments for the MLIP fitting process.
         scalar_pressure_method: str
-            Method for adding external pressures.
-            Acceptable options are:
-                exp: Applies pressure using an exponential distribution.
-                uniform: Applies pressure using a uniform distribution.
+            Method for adding external pressures. Acceptable options are as follows
+
+            - 'exp': Applies pressure using an exponential distribution.
+            - 'uniform': Applies pressure using a uniform distribution.
+
         scalar_exp_pressure: float
             Scalar exponential pressure. Default is 100.
         scalar_pressure_exponential_width: float
@@ -226,23 +220,20 @@ def make(self, config_file: str | None = None, **kwargs):
             Initial temperature (in eV) for Boltzmann sampling. Default is 0.3.
         current_iter_index: int
             Index for the current RSS iteration. Default is 1.
+        **fit_kwargs:
+            Additional keyword arguments for the MLIP fitting process.
 
         Returns
         -------
-        dict
-            A dictionary whose keys contains:
-                test_error: float
-                    The test error of the fitted MLIP.
-                pre_database_dir: str
-                    The directory of the latest RSS database.
-                mlip_path: str
-                    The path to the latest fitted MLIP.
-                isolated_atom_energies: dict
-                    The isolated energy values.
-                current_iter: int
-                    The current iteration index.
-                kb_temp: float
-                    The temperature (in eV) for Boltzmann sampling.
+        dict:
+            A dictionary with following information
+
+            - 'test_error': float, The test error of the fitted MLIP.
+            - 'pre_database_dir': str, The directory of the latest RSS database.
+            - 'mlip_path': str, The path to the latest fitted MLIP.
+            - 'isolated_atom_energies': dict, The isolated energy values.
+            - 'current_iter': int, The current iteration index.
+            - 'kb_temp': float, The temperature (in eV) for Boltzmann sampling.
         """
         rss_default_config_path = (
             self.path_to_default_config_parameters