documentation improvements

wolearyc · Sep 22, 2024 · 0451106 · 0451106
1 parent c54d990
commit 0451106
Show file tree

Hide file tree

Showing 37 changed files with 965 additions and 499 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 ## About
 
-**Ramannoodle** is a Python API for efficiently calculating Raman spectra from first principles calculations. Ramannoodle supports molecular-dynamics- and phonon-based Raman calculations and includes interfaces with VASP.
+**Ramannoodle** is a Python API for efficiently calculating Raman spectra from first principles calculations. Ramannoodle supports molecular-dynamics- and phonon-based Raman calculations. It includes interfaces with VASP but can easily be used with other codes using IO from external libraries, such as [pymatgen](https://pymatgen.org/) or [ase](https://wiki.fysik.dtu.dk/ase/).
 
 Ramannoodle aims to be:
 
@@ -24,20 +24,18 @@ Ramannoodle aims to be:
 
     Ramannoodle is designed to give the user a good understanding of what is being calculated at varying levels of abstraction.
 
-Ramannoodle includes interfaces with:
-
-* VASP
-* phonopy (planned)
-
 ## Installation
 
-Ramannoodle can be installed via pip:
+The base version of ramannoodle can be installed with pip:
 
 ```
 $ pip install ramannoodle
 ```
 
-Due to idiosyncrasies with PyTorch's build system, installing ramannoodle's machine learning modules is slightly more involved. First, PyTorch must be installed ([pip commands](https://pytorch.org/get-started/locally/)). Then, corresponding torch-scatter and torch-sparse packages must be installed. Finally, Ramannoodle can then be installed with the appropriate options.
+Ramannoodle's machine learning modules are implemented with PyTorch. To use these modules:
+1. Install [PyTorch](https://pytorch.org/get-started/locally/).
+2. Install [torch-scatter](https://pypi.org/project/torch-scatter/) and [torch-sparse](https://pypi.org/project/torch-sparse/) corresponding to the PyTorch version/implementation.
+3.  Install ramannoodle using the `torch` options group.
 
 For example, installation on a Linux system using PyTorch 2.4.1 (cpu implementation) is done as follows:
 
@@ -57,10 +55,9 @@ Contributions in the form of bug reports, feature suggestions, and pull requests
 
 ## Citing
 
-coming soon...
-
-## Future releases
+To acknowledge use of ramannoodle, please cite
 
-* **0.4.0** | ML polarizability models
-* **0.5.0** | Advanced spectra analyses
-* **1.0.0** | Official release
+>> **Rapid Characterization of Point Defects in Solid-State Ion Conductors Using Raman Spectroscopy, Machine-Learning Force Fields, and Atomic Raman Tensors** <br>
+ W. O’Leary, M. Grumet, W. Kaiser, T. Bučko, J.L.M. Rupp, D.A. Egger <br>
+ Journal of the American Chemical Society (2024) <br>
+ doi: [10.1021/jacs.4c07812](https://pubs.acs.org/doi/10.1021/jacs.4c07812)
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,4 +2,5 @@ furo==2024.8.6
 ipython==8.26.0
 nbsphinx==0.9.4
 sphinx==7.4.7
+sphinx-autodoc-typehints==2.4.4
 sphinx-rtd-theme==2.0.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -26,8 +26,9 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    "sphinx_autodoc_typehints",
     'nbsphinx',
-    'IPython.sphinxext.ipython_console_highlighting'
+    'IPython.sphinxext.ipython_console_highlighting',
 ]
 autodoc_typehints = 'description'
 nbsphinx_allow_errors = True
@@ -36,6 +37,7 @@
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('http://docs.scipy.org/doc/numpy', None),
     'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
+    'torch': ('https://pytorch.org/docs/stable/', None),
 }
 
 intersphinx_disabled_domains = ['std']

diff --git a/docs/source/generated/ramannoodle.dynamics.rst b/docs/source/generated/ramannoodle.dynamics.rst
@@ -1,4 +1,4 @@
-ramannoodle.dynamics package
+dynamics
 ============================
 
 Submodules

diff --git a/docs/source/generated/ramannoodle.io.rst b/docs/source/generated/ramannoodle.io.rst
@@ -1,4 +1,4 @@
-ramannoodle.io package
+io
 ======================
 
 Subpackages

diff --git a/docs/source/generated/ramannoodle.io.vasp.rst b/docs/source/generated/ramannoodle.io.vasp.rst
@@ -1,4 +1,4 @@
-ramannoodle.io.vasp package
+io.vasp
 ===========================
 
 Submodules

diff --git a/docs/source/generated/ramannoodle.polarizability.rst b/docs/source/generated/ramannoodle.polarizability.rst
@@ -1,6 +1,14 @@
-ramannoodle.polarizability package
+polarizability
 ==================================
 
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   ramannoodle.polarizability.torch
+
 Submodules
 ----------
 

diff --git a/docs/source/generated/ramannoodle.polarizability.torch.rst b/docs/source/generated/ramannoodle.polarizability.torch.rst
@@ -1,4 +1,4 @@
-ramannoodle.polarizability.torch package
+polarizability.torch
 ========================================
 
 Submodules
@@ -12,18 +12,18 @@ ramannoodle.polarizability.torch.dataset module
    :undoc-members:
    :show-inheritance:
 
-ramannoodle.polarizability.torch.dummy\_dataset module
-------------------------------------------------------
+ramannoodle.polarizability.torch.gnn module
+-------------------------------------------
 
-.. automodule:: ramannoodle.polarizability.torch.dummy_dataset
+.. automodule:: ramannoodle.polarizability.torch.gnn
    :members:
    :undoc-members:
    :show-inheritance:
 
-ramannoodle.polarizability.torch.gnn module
--------------------------------------------
+ramannoodle.polarizability.torch.train module
+---------------------------------------------
 
-.. automodule:: ramannoodle.polarizability.torch.gnn
+.. automodule:: ramannoodle.polarizability.torch.train
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/generated/ramannoodle.spectrum.rst b/docs/source/generated/ramannoodle.spectrum.rst
@@ -1,4 +1,4 @@
-ramannoodle.spectrum package
+spectrum
 ============================
 
 Submodules

diff --git a/docs/source/generated/ramannoodle.structure.rst b/docs/source/generated/ramannoodle.structure.rst
@@ -1,4 +1,4 @@
-ramannoodle.structure package
+structure
 =============================
 
 Submodules

diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -3,8 +3,8 @@ Introduction
 
 A chemical system's Raman spectrum reflects the frequencies and amplitudes at which the components of its **polarizability** -- a 3x3 tensor -- fluctuate due to thermal atomic motion. We must answer two questions to calculate a Raman spectrum of a collection of atoms:
 
-1. How do the atoms "jiggle" at finite temperatures?
-2. How does each jiggle modulate polarizability?
+1. How do the atoms vibrate at finite temperatures?
+2. How does each vibration modulate polarizability?
 
 To answer question (1), we often consider the system's vibrational normal modes, i.e., phonons in the case of periodic systems. However, in cases where atomic motion is appreciably anharmonic, the phonon picture misses important features. In these cases, we use molecular dynamics to understand, at least in a statistical sense, exactly how the atoms move as a function of time.
 
@@ -17,18 +17,12 @@ Unfortunately, the need to calculate so many polarizabilities can make Raman spe
 Installation
 ------------
 
-Ramannoodle can be installed -- as is standard for Python packages -- with pip:
+Please see ramannoodle's `repo <https://github.com/wolearyc/ramannoodle>`_ for up-to-date installation instructions.
 
-.. code-block:: console
+Citing
+------
 
-      $ pip install ramannoodle
-
-So long as your Python environment is configured correctly, you should be good to go:
-
-.. code-block:: python
-
-    import ramannoodle
-    # ...
+Please see ramannoodle's `repo <https://github.com/wolearyc/ramannoodle>`_ for up-to-date citation information.
 
 Modules
 --------

diff --git a/docs/source/notebooks/machine-learning.ipynb b/docs/source/notebooks/machine-learning.ipynb
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -9,3 +9,4 @@ Tutorials
    notebooks/full-workflow
    notebooks/molecular-dynamics
    notebooks/masking
+   notebooks/machine-learning
diff --git a/ramannoodle/dynamics/abstract.py b/ramannoodle/dynamics/abstract.py
@@ -18,5 +18,5 @@ def get_raman_spectrum(
         Parameters
         ----------
         polarizability_model
-            | Must be compatible with the dynamics.
+            Must be compatible with the dynamics.
         """
diff --git a/ramannoodle/dynamics/phonon.py b/ramannoodle/dynamics/phonon.py
@@ -1,4 +1,4 @@
-"""Harmonic lattice vibrations aka phonons."""
+"""Harmonic lattice vibrations."""
 
 import numpy as np
 from numpy.typing import NDArray
@@ -21,11 +21,11 @@ class Phonons(Dynamics):
     Parameters
     ----------
     ref_positions
-        | (fractional) 2D array with shape (N,3) where N is the number of atoms.
+        (fractional) Array with shape (N,3) where N is the number of atoms.
     wavenumbers
-        | (cm\ :sup:`-1`) 1D array with shape (M,).
+        (cm\ :sup:`-1`) Array with shape (M,).
     displacements
-        | (fractional) 3D array with shape (M,N,3).
+        (fractional) Array with shape (M,N,3).
     """
 
     def __init__(
@@ -52,7 +52,7 @@ def ref_positions(self) -> NDArray[np.float64]:
         Returns
         -------
         :
-            (fractional) 2D array with shape (N,3) where N is the number of atoms.
+            (fractional) Array with shape (N,3) where N is the number of atoms.
         """
         return self._ref_positions.copy()
 
@@ -63,7 +63,7 @@ def wavenumbers(self) -> NDArray[np.float64]:
         Returns
         -------
         :
-            (cm\ :sup:`-1`) 1D array with shape (M,) where M is the number of phonons.
+            (cm\ :sup:`-1`) Array with shape (M,) where M is the number of phonons.
         """
         return self._wavenumbers.copy()
 
@@ -74,7 +74,7 @@ def displacements(self) -> NDArray[np.float64]:
         Returns
         -------
         :
-            (fractional) 3D array with shape (M,N,3) where M is the number of phonons
+            (fractional) Array with shape (M,N,3) where M is the number of phonons
             and N is the number of atoms.
         """
         return self._displacements.copy()
@@ -87,7 +87,7 @@ def get_raman_spectrum(
         Parameters
         ----------
         polarizability_model
-            | Must be compatible with phonons.
+            Must be compatible with phonons.
         """
         raman_tensors = []
         for displacement in self._displacements:

diff --git a/ramannoodle/dynamics/trajectory.py b/ramannoodle/dynamics/trajectory.py
@@ -1,4 +1,4 @@
-"""Molecular dynamics trajectories."""
+"""Molecular dynamics trajectory."""
 
 from collections.abc import Sequence
 from typing import overload
@@ -22,10 +22,10 @@ class Trajectory(Dynamics, Sequence[NDArray[np.float64]]):
     Parameters
     ----------
     positions_ts
-        | (fractional) 3D array with shape (S,N,3) where S in the number of
-        | configurations and N is the number of atoms.
+        (fractional) Array with shape (S,N,3) where S in the number of
+        configurations and N is the number of atoms.
     timestep
-        | (fs)
+        (fs)
 
     """
 
@@ -52,14 +52,20 @@ def positions_ts(self) -> NDArray[np.float64]:
         Returns
         -------
         :
-            (fractional) 3D array with shape (S,N,3) where S in the number of
+            (fractional) Array with shape (S,N,3) where S in the number of
             configurations and N is the number of atoms.
         """
         return self._positions_ts.copy()
 
     @property
     def timestep(self) -> float:
-        """Get timestep in fs."""
+        """Get timestep.
+
+        Returns
+        -------
+        :
+            (fs)
+        """
         return self._timestep
 
     def get_raman_spectrum(
@@ -70,7 +76,7 @@ def get_raman_spectrum(
         Parameters
         ----------
         polarizability_model
-            | Must be compatible with the trajectory.
+            Must be compatible with the trajectory.
         """
         try:
             polarizability_ts = polarizability_model.calc_polarizabilities(

diff --git a/ramannoodle/exceptions.py b/ramannoodle/exceptions.py
@@ -10,11 +10,11 @@ class NoMatchingLineFoundException(Exception):
 
 
 class InvalidFileException(Exception):
-    """File cannot be read, likely due to due to invalid or unexpected format."""
+    """File cannot not be read, likely due to due to invalid or unexpected format."""
 
 
 class IncompatibleStructureException(Exception):
-    """Supplied file is incompatible."""
+    """File contains structure that is incompatible with the current operation."""
 
 
 class InvalidDOFException(Exception):
@@ -41,8 +41,7 @@ class UserError(Exception):
 def _shape_string(shape: Sequence[int | None]) -> str:
     """Get a string representing a shape.
 
-    Maps None --> "_", indicating that this element can
-    be anything.
+    Maps None --> "_", indicating that this element can be anything.
     """
     result = "("
     for i in shape:
@@ -109,7 +108,7 @@ def verify_ndarray_shape(
 def verify_list_len(name: str, array: list[Any], length: int | None) -> None:
     """Verify an list's shape.
 
-    We should avoid calling this function whenever possible (EATF).
+    Calling function should be avoided whenever possible (EATF).
 
     :meta private: