documentation sweep and version bump

README.md

@@ -27,7 +27,7 @@ ramannoodle is built from the ground up with the goals of being:
 
     ramannoodle is designed according to the philosophy that the user should understand *exactly* what is being calculated, without hidden corrections or assumptions.
 
-## Supported DFT Software
+**ramannoodle interfaces with...**
 
 * VASP (currently under development)
 * phonopy (planned)
@@ -40,6 +40,10 @@ ramannoodle can be installed via pip:
 pip install ramannoodle
 `
 
+## Documentation
+
+[https://ramannoodle.readthedocs.io/](https://ramannoodle.readthedocs.io/)
+
 ## Contributing
 
 Contributions in the form of bug reports, feature suggestions, and pull requests are always welcome!
@@ -50,17 +54,10 @@ coming soon...
 
 ## Roadmap
 
-Current release: v.0.1.0-alpha
+Current release: v0.1.1-alpha
 
 Future releases:
 
-**v.0.1.1-alpha**
-
-* Major improvements to exception and error handling.
-* Draft documentation, including a basic tutorial
-* Symmetry generation is now much faster
-* Minor bugfixes and documentation updates
-
 
 **v.0.1.2-alpha**
 * Utilities to help set up calculations for `InterpolationPolarizabilityModel`, including displaced structure writing functionality.

docs/source/conf.py

@@ -16,7 +16,7 @@
 project = 'ramannoodle'
 copyright = "2024, Willis O'Leary"
 author = "Willis O'Leary"
-release = 'v.0.1.1-alpha'
+release = 'v0.1.1-alpha'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

ramannoodle/dynamics/__init__.py

@@ -35,11 +35,6 @@ class Phonons(Dynamics):
     cartesian_displacements
         3D array with shape (M,N,3) where N is the number of atoms
 
-    Raises
-    ------
-    ValueError
-    TypeError
-
     """
 
     def __init__(
@@ -72,12 +67,7 @@ def __init__(
     def get_raman_spectrum(
         self, polarizability_model: PolarizabilityModel
     ) -> PhononRamanSpectrum:
-        """Calculate a raman spectrum using a polarizability model.
-
-        Raises
-        ------
-        ValueError
-        """
+        """Calculate a raman spectrum using a polarizability model."""
         raman_tensors = []
         for cartesian_displacement in self._cartesian_displacements:
             try:

ramannoodle/io/__init__.py

@@ -32,7 +32,9 @@ def read_phonons(filepath: str | Path, file_format: str) -> Phonons:
     Raises
     ------
     InvalidFileException
-    ValueError
+        File has unexpected format.
+    FileNotFoundError
+        File could not be found.
     """
     try:
         return _PHONON_LOADERS[file_format](filepath)
@@ -61,7 +63,9 @@ def read_positions_and_polarizability(
     Raises
     ------
     InvalidFileException
-    ValueError
+        File has unexpected format.
+    FileNotFoundError
+        File could not be found.
     """
     try:
         return _POSITION_AND_POLARIZABILITY_LOADERS[file_format](filepath)
@@ -87,10 +91,9 @@ def read_structural_symmetry(
     Raises
     ------
     InvalidFileException
-        If the OUTCAR has an unexpected format.
-    SymmetryException
-        If OUTCAR was read but the symmetry search failed
-    ValueError
+        File has unexpected format.
+    FileNotFoundError
+        File could not be found.
     """
     try:
         return _STRUCTURAL_SYMMETRY_LOADERS[file_format](filepath)

ramannoodle/io/vasp/__init__.py

@@ -32,8 +32,9 @@ def read_phonons_from_outcar(filepath: str | Path) -> Phonons:
     Raises
     ------
     FileNotFoundError
+        File not found.
     InvalidFileException
-        If the OUTCAR has an unexpected format.
+        File has an unexpected format.
     """
     wavenumbers = []
     eigenvectors = []

ramannoodle/polarizability/interpolation.py

@@ -31,7 +31,7 @@ def get_amplitude(
     )
 
 
-class InterpolationPolarizabilityModel(PolarizabilityModel):
+class InterpolationModel(PolarizabilityModel):
     """Polarizability model based on interpolation around degrees of freedom.
 
     One is free to specify the interpolation order as well as the precise
@@ -50,11 +50,6 @@ class InterpolationPolarizabilityModel(PolarizabilityModel):
         2D array with shape (3,3) giving polarizability of system at equilibrium. This
         would usually correspond to the minimum energy structure.
 
-    Raises
-    ------
-    ValueError
-    TypeError
-
     """
 
     def __init__(
@@ -85,10 +80,6 @@ def get_polarizability(
         :
             2D array with shape (3,3)
 
-        Raises
-        ------
-        TypeError
-        ValueError
         """
         delta_polarizability: NDArray[np.float64] = np.zeros((3, 3))
         for basis_vector, interpolation in zip(
@@ -128,21 +119,22 @@ def add_dof(  # pylint: disable=too-many-locals
         ----------
         displacement
             2D array with shape (N,3) where N is the number of atoms. Units
-            are arbitrary.
+            are arbitrary. Must be orthogonal to all previously added DOFs.
         amplitudes
-            1D array of length L containing amplitudes in angstroms.
+            1D array of length L containing amplitudes in angstroms. Duplicate
+            amplitudes are not allowed, including symmetrically equivalent
+            amplitudes.
         polarizabilities
             3D array with shape (L,3,3) containing known polarizabilities for
             each amplitude.
         interpolation_order
-            must be less than the number of total number of amplitudes after
+            Must be less than the number of total number of amplitudes after
             symmetry considerations.
 
         Raises
         ------
         InvalidDOFException
-        ValueError
-        TypeError
+            Provided degree of freedom was invalid.
 
         """
         try:
@@ -260,10 +252,10 @@ def add_dof_from_files(
 
         Raises
         ------
-        TypeError
         FileNotFoundError
+            File could not be found.
         InvalidDOFException
-        ValueError
+            DOF assembled from supplied files was invalid (see get_dof)
 
         """
         # Extract displacements, polarizabilities, and basis vector

ramannoodle/spectrum/__init__.py

@@ -17,10 +17,6 @@ class PhononRamanSpectrum:  # pylint: disable=too-few-public-methods
     raman_tensors
         an ndarray with shape (M,3,3)
 
-    Raises
-    ------
-    ValueError
-    TypeError
     """
 
     def __init__(
@@ -66,8 +62,8 @@ def measure(  # pylint: disable=too-many-arguments
 
         Raises
         ------
-        ValueError
         NotImplementedError
+            Raised when any orientation besides "polycrystalline" is supplied.
 
         """
         if orientation != "polycrystalline":

ramannoodle/spectrum/spectrum_utils.py

@@ -55,10 +55,6 @@ def get_laser_correction(
     :
         Correction factor for each wavenumber.
 
-    Raises
-    ------
-    ValueError
-
     """
     try:
         if laser_wavenumber <= 0:
@@ -98,10 +94,6 @@ def convolve_intensities(
     :
         2-tuple containing wavenumbers and corresponding intensities
 
-    Raises
-    ------
-    ValueError
-    TypeError
     """
     if out_wavenumbers is None:
         out_wavenumbers = np.linspace(

ramannoodle/symmetry/__init__.py

@@ -23,6 +23,12 @@ class StructuralSymmetry:
         Symmetry precision parameter for spglib.
     angle_tolerance
         Symmetry precision parameter for spglib.
+
+    Raises
+    ------
+    SymmetryException
+        Symmetry could not be determined for supplied structure.
+
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -48,7 +54,7 @@ def __init__(  # pylint: disable=too-many-arguments
             spglib.get_symmetry(cell, symprec=symprec, angle_tolerance=angle_tolerance)
         )
         if self._symmetry_dict is None:
-            raise SymmetryException("symmetry search failed")
+            raise SymmetryException("Symmetry search failed. Check structure.")
 
         self._rotations = self._symmetry_dict["rotations"]
         self._translations = self._symmetry_dict["translations"]

ramannoodle/symmetry/symmetry_utils.py

@@ -22,11 +22,6 @@ def are_collinear(vector_1: NDArray[np.float64], vector_2: NDArray[np.float64])
     vector_2
         ndarray with shape (M,)
 
-    Raises
-    ------
-    TypeError
-    ValueError
-
     """
     try:
         vector_1 = vector_1 / float(np.linalg.norm(vector_1))
@@ -56,10 +51,6 @@ def is_orthogonal_to_all(
     int
         first index of non-orthogonal vector, otherwise -1
 
-    Raises
-    ------
-    TypeError
-
     """
     # This implementation could be made more efficient.
     try:
@@ -122,13 +113,7 @@ def compute_permutation_matrices(
     translations: NDArray[np.float64],
     fractional_positions: NDArray[np.float64],
 ) -> NDArray[np.float64]:
-    """Expresses a series of rotation/translations as permutation matrices.
-
-    Raises
-    ------
-    SymmetryException
-
-    """
+    """Expresses a series of rotation/translations as permutation matrices."""
     # Ensure no atom is at unit cell boundary by shifting
     # center of mass
     center_of_mass_shift = np.array([0.5, 0.5, 0.5]) - np.mean(
@@ -155,16 +140,18 @@ def _get_fractional_positions_permutation_matrix(
 ) -> NDArray[np.float64]:
     """Calculate a permutation matrix between reference and permuted positions.
 
+    .. warning::
+        Arguments must be true permutations of each other. This function does not
+        correct for periodic boundary conditions, so it needs to be supplied a
+        structure without atoms at the unit cell boundaries.
+
     Parameters
     ----------
     reference_positions
         A 2D array with shape (N,3)
     permuted_positions
         A 2D array with shape (N,3).
 
-    Raises
-    ------
-    SymmetryException
     """
     reference_positions = apply_pbc(reference_positions)
     permuted_positions = apply_pbc(permuted_positions)
@@ -195,13 +182,7 @@ def transform_fractional_positions(
     rotation: NDArray[np.float64],
     translation: NDArray[np.float64],
 ) -> NDArray[np.float64]:
-    """Transform fractional coordinates under periodic boundary conditions.
-
-    Raises
-    ------
-    TypeError
-    ValueError
-    """
+    """Transform fractional coordinates under periodic boundary conditions."""
     verify_positions("positions", positions)
     positions = apply_pbc(positions)
     try:
@@ -229,10 +210,9 @@ def calculate_displacement(
     positions_1: NDArray[np.float64],
     positions_2: NDArray[np.float64],
 ) -> NDArray[np.float64]:
-    """Subtracts fractional positions under periodic boundary conditions.
-
-    Returns a displacement.
+    """Calculate displacement between two fractional positions.
 
+    Respects periodic boundary conditions.
     """
     positions_1 = apply_pbc(positions_1)
     positions_2 = apply_pbc(positions_2)

setup.py

@@ -1,12 +1,20 @@
 """Setup."""
 
 from setuptools import setup
+from pathlib import Path
+
+
+# read the contents of README
+this_directory = Path(__file__).parent
+long_description = (this_directory / "README.md").read_text()
+
 
 setup(
     name='ramannoodle',
-    version='1.0.0-alpha',
-    description='Raman spectra from first principles calculations.',
-    long_description='Raman spectra from first principles calculations. Supports VASP.',
+    version='v0.1.1-alpha',
+    description='Helps calculate Raman spectra from first-principles calculations.',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
     author="Willis O'Leary",
     author_email='wolearyc@gmail.com',
     license='MIT',