polished documentation

README.md

@@ -8,7 +8,9 @@
 
 ## About
 
-**ramannoodle** is a Python API for calculating Raman spectra from first-principles calculations. Ramannoodle is built from the ground up with the goals of being:
+**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 designed from the ground up to be:
 
 1. **EFFICIENT**
 
@@ -22,14 +24,14 @@
 
     Ramannoodle is designed to give the user a good understanding of what is being calculated at varying levels of abstraction.
 
-**Ramannoodle interfaces with...**
+Ramannoodle includes interfaces with:
 
 * VASP
 * phonopy (planned)
 
 ## Installation
 
-ramannoodle can be installed via pip:
+Ramannoodle can be installed via pip:
 
 `
 $ pip install ramannoodle
@@ -41,20 +43,14 @@ $ pip install ramannoodle
 
 ## Contributing
 
-Contributions in the form of bug reports, feature suggestions, and pull requests are always welcome! Those contributing code should check out the [dev guide](https://ramannoodle.readthedocs.io/en/latest/dev%20guide.html).
+Contributions in the form of bug reports, feature suggestions, and pull requests are always welcome! Those contributing code should check out the [dev guide](https://ramannoodle.readthedocs.io/en/latest/development.html).
 
 ## Citing
 
 coming soon...
 
 ## Future releases
 
-**0.3.0**
-* Support for molecular dynamics
-* IO support for Phonopy
-
-**1.0.0**
-* Official release and fixed public API
-
-**1.1.0**
-* ML polarizability models
+* **0.4.0** | ML polarizability models
+* **0.5.0** | Advanced spectra analyses
+* **1.0.0** | Official release

docs/gen_api_sources.sh

@@ -0,0 +1,2 @@
+# CD must be the reports directory!
+sphinx-apidoc -o source/generated ../ramannoodle

docs/source/dev guide.rst → docs/source/development.rst

@@ -1,5 +1,5 @@
-Dev Guide
-=========
+Development
+===========
 
 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 to first-principles codes as well as developing new polarizability models. This document provides a few development guidelines. Please reach out on Github with any questions or if you want to collaborate :)
 

docs/source/guides.rst

@@ -5,9 +5,5 @@ Guides
    :maxdepth: 2
    :caption: Contents:
 
-   notebooks/Basic tutorial
-   notebooks/Full tutorial
-   notebooks/Molecular dynamics
-   notebooks/Masking
    io
    units

docs/source/index.rst

@@ -6,13 +6,18 @@
 ramannoodle documentation
 =========================
 
-**Ramannoodle** is a Python API for calculating Raman spectra from first principles calculations in an efficient, flexible, and transparent way.
+**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.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    introduction
+   tutorials
    guides
    API <generated/ramannoodle>
-   dev guide
+   development
+
+.. |br| raw:: html
+
+   <br />

docs/source/introduction.rst

@@ -1,23 +1,23 @@
 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. Therefore, we must answer two questions to calculate a Raman spectrum:
+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?
 
-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.
+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.
 
-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 a phonon's displacement. We evaluate this derivative using central differences, which conventionally requires 2 polarizability calculations  per phonon (though the exact number required depends on structural symmetries). When using molecular dynamics, our task is even simpler; we calculate the polarizability at every timestep and assemble a **polarizability time series.**
+With the atomic dynamics in hand, answering question (2) is conceptually straightforward. When considering phonons, we calculate a **Raman tensor** for each phonon; mathematically speaking, a Raman tensor is the polarizability derivative in the direction of a phonon's displacement. We evaluate this derivative using central differences, which conventionally requires 2 polarizability calculations per phonon (though the exact number required depends on structural symmetries). When considering molecular dynamics, we calculate the polarizability at every timestep and assemble a **polarizability time series.**
 
-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. This ultimately makes conventional Raman spectrum calculations impractical for many of the most interesting and technologically relevant materials.
+Unfortunately, the need to calculate so many polarizabilities can make Raman spectrum calculations very computationally costly. These costs can quickly balloon, especially when treating large and/or complex systems. This ultimately makes conventional Raman spectrum calculations impractical for many of the most interesting and technologically relevant materials.
 
-**Ramannoodle** was designed to reduce the computational cost of first principles Raman calculations. It accomplishes this by providing efficient polarizability models. For example, :class:`~ramannoodle.polarizability.art.ARTModel` and :class:`~ramannoodle.polarizability.interpolation.InterpolationModel` leverage structural symmetries to greatly reduce the number of required first principles polarizability calculations. We hope that current and future versions of this API will make computing Raman spectra simpler and, consequently, make Raman spectroscopy a more powerful characterization tool.
+Ramannoodle's **primary purpose** is to reduce the computational cost of first principles Raman calculations. It accomplishes this by providing efficient polarizability models. For example, :class:`~ramannoodle.polarizability.art.ARTModel` and :class:`~ramannoodle.polarizability.interpolation.InterpolationModel` leverage structural symmetries to greatly reduce the number of required first principles polarizability calculations. We hope that current and future versions of this API will make computing Raman spectra simpler and, consequently, make Raman spectroscopy a more powerful characterization tool.
 
 Installation
 ------------
 
-Ramannoodle can be installed - as is standard for Python packages - with pip:
+Ramannoodle can be installed -- as is standard for Python packages -- with pip:
 
 .. code-block:: console
 
@@ -69,4 +69,4 @@ Ramannoodle's basic workflow is as follows:
 2. 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. Combine the polarizability model with the dynamics to compute a Raman spectrum.
 
-Next, we will walk through a concrete example: :doc:`../notebooks/Basic tutorial`
+Next, we will walk through a concrete example: :doc:`../notebooks/basics`

docs/source/io.rst

@@ -1,7 +1,7 @@
 Interfacing with first-principles software
 ==========================================
 
-Ramannoodle includes routines for reading and writing files used by quantum chemistry software. Currently, ramannoodle only supports VASP. However, we hope to include interfaces with other codes in future versions.
+Ramannoodle includes routines for reading and writing files used by quantum chemistry software. Currently, ramannoodle only supports VASP. We hope to include community-contributed interfaces with other codes in future versions.
 
 IO
 ---
@@ -55,4 +55,4 @@ The following table reviews which file types and properties are currently suppor
 +---------------------------------+------------------------------+-------------------+----------------------+----------------------+----------------+
 
 :sup:`1` Uses initial structure.
-:sup:`2` Not available in ``generic_io``
+:sup:`2` Not available in :mod:`ramannoodle.io.generic`