Feature/update docs

.github/workflows/quality.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: prefix-dev/setup-pixi@v0.8.8
         with:
-          pixi-version: v0.48.0
+          pixi-version: v0.66.0
       - run: pixi run fmt --check
       - run: pixi run lint
       - run: pixi run types

README.md

@@ -37,7 +37,7 @@ python examples/fsm_example.py data/sharada/06_diels_alder/ --calculator emt
 ```
 Note the EMT calculator should only be used for quick demonstrations/tests.
 
-## Tutorials 
+## Tutorials
 
 1. A Google Colab notebook example is available at:
 ```
@@ -51,11 +51,11 @@ The script:
 ```
 examples/fsm_example.py
 ```
-is a comprehensive and flexible tool that supports most ML-FSM functionality. 
+is a comprehensive and flexible tool that supports most ML-FSM functionality.
 
 Note: Users are responsible for installing their desired quantum chemistry backend, current calculators supported in fsm_example.py are [AIMNet2](https://github.com/isayevlab/AIMNet2), [MACEOFF23](https://github.com/ACEsuit/mace-off), [FAIR UMA](https://github.com/facebookresearch/fairchem), [TensorNet](https://github.com/torchmd/torchmd-net), [xTB](https://github.com/grimme-lab/xtb), [QChem](https://www.q-chem.com).
 
-3. Some ML potentials do not offer a native ASE interface. To accommodate these, a minimal example of custom ```ase.Calculator``` wrappers is provided in the ```examples/``` folder. This serves as templates for integrating arbitrary NNPs with ML-FSM   
+3. Some ML potentials do not offer a native ASE interface. To accommodate these, a minimal example of custom ```ase.Calculator``` wrappers is provided in the ```examples/``` folder. This serves as templates for integrating arbitrary NNPs with ML-FSM
 ## Usage
 For projects referencing algorithmic improvements to the FSM please cite:
 

docs/requirements.txt

@@ -1,5 +1,5 @@
 sphinx
 sphinx-autodoc-typehints
 numpydoc
-sphinx-rtd-theme
+furo
 myst-parser

docs/source/api.rst

@@ -1,70 +1,90 @@
 API Reference
 =============
 
-This section contains the complete API reference for all modules in mlfsm.
+This section contains the complete API reference for all modules in ``mlfsm``.
+
+----
 
 Core Modules
 ------------
 
-Coordinates
-~~~~~~~~~~~
-.. automodule:: mlfsm.coords
+FreezingString (``mlfsm.cos``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The main driver class that orchestrates string growth, interpolation, and node
+optimization throughout the FSM calculation.
+
+.. automodule:: mlfsm.cos
    :members:
    :undoc-members:
    :show-inheritance:
    :special-members: __init__
 
-The coordinates module provides objects and functionality for cartesian and redundant internal coordinates.
+----
+
+Interpolation (``mlfsm.interp``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Provides :class:`~mlfsm.interp.Linear`, :class:`~mlfsm.interp.LST`, and
+:class:`~mlfsm.interp.RIC` interpolation schemes for generating reaction path
+nodes between endpoint geometries.
 
-Interpolation
-~~~~~~~~~~~~~
 .. automodule:: mlfsm.interp
    :members:
    :undoc-members:
    :show-inheritance:
    :special-members: __init__
 
-The interpolation module provides objects and funcitonality for various interpolation methods.
+----
 
-Optimization
-~~~~~~~~~~~~
-.. automodule:: mlfsm.opt
+Coordinates (``mlfsm.coords``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cartesian and redundant internal coordinate systems used during interpolation and
+back-transformation to Cartesian coordinates.
+
+.. automodule:: mlfsm.coords
    :members:
    :undoc-members:
    :show-inheritance:
    :special-members: __init__
 
-The opt module provides optimizer objects for various methods and coordinate systems.
+----
 
-Cos
-~~~~~~~~~~~~~~~~~
-.. automodule:: mlfsm.cos
+Optimization (``mlfsm.opt``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Node-level optimizers that relax FSM images perpendicular to the current tangent
+direction using L-BFGS-B with explicit line search.
+
+.. automodule:: mlfsm.opt
    :members:
    :undoc-members:
    :show-inheritance:
    :special-members: __init__
 
-The cos module provides the main freezing string class
+----
+
+Geometry Utilities (``mlfsm.geom``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Low-level vector operations and projection operators used throughout the FSM,
+including rigid-body alignment and translation/rotation projection.
 
-Geometry
-~~~~~~~~
 .. automodule:: mlfsm.geom
    :members:
    :undoc-members:
    :show-inheritance:
-   :special-members: __init__
 
-The geometry module has functions for manipulating geometries or calculating geometric quantities.
+----
+
+Utilities (``mlfsm.utils``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Utility Modules
----------------
+Input/output helpers for loading reactant and product geometries and handling
+fixed-atom constraints.
 
-Utilities
-~~~~~~~~~
 .. automodule:: mlfsm.utils
    :members:
    :undoc-members:
    :show-inheritance:
-   :special-members: __init__
-
-Helper functions and utilities for common operations.

docs/source/conf.py

@@ -3,25 +3,24 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../../mlfsm"))
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+sys.path.insert(0, os.path.abspath("../../src"))
 
 # -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "ML-FSM"
 copyright = "2025, Jonah Marks and Joe Gomes"
 author = "Jonah Marks and Joe Gomes"
 release = "1.0.1"
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autodoc.typehints",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
     "numpydoc",
     "myst_parser",
 ]
@@ -31,26 +30,17 @@
 templates_path = ["_templates"]
 exclude_patterns: list[str] = []
 
+# -- Intersphinx mapping -----------------------------------------------------
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_static_path = ["_static"]
-
-# Theme
-html_theme = "sphinx_rtd_theme"  # or 'furo' for a modern look
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "ase": ("https://wiki.fysik.dtu.dk/ase", None),
+}
 
-# Extensions
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",  # for Google/NumPy docstrings
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.mathjax",
-]
+# -- Autodoc settings --------------------------------------------------------
 
-# Autodoc settings
 autodoc_default_options = {
     "members": True,
     "member-order": "bysource",
@@ -59,11 +49,24 @@
     "exclude-members": "__weakref__",
 }
 
-# Autosummary
+autodoc_typehints = "description"
 autosummary_generate = True
 
-# Napoleon settings (if using Google/NumPy docstrings)
+# -- Napoleon settings -------------------------------------------------------
+
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
+
+# -- HTML output -------------------------------------------------------------
+
+html_theme = "furo"
+
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "navigation_with_keys": True,
+    "top_of_page_button": "edit",
+}
+
+html_title = "ML-FSM"