Merge pull request #13 from wolearyc/dev

PR 0.3.0

.github/dependabot.yml

@@ -5,11 +5,20 @@
 
 version: 2
 updates:
-- package-ecosystem: pip
-  directory: "/"
-  schedule:
-    interval: weekly
-  groups:
-    python-packages:
-      patterns:
-        - "*"
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-packages:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      action-packages:
+        patterns:
+          - "*"

.github/workflows/python-package.yml

@@ -9,13 +9,14 @@ on:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.10", "3.11", "3.12"]
+        uv-arg: ["--resolution=lowest", ""]
 
+    runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
@@ -25,15 +26,17 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
+        pip install uv
+        uv pip install ${{ matrix.uv-arg }} --system -r requirements.txt
     - name: Analyzing the code with pylint
+      if: ${{ matrix.os != 'windows-latest' }} # Windows throws strange linting errors
       run: |
         pylint $(git ls-files '*.py')
     - name: Analyzing the code with flake8
       uses: py-actions/flake8@v2
       with:
         max-line-length: "88"
-        args: "--docstring-convention=numpy"
+        args: "--docstring-convention=numpy --extend-ignore=E203,D105"
         plugins: "flake8-bugbear==24.4.26 flake8-docstrings"
     - name: Test with pytest
       run: |

.pre-commit-config.yaml

@@ -42,10 +42,10 @@ repos:
           ]
         exclude: "conf.py"
 -   repo: https://github.com/pycqa/flake8
-    rev: '7.1.1'  # pick a git hash / tag to point to
+    rev: '7.1.1'
     hooks:
     -   id: flake8
-        args: [--max-line-length=88, --docstring-convention=numpy]
+        args: ["--max-line-length=88", "--docstring-convention=numpy", "--extend-ignore=E203,D105"]
         additional_dependencies:
           [
             flake8-bugbear, flake8-docstrings, flake8-absolute-import

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

cspell.json

@@ -10,11 +10,14 @@
         "anharmonic",
         "ANSICOLORS",
         "argmax",
+        "atominfo",
         "automodule",
         "AVOGADROS",
         "Daltons",
+        "defusedxml",
         "docstrings",
         "dtype",
+        "dynmat",
         "EAFP",
         "EATF",
         "equil",
@@ -27,6 +30,7 @@
         "Grumet",
         "ifft",
         "Imaginarium",
+        "initialpos",
         "interp",
         "LBYL",
         "lexsort",
@@ -49,12 +53,15 @@
         "polarizabilities",
         "POSCAR",
         "POTCAR",
+        "POTIM",
         "pylint",
         "pytest",
         "quickstart",
         "Raman",
         "ramannoodle",
         "repr",
+        "rint",
+        "savez",
         "spglib",
         "symprec",
         "tablefmt",
@@ -63,12 +70,15 @@
         "toctree",
         "undoc",
         "Unitless",
+        "varray",
+        "varrays",
         "VASP",
         "vasprun",
         "VRHFIN",
         "wavenumber",
         "wavenumbers",
-        "wspace"
+        "wspace",
+        "XDATCAR"
     ],
     "ignoreWords": [],
     "import": []

docs/gen_api_sources.sh

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

docs/requirements.txt

@@ -1,5 +1,5 @@
-furo
-ipython
+furo==2024.8.6
+ipython==8.26.0
 nbsphinx==0.9.4
 sphinx==7.4.7
 sphinx-rtd-theme==2.0.0

docs/source/conf.py

@@ -16,7 +16,7 @@
 project = 'ramannoodle'
 copyright = "2023-present, Willis O'Leary"
 author = "Willis O'Leary"
-release = '0.2.1'
+release = '0.3.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -30,6 +30,7 @@
     'IPython.sphinxext.ipython_console_highlighting'
 ]
 autodoc_typehints = 'description'
+nbsphinx_allow_errors = True
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
@@ -42,8 +43,6 @@
 templates_path = ['_templates']
 exclude_patterns = []
 
-language = 'Python'
-
 autodoc_member_order = 'groupwise'
 
 # -- Options for HTML output -------------------------------------------------

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 :)
 
@@ -30,7 +30,13 @@ Ramannoodle's documentation is built with `Sphinx <https://www.sphinx-doc.org/en
 
       $ make html
 
-from within the ``docs`` directory. The resulting html is available in ``docs/build/html``.
+from within the ``docs`` directory. The resulting html is available in ``docs/build/html``. After adding new modules, Sphinx source files must be generated with ``sphinx-apidoc``. This can be done by running
+
+.. code-block:: console
+
+      $ bash gen_api_sources.sh
+
+from within the ``docs`` directory.
 
 Test coverage reports and badges can be generated by running
 
@@ -43,7 +49,7 @@ from within the ``docs`` directory. The coverage report html can be found in ``r
 Guidelines
 ----------
 
-In no particular order, here are some guidelines that are followed throughout ramannoodle:
+In no particular order, here are some development guidelines:
 
 * Since `mypy <https://mypy-lang.org/>`_ is used, type hints are mandatory.
 
@@ -61,4 +67,4 @@ In no particular order, here are some guidelines that are followed throughout ra
 
 * Ramannoodle uses a mix of object oriented programming and a more "imperative" style (by which me mean using functions, in a similar manner to C).
 
-* With IO functions, ramannoodle attempts to strike a balance between simplicity and flexibility. :mod:`ramannoodle.io.generic` provides file readers and writers for a variety of file formats. These generic routines are rather inflexible but are necessary for certain functionality. In most cases, users are strongly encouraged to use modules contained in the code-specific IO packages -- for example :mod:`ramannoodle.io.vasp.poscar` or :mod:`ramannoodle.io.vasp.outcar` -- to read the write files.
+* With IO functions, ramannoodle attempts to strike a balance between simplicity and flexibility. :mod:`ramannoodle.io.generic` provides file readers and writers for a variety of file formats. These generic functions are rather inflexible but are necessary for certain functionality. In most cases, users are strongly encouraged to use modules contained in the code-specific IO packages -- for example :mod:`ramannoodle.io.vasp.poscar` or :mod:`ramannoodle.io.vasp.outcar` -- to read the write files.

docs/source/generated/ramannoodle.dynamics.rst

@@ -1,11 +1,6 @@
 ramannoodle.dynamics package
 ============================
 
-.. automodule:: ramannoodle.dynamics
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Submodules
 ----------
 
@@ -24,3 +19,19 @@ ramannoodle.dynamics.phonon module
    :members:
    :undoc-members:
    :show-inheritance:
+
+ramannoodle.dynamics.trajectory module
+--------------------------------------
+
+.. automodule:: ramannoodle.dynamics.trajectory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.dynamics
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/generated/ramannoodle.io.rst

@@ -1,11 +1,6 @@
 ramannoodle.io package
 ======================
 
-.. automodule:: ramannoodle.io
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Subpackages
 -----------
 
@@ -32,3 +27,11 @@ ramannoodle.io.io\_utils module
    :members:
    :undoc-members:
    :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.io
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/generated/ramannoodle.io.vasp.rst

@@ -1,11 +1,6 @@
 ramannoodle.io.vasp package
 ===========================
 
-.. automodule:: ramannoodle.io.vasp
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Submodules
 ----------
 
@@ -24,3 +19,27 @@ ramannoodle.io.vasp.poscar module
    :members:
    :undoc-members:
    :show-inheritance:
+
+ramannoodle.io.vasp.vasprun module
+----------------------------------
+
+.. automodule:: ramannoodle.io.vasp.vasprun
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ramannoodle.io.vasp.xdatcar module
+----------------------------------
+
+.. automodule:: ramannoodle.io.vasp.xdatcar
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.io.vasp
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/generated/ramannoodle.polarizability.rst

@@ -1,11 +1,6 @@
 ramannoodle.polarizability package
 ==================================
 
-.. automodule:: ramannoodle.polarizability
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Submodules
 ----------
 
@@ -32,3 +27,11 @@ ramannoodle.polarizability.interpolation module
    :members:
    :undoc-members:
    :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.polarizability
+   :members:
+   :undoc-members:
+   :show-inheritance: