version 0.4.0

.github/dependabot.yml

@@ -9,6 +9,7 @@ updates:
     directory: "/"
     schedule:
       interval: weekly
+    target-branch: "dev"
     groups:
       python-packages:
         patterns:

.github/workflows/publish-to-test-pypi.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -42,7 +42,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4.1.7
+      uses: actions/download-artifact@v4.1.8
       with:
         name: python-package-distributions
         path: dist/
@@ -63,12 +63,12 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4.1.7
+      uses: actions/download-artifact@v4.1.8
       with:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
       with:
         inputs: >-
           ./dist/*.tar.gz

.github/workflows/python-package.yml

@@ -20,14 +20,18 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install uv
-        uv pip install ${{ matrix.uv-arg }} --system -r requirements.txt
+        uv pip install ${{ matrix.uv-arg }} --system -r deps/dev_requirements.txt
+        uv pip install ${{ matrix.uv-arg }} --system -r deps/requirements.txt
+        uv pip install ${{ matrix.uv-arg }} --system -r deps/torch_geometric_requirements.txt
+        uv pip install ${{ matrix.uv-arg }} --system -r deps/torch_requirements.txt
+        uv pip install ${{ matrix.uv-arg }} --system --no-index -r deps/torch_extra_requirements.txt
     - name: Analyzing the code with pylint
       if: ${{ matrix.os != 'windows-latest' }} # Windows throws strange linting errors
       run: |

.gitignore

@@ -265,7 +265,7 @@ $RECYCLE.BIN/
 
 # End of https://www.toptal.com/developers/gitignore/api/macos,linux,windows,python,visualstudiocode
 session
-test/Testing.ipynb
 test/data/temp
 test/data/temp.vasp
 docs/source/notebooks/*POSCAR
+test/Testing.ipynb

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 ci:
-    skip: [pylint,flake8]
+    skip: [pylint,flake8,mypy]
 exclude: EPS_OUTCAR
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
@@ -38,7 +38,7 @@ repos:
         args: [--strict]
         additional_dependencies:
           [
-            pytest,types-tabulate
+            pytest,types-tabulate,torch
           ]
         exclude: "conf.py"
 -   repo: https://github.com/pycqa/flake8

.readthedocs.yaml

@@ -8,7 +8,10 @@ build:
 python:
   install:
     - requirements: docs/requirements.txt
-    - requirements: requirements.txt
+    - requirements: deps/requirements.txt
+    - requirements: deps/torch_requirements.txt
+    - requirements: deps/torch_geometric_requirements.txt
+    - requirements: deps/torch_extra_requirements.txt
 
 sphinx:
   configuration: docs/source/conf.py

README.md

@@ -8,9 +8,9 @@
 
 ## 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 is designed from the ground up to be:
+Ramannoodle aims to be:
 
 1. **EFFICIENT**
 
@@ -24,18 +24,26 @@ Ramannoodle is designed from the ground up 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
-`
+```
+
+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:
+
+```
+$ pip install torch==2.4.1+cpu --index-url https://download.pytorch.org/whl/cpu
+$ pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.4.0+cpu.html
+$ pip install ramannoodle[torch]
+```
 
 ## Documentation
 
@@ -47,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)

cspell.json

@@ -7,14 +7,17 @@
     "dictionaries": [],
     "words": [
         "__repr__",
+        "allclose",
         "anharmonic",
         "ANSICOLORS",
         "argmax",
         "atominfo",
         "automodule",
         "AVOGADROS",
+        "Bučko",
         "Daltons",
         "defusedxml",
+        "dimenet",
         "docstrings",
         "dtype",
         "dynmat",
@@ -27,11 +30,15 @@
         "fftshift",
         "firstrow",
         "freq",
+        "GNNFF",
         "Grumet",
         "ifft",
         "Imaginarium",
         "initialpos",
         "interp",
+        "jacs",
+        "keepdim",
+        "layernorm",
         "LBYL",
         "lexsort",
         "linalg",
@@ -46,34 +53,46 @@
         "newaxis",
         "NIONS",
         "numpy",
+        "optim",
         "outcar",
         "outcars",
         "pathify",
         "phonopy",
+        "pmodel",
         "polarizabilities",
         "POSCAR",
         "POTCAR",
         "POTIM",
         "pylint",
+        "pymatgen",
         "pytest",
         "quickstart",
         "Raman",
         "ramannoodle",
+        "randn",
         "repr",
         "rint",
+        "Rupp",
         "savez",
+        "schnet",
+        "Softplus",
         "spglib",
+        "subbatch",
+        "subbatchs",
         "symprec",
         "tablefmt",
         "timestep",
         "timesteps",
         "toctree",
+        "tqdm",
         "undoc",
         "Unitless",
         "varray",
         "varrays",
+        "unsqueeze",
         "VASP",
         "vasprun",
+        "vecdot",
         "VRHFIN",
         "wavenumber",
         "wavenumbers",

deps/dev_requirements.txt

@@ -0,0 +1,5 @@
+flake8 == 7.1.0
+pre-commit == 3.7.1
+pylint == 3.3.1
+pytest == 8.3.1
+setuptools == 74.1.2

deps/requirements.txt

@@ -0,0 +1,12 @@
+# numpy, scipy recommendations: https://scientific-python.org/specs/spec-0000/
+
+defusedxml >= 0.6.0 # min working
+numpy >= 1.24.0;python_version=='3.10' # min recommended
+numpy >= 1.24.0;python_version=='3.11' # min recommended
+numpy >= 1.26.0;python_version=='3.12' # min working
+scipy >= 1.10.0;python_version=='3.10' # min recommended
+scipy >= 1.10.0;python_version=='3.11' # min recommended
+scipy >= 1.11.2;python_version=='3.12' # min working
+spglib >= 1.16.4 # min working
+tabulate >= 0.8.8 # min working
+tqdm >= 2.0 # min working

deps/torch_extra_requirements.txt

@@ -0,0 +1,3 @@
+-f https://data.pyg.org/whl/torch-2.4.0+cpu.html
+torch-scatter
+torch-sparse

deps/torch_geometric_requirements.txt

@@ -0,0 +1,16 @@
+aiohttp >= 3.8.0;python_version=='3.10' # min working
+aiohttp >= 3.8.3;python_version=='3.11' # min working
+aiohttp >= 3.9.0;python_version=='3.12' # min working
+dill >= 0.3.4 # min working
+frozenlist >= 1.2.0;python_version=='3.10' # min working
+frozenlist >= 1.3.3;python_version=='3.11' # min working
+frozenlist >= 1.4.1;python_version=='3.12' # min working
+fsspec>= 2021.4.0;python_version=='3.10' # min working
+jinja2 >= 3.0.2 # min working
+pyparsing >= 3.0.0 # min working
+scikit-learn >= 1.2.0;python_version=='3.10' # min working
+scikit-learn >= 1.2.0;python_version=='3.11' # min working
+scikit-learn >= 1.3.0;python_version=='3.12' and sys_platform=='darwin' # min working
+scikit-learn >= 1.3.0;python_version=='3.12' and sys_platform=='linux' # min working
+scikit-learn >= 1.4.0;python_version=='3.12' and sys_platform=='win32' # min working
+torch_geometric >= 2.3.0 # min working

deps/torch_requirements.txt

@@ -0,0 +1,4 @@
+--index-url https://download.pytorch.org/whl/cpu
+torch==2.4.1;sys_platform=='darwin'
+torch==2.4.1+cpu;sys_platform=='linux'
+torch==2.4.1+cpu;sys_platform=='win32'

docs/requirements.txt

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

docs/source/conf.py

@@ -16,7 +16,7 @@
 project = 'ramannoodle'
 copyright = "2023-present, Willis O'Leary"
 author = "Willis O'Leary"
-release = '0.3.0'
+release = '0.4.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -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']
@@ -55,6 +57,6 @@
     "dark_logo": "logo_dark.png",
     "sidebar_hide_name": True,
 }
-html_extra_path = ["docs/source/robots.txt"]
+html_extra_path = ["robots.txt"]
 
 sys.path.insert(0, os.path.abspath('../../'))

docs/source/generated/ramannoodle.dataset.rst

@@ -0,0 +1,18 @@
+ramannoodle.dataset package
+===========================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   ramannoodle.dataset.torch
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/generated/ramannoodle.dataset.torch.rst

@@ -0,0 +1,29 @@
+ramannoodle.dataset.torch package
+=================================
+
+Submodules
+----------
+
+ramannoodle.dataset.torch.dataset module
+----------------------------------------
+
+.. automodule:: ramannoodle.dataset.torch.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ramannoodle.dataset.torch.utils module
+--------------------------------------
+
+.. automodule:: ramannoodle.dataset.torch.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ramannoodle.dataset.torch
+   :members:
+   :undoc-members:
+   :show-inheritance: