rinse-descriptor 0.1.0__tar.gz

rinse_descriptor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Python – lint, type-check, test
+  # --------------------------------------------------------------------------
+  python:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install project (dev dependencies)
+        run: uv sync --group dev
+
+      - name: ruff lint
+        run: uv run ruff check python/ tests/
+
+      - name: ruff format check
+        run: uv run ruff format --check python/ tests/
+
+      - name: mypy
+        run: uv run mypy python/rinse_descriptor/
+
+      - name: pytest
+        run: uv run pytest tests/ -v --tb=short
+
+  # --------------------------------------------------------------------------
+  # Build sdist + wheel (on push to main)
+  # --------------------------------------------------------------------------
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [python]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

rinse_descriptor-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: "Publish"
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v0.1.0
+      - v*
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install Python 3.13
+        run: uv python install 3.13
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

rinse_descriptor-0.1.0/.gitignore

@@ -0,0 +1,80 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.pytest_cache/
+cache/
+.nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Marimo Notebook
+__marimo__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# sqlite database
+*.db
+*.db-journal
+
+crystal_pickles/
+umap_hdbscan_results.csv

rinse_descriptor-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-fix
+        name: ruff check --fix (staged files)
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        files: ^(python/|tests/)
+        stages: [pre-commit]
+      - id: ruff-format
+        name: ruff format (staged files)
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        files: ^(python/|tests/)
+        stages: [pre-commit]
+      - id: ruff-check-all
+        name: ruff check (full)
+        entry: uv run ruff check python/ tests/
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+      - id: mypy
+        name: mypy (package)
+        entry: uv run mypy python/rinse_descriptor/
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+      - id: pytest
+        name: pytest (suite)
+        entry: sh -c 'PYTHONPATH=python uv run pytest tests/ -v --tb=short'
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

rinse_descriptor-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

rinse_descriptor-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: rinse-descriptor
+Version: 0.1.0
+Summary: Reciprocal-space INvariant Spectral Embedding (RINSE) descriptors for crystalline materials
+License: MIT
+Keywords: crystallography,descriptors,machine learning,materials science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: ase>=3.23.0
+Requires-Dist: gemmi>=0.6.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: scipy>=1.12
+Description-Content-Type: text/markdown
+
+# RINSE – Reciprocal-space INvariant Spectral Embedding
+
+RINSE computes rotationally invariant descriptors of crystalline materials
+by projecting the intensity-weighted reciprocal lattice onto a combined radial
+and angular basis (analogous to SOAP, but working entirely in reciprocal space).
+
+## Descriptor formulation
+
+For a crystal, all reflections $\mathbf{G}_{\mathrm{hkl}}$ within a resolution cutoff
+(default $\sin{\theta}/\lambda \leq 0.6 Å^{-1}$ , i.e. $\mathbf{G} \leq 0.6 Å^{-1}$) are enumerated.
+Each reflection is assigned an intensity $\mathrm{I}(\mathbf{G}) = \lvert\mathrm{F}(\mathbf{G})\rvert^{2}$ from the
+structure factor calculated via Gemmi (direct summation, IT92 X-ray form
+factors by default).
+
+The expansion coefficients are:
+
+$$
+A_{nlm} = Σ_\mathbf{G}  I(\mathbf{G}) · R_n(\mathbf{G}) · Y_l^m(\hat{\mathbf{G}})
+$$
+
+and the rotationally invariant power spectrum is:
+
+$$
+p_{nl} = Σ_m \lvert A_{nlm}\rvert^{2}
+$$
+
+Because the intensity field is centrosymmetric if anomalous dispersion is not considered, only even *l*
+contributes. Default parameters give a **8 × 16 = 128-element** descriptor:
+
+| Axis | Values | Count |
+|------|--------|-------|
+| Radial (*n*) | 0, 1, …, 7 | 8 |
+| Angular (*l*) | 0, 2, 4, …, 30 (even only) | 16 |
+
+## Installation
+
+### From source (requires `uv`)
+
+```bash
+# Clone
+git clone https://github.com/DuMOCC-Group/rinse-descriptor.git
+cd rinse-descriptor
+
+# Install uv (if not already available)
+curl -Ls https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies
+uv sync
+```
+
+### From PyPI (once published)
+
+```bash
+pip install rinse-descriptor
+# or
+uv add rinse-descriptor
+```
+
+## Quick start
+
+### From an ASE Atoms object
+
+```python
+from ase.build import bulk
+from rinse_descriptor import descriptor, descriptor_many, RinseParams
+
+# Single structure → (8, 16) matrix
+atoms = bulk("NaCl", "rocksalt", a=5.64)
+x = descriptor(atoms)
+print(x.shape)  # (8, 16)
+
+# Flatten to 1-D feature vector
+x_vec = descriptor(atoms, flatten=True)
+print(x_vec.shape)  # (128,)
+
+# Batch of structures → (N, 8, 16)
+structures = [bulk("Si", "diamond", a=5.43), bulk("Cu", "fcc", a=3.62)]
+X = descriptor_many(structures)
+print(X.shape)  # (2, 8, 16)
+```
+
+### From a CIF file
+
+```python
+from rinse_descriptor import descriptor
+
+x = descriptor("mystructure.cif")
+print(x.shape)  # (8, 16)
+```
+
+### Custom parameters
+
+```python
+from rinse_descriptor import RinseParams, descriptor
+
+params = RinseParams(
+    n_max=8,                       # radial basis order (n = 0 … 7)
+    l_max=16,                       # angular levels (gives l = 0,2,...,30)
+    sin_theta_over_lambda_max=0.6,  # resolution cutoff in Å⁻¹
+    radial_basis="chebyshev",       # or "bessel" / "smooth_shells_cw" / "smooth_shells_nl"
+)
+x = descriptor(atoms, params=params)
+```
+
+### Form factors and structure factor type
+
+```python
+from rinse_descriptor import descriptor
+
+# Electron scattering factors, intensities
+x = descriptor(atoms, form_factor_type="electron", structure_factor_type="F2")
+
+# Neutron scattering lengths, amplitudes
+x = descriptor(atoms, form_factor_type="neutron", structure_factor_type="F")
+```
+
+Available `form_factor_type` values: `"xray"` (default), `"electron"`, `"neutron"`, `"unity"`.
+
+Available `structure_factor_type` values: `"F2"` (default), `"F"`.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest tests/ -v
+
+# Run benchmarks
+uv run pytest benchmarks/ --benchmark-only -v
+
+# Lint / format
+uv run ruff check python/ tests/
+uv run ruff format python/ tests/
+uv run mypy python/rinse_descriptor/
+```
+
+### Pre-commit hooks (recommended)
+
+This repository includes a `.pre-commit-config.yaml` that runs:
+
+- On commit: `ruff check --fix` and `ruff format` for staged Python files.
+- On push: full `ruff check`, `mypy`, and `pytest`.
+
+Install and run once:
+
+```bash
+uv sync --group dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+uv run pre-commit run --all-files
+```
+
+## Project structure
+
+```
+rinse-descriptor/
+├── python/rinse_descriptor/  # Python package
+│   ├── __init__.py        # Public API: descriptor(), descriptor_many()
+│   ├── _crystal.py        # Crystal dataclass (ASE/Gemmi-independent)
+│   ├── _structure_factors.py  # Gemmi structure factor calculation
+│   ├── _radial_basis.py   # Chebyshev / Bessel / smooth-shell radial bases
+│   └── _descriptor.py     # Power spectrum computation
+├── tests/                 # pytest test suite
+├── benchmarks/            # pytest-benchmark suite
+├── .github/workflows/ci.yml
+└── pyproject.toml
+```
+
+## Future: `rinse_descriptor.diffraction` submodule
+
+The package is designed to support a future `rinse_descriptor.diffraction` submodule that will provide:
+
+- Indexed diffraction patterns (hkl, d-spacing, intensity)
+- Unindexed powder diffraction patterns (2θ or *d*-spacing profiles)
+- Reciprocal-space descriptors beyond the power spectrum (e.g. bispectrum)
+
+The `Crystal`, `ReflectionList`, and `RinseParams` types are designed to be
+shared between the core descriptor and the diffraction submodule.
+
+## License
+
+MIT

rinse_descriptor-0.1.0/README.md

@@ -0,0 +1,180 @@
+# RINSE – Reciprocal-space INvariant Spectral Embedding
+
+RINSE computes rotationally invariant descriptors of crystalline materials
+by projecting the intensity-weighted reciprocal lattice onto a combined radial
+and angular basis (analogous to SOAP, but working entirely in reciprocal space).
+
+## Descriptor formulation
+
+For a crystal, all reflections $\mathbf{G}_{\mathrm{hkl}}$ within a resolution cutoff
+(default $\sin{\theta}/\lambda \leq 0.6 Å^{-1}$ , i.e. $\mathbf{G} \leq 0.6 Å^{-1}$) are enumerated.
+Each reflection is assigned an intensity $\mathrm{I}(\mathbf{G}) = \lvert\mathrm{F}(\mathbf{G})\rvert^{2}$ from the
+structure factor calculated via Gemmi (direct summation, IT92 X-ray form
+factors by default).
+
+The expansion coefficients are:
+
+$$
+A_{nlm} = Σ_\mathbf{G}  I(\mathbf{G}) · R_n(\mathbf{G}) · Y_l^m(\hat{\mathbf{G}})
+$$
+
+and the rotationally invariant power spectrum is:
+
+$$
+p_{nl} = Σ_m \lvert A_{nlm}\rvert^{2}
+$$
+
+Because the intensity field is centrosymmetric if anomalous dispersion is not considered, only even *l*
+contributes. Default parameters give a **8 × 16 = 128-element** descriptor:
+
+| Axis | Values | Count |
+|------|--------|-------|
+| Radial (*n*) | 0, 1, …, 7 | 8 |
+| Angular (*l*) | 0, 2, 4, …, 30 (even only) | 16 |
+
+## Installation
+
+### From source (requires `uv`)
+
+```bash
+# Clone
+git clone https://github.com/DuMOCC-Group/rinse-descriptor.git
+cd rinse-descriptor
+
+# Install uv (if not already available)
+curl -Ls https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies
+uv sync
+```
+
+### From PyPI (once published)
+
+```bash
+pip install rinse-descriptor
+# or
+uv add rinse-descriptor
+```
+
+## Quick start
+
+### From an ASE Atoms object
+
+```python
+from ase.build import bulk
+from rinse_descriptor import descriptor, descriptor_many, RinseParams
+
+# Single structure → (8, 16) matrix
+atoms = bulk("NaCl", "rocksalt", a=5.64)
+x = descriptor(atoms)
+print(x.shape)  # (8, 16)
+
+# Flatten to 1-D feature vector
+x_vec = descriptor(atoms, flatten=True)
+print(x_vec.shape)  # (128,)
+
+# Batch of structures → (N, 8, 16)
+structures = [bulk("Si", "diamond", a=5.43), bulk("Cu", "fcc", a=3.62)]
+X = descriptor_many(structures)
+print(X.shape)  # (2, 8, 16)
+```
+
+### From a CIF file
+
+```python
+from rinse_descriptor import descriptor
+
+x = descriptor("mystructure.cif")
+print(x.shape)  # (8, 16)
+```
+
+### Custom parameters
+
+```python
+from rinse_descriptor import RinseParams, descriptor
+
+params = RinseParams(
+    n_max=8,                       # radial basis order (n = 0 … 7)
+    l_max=16,                       # angular levels (gives l = 0,2,...,30)
+    sin_theta_over_lambda_max=0.6,  # resolution cutoff in Å⁻¹
+    radial_basis="chebyshev",       # or "bessel" / "smooth_shells_cw" / "smooth_shells_nl"
+)
+x = descriptor(atoms, params=params)
+```
+
+### Form factors and structure factor type
+
+```python
+from rinse_descriptor import descriptor
+
+# Electron scattering factors, intensities
+x = descriptor(atoms, form_factor_type="electron", structure_factor_type="F2")
+
+# Neutron scattering lengths, amplitudes
+x = descriptor(atoms, form_factor_type="neutron", structure_factor_type="F")
+```
+
+Available `form_factor_type` values: `"xray"` (default), `"electron"`, `"neutron"`, `"unity"`.
+
+Available `structure_factor_type` values: `"F2"` (default), `"F"`.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest tests/ -v
+
+# Run benchmarks
+uv run pytest benchmarks/ --benchmark-only -v
+
+# Lint / format
+uv run ruff check python/ tests/
+uv run ruff format python/ tests/
+uv run mypy python/rinse_descriptor/
+```
+
+### Pre-commit hooks (recommended)
+
+This repository includes a `.pre-commit-config.yaml` that runs:
+
+- On commit: `ruff check --fix` and `ruff format` for staged Python files.
+- On push: full `ruff check`, `mypy`, and `pytest`.
+
+Install and run once:
+
+```bash
+uv sync --group dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+uv run pre-commit run --all-files
+```
+
+## Project structure
+
+```
+rinse-descriptor/
+├── python/rinse_descriptor/  # Python package
+│   ├── __init__.py        # Public API: descriptor(), descriptor_many()
+│   ├── _crystal.py        # Crystal dataclass (ASE/Gemmi-independent)
+│   ├── _structure_factors.py  # Gemmi structure factor calculation
+│   ├── _radial_basis.py   # Chebyshev / Bessel / smooth-shell radial bases
+│   └── _descriptor.py     # Power spectrum computation
+├── tests/                 # pytest test suite
+├── benchmarks/            # pytest-benchmark suite
+├── .github/workflows/ci.yml
+└── pyproject.toml
+```
+
+## Future: `rinse_descriptor.diffraction` submodule
+
+The package is designed to support a future `rinse_descriptor.diffraction` submodule that will provide:
+
+- Indexed diffraction patterns (hkl, d-spacing, intensity)
+- Unindexed powder diffraction patterns (2θ or *d*-spacing profiles)
+- Reciprocal-space descriptors beyond the power spectrum (e.g. bispectrum)
+
+The `Crystal`, `ReflectionList`, and `RinseParams` types are designed to be
+shared between the core descriptor and the diffraction submodule.
+
+## License
+
+MIT

rinse_descriptor-0.1.0/benchmarks/bench_descriptor.py

@@ -0,0 +1,40 @@
+"""Benchmarks for the RINSE descriptor (pytest-benchmark)."""
+
+from __future__ import annotations
+
+import pytest
+from ase.build import bulk, make_supercell
+from rinse_descriptor import RinseParams, descriptor
+
+
+@pytest.fixture(scope="module")
+def nacl_unit():
+    return bulk("NaCl", "rocksalt", a=5.6402)
+
+
+@pytest.fixture(scope="module")
+def nacl_supercell():
+    atoms = bulk("NaCl", "rocksalt", a=5.6402)
+    return make_supercell(atoms, [[2, 0, 0], [0, 2, 0], [0, 0, 2]])
+
+
+@pytest.fixture(scope="module")
+def params_default():
+    return RinseParams()
+
+
+@pytest.fixture(scope="module")
+def params_small():
+    return RinseParams(n_max=8, l_max=8, sin_theta_over_lambda_max=1.0)
+
+
+def test_benchmark_nacl_unit(benchmark, nacl_unit, params_default):
+    benchmark(descriptor, nacl_unit, params=params_default)
+
+
+def test_benchmark_nacl_supercell(benchmark, nacl_supercell, params_default):
+    benchmark(descriptor, nacl_supercell, params=params_default)
+
+
+def test_benchmark_small_params(benchmark, nacl_unit, params_small):
+    benchmark(descriptor, nacl_unit, params=params_small)