documentation pass

docs/source/dev guide.rst

@@ -0,0 +1,54 @@
+Dev Guide
+=========
+
+Contributions to ramannoodle - in the form of bug reports, feature suggestions, pull requests, etc. -  are always welcome! We are particularly interested in adding new interfaces for first-principles codes as well as new polarizability models. This document provides a few development guidelines. Please reach out on Github with any questions or if you want to collaborate :)
+
+Workflow
+--------
+
+Ramannoodle is hosted on Github:
+
+`https://github.com/wolearyc/ramannoodle <https://github.com/wolearyc/ramannoodle>`_
+
+The project uses `pre-commit <https://pre-commit.com/>`_ with a range of hooks that help ensure high code quality and consistency. You are strongly encouraged to use it frequently, as all pull requests need to pass CI pre-commit before merge! Pre-commit can be installed with pip
+
+.. code-block:: console
+
+      $ pip install pre-commit
+
+and can be run from the repository's root directory with
+
+.. code-block:: console
+
+      $ pre-commit run --all
+
+Ramannoodle includes a test suite that uses the `pytest <https://docs.pytest.org/en/stable/>`_ framework. Pull requests must pass all CI tests in order to be merged. New tests should be developed for any new functionality.
+
+Ramannoodle's documentation is built with `Sphinx <https://www.sphinx-doc.org/en/master/>`_. The documentation can be built by running
+
+.. code-block:: console
+
+      $ make html
+
+in the docs directory. The resulting html is available in build/html.
+
+Guidelines
+----------
+
+In no particular order, here are some guidelines that are followed throughout ramannoodle:
+
+* Since `mypy <https://mypy-lang.org/>`_ is used, type hints are mandatory.
+
+* Whenever possible, use the EAFP (as opposed to LBYL) principle when raising exceptions.
+
+* Use numpy-style docstrings.
+
+* All public-facing functions should raise descriptive TypeError and ValueError exceptions when invalid arguments are provided. These sorts of exceptions should not be documented in the docstring.
+
+* All array arguments should be numpy arrays. This should be enforced, when appropriate, through exceptions.
+
+* Docstring descriptions for array arguments should provide a dimension and shape. Uppercase letters can be used for cases where shape is variable. For example, "4D array with shape (M,N,3) where M is ... and N is ...".
+
+* Unless otherwise noted, fractional coordinates are always used. Variables for cartesian coordinates always have "cartesian\_" appended.
+
+* Use classes widely. Sometimes, a regular function is all that is needed!

docs/source/index.rst

@@ -6,10 +6,14 @@
 ramannoodle documentation
 =========================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+**ramannoodle** is a Python API for calculating Raman spectra from first principles calculations in an efficient, flexible, and transparent way.
 
+.. note::
+
+   ramannoodle is currently in alpha.
+
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
@@ -18,4 +22,4 @@ documentation for details.
    introduction
    notebooks/Basic tutorial
    generated/api
-   generated/modules
+   dev guide

docs/source/introduction.rst

@@ -8,14 +8,16 @@ A chemical system's Raman spectrum reflects the frequencies and amplitudes at wh
 
 To answer question (1), we often simply consider the system's vibrational normal modes, i.e., phonons in the case of periodic systems. However, in cases where atomic motions are strongly 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.
 
-With the atomic dynamics in hand, answering question (2), is, at least conceptually, quite straightforward. When considering phonons, we  calculate a **Raman tensor** for each phonon; mathematically speaking, this is a directional derivative of polarizability in the direction of that a phonon displacement. When using molecular dynamics, our task is even simpler; we simply calculate the polarizability at every timestep and assemble a **polarizability time series.** Unfortunately, calculation of polarizabilities comes with a high computational cost. This costs can quickly balloon, especially when treating large and/or complex systems. These costs ultimately make Raman spectra calculations impractical for many of the most interesting and technologically relevant systems.
+With the atomic dynamics in hand, answering question (2), is, at least conceptually, quite straightforward. When considering phonons, we  calculate a **Raman tensor** for each phonon; mathematically speaking, this is a directional derivative of polarizability in the direction of that a phonon displacement. We evaluate this derivative using central differences, which requires ~2 polarizability calculations per phonon. When using molecular dynamics, our task is even simpler; we calculate the polarizability at every timestep and assemble a **polarizability time series.**
 
-ramannoodle was designed to reduce the cost to calculate Raman spectra from first principles. It does this by providing an efficient :class:`~ramannoodle.polarizability.interpolation.InterpolationPolarizabilityModel`, which leverages structural symmetries to greatly reduce the number of required first principles polarizability calculations. The plan is to extend this API with additional models and capabilities that will make computing Raman spectra (and ultimately interpreting experimental Raman spectra) a breeze.
+Unfortunately, the need to calculate so many polarizabilities can make Raman spectrum calculations rather computationally costly. These costs can quickly balloon, especially when treating large and/or complex systems. These costs ultimately make Raman spectra calculations impractical for many of the most interesting and technologically relevant materials.
+
+**ramannoodle** was designed to reduce the cost to calculate Raman spectra from first principles. It does this by providing an efficient :class:`~ramannoodle.polarizability.interpolation.InterpolationPolarizabilityModel`, which leverages structural symmetries to greatly reduce the number of required first principles polarizability calculations. The plan is to extend this API with additional models and capabilities that will make computing Raman spectra a breeze and, consequently, make Raman spectroscopy a more powerful characterization tool.
 
 Installation
 ------------
 
-ramannoodle can be installed, like nearly all Python packages, with pip:
+ramannoodle can be installed - as as standard for Python packages - with pip:
 
 .. code-block:: console
 
@@ -58,4 +60,4 @@ Ramannoodle's basic workflow is as follows:
 2. We construct a polarizability model, which maps atomic positions to polarizabilities. We build-up (or train) this model by feeding in polarizability data calculated from first principles calculations.
 3. We combine the polarizability model with the dynamics to compute a Raman spectrum.
 
-A complete tutorial can be found in the next page: :doc:`notebooks/Basic tutorial`
+Next, we will walk through a concrete example: :doc:`../notebooks/Basic tutorial`

docs/notebooks/Basic tutorial.ipynb → docs/source/notebooks/Basic tutorial.ipynb

@@ -60,12 +60,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "6102769c-0416-497a-b6a9-e451b66ca71d",
    "metadata": {},
    "outputs": [],
    "source": [
-    "data_dir = \"../../test/data/TiO2\"\n",
+    "data_dir = \"../../../test/data/TiO2\"\n",
     "# phonon_OUTCAR contains phonons (duh) as well as the equilibrium TiO2 structure.\n",
     "phonon_outcar = f\"{data_dir}/phonons_OUTCAR\"\n",
     "\n",
@@ -85,7 +85,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "id": "f14761e9-96a8-4317-94cb-47153683eb88",
    "metadata": {},
    "outputs": [],