furka 0.0.1a1__tar.gz

furka-0.0.1a1/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-typecheck:
+    name: Ruff & mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Check formatting and lint with Ruff
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+
+      - name: Type-check with mypy
+        run: uv run mypy src tests
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run pytest
+        run: uv run --python ${{ matrix.python-version }} pytest
+
+  build-check:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build distributions
+        run: uv build

furka-0.0.1a1/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          if [ "${TAG_VERSION}" != "${PKG_VERSION}" ]; then
+            echo "::error::Tag version (${TAG_VERSION}) does not match pyproject.toml version (${PKG_VERSION})"
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI via Trusted Publishing
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/furka
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: [build, publish-pypi]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PRERELEASE_FLAG=""
+          if [[ "${GITHUB_REF_NAME}" =~ (a|b|rc|dev)[0-9]+$ ]]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            ${PRERELEASE_FLAG}

furka-0.0.1a1/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Unit test / coverage / linter / type-checker caches
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# IDEs and OS artifacts
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

furka-0.0.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alain C. Vaucher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

furka-0.0.1a1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: furka
+Version: 0.0.1a1
+Summary: Composable transition-state (TS) and minimum-energy-path (MEP) algorithms for computational chemistry.
+Project-URL: Homepage, https://github.com/avaucher/furka
+Project-URL: Repository, https://github.com/avaucher/furka
+Project-URL: Issues, https://github.com/avaucher/furka/issues
+Author: Alain C. Vaucher
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chemistry,intrinsic-reaction-coordinate,minimum-energy-path,potential-energy-surface,saddle-point,transition-state
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: ase
+Requires-Dist: ase>=3.22; extra == 'ase'
+Provides-Extra: geometric
+Requires-Dist: geometric>=1.0; extra == 'geometric'
+Provides-Extra: sella
+Requires-Dist: sella>=2.3; extra == 'sella'
+Provides-Extra: viz
+Requires-Dist: plotly>=5.18; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# furka
+
+**`furka`** is a modular Python library for locating chemical transition states (first-order saddle points) and minimum energy paths (MEPs) on molecular potential energy surfaces.
+
+Named after the Swiss Alpine **Furka Pass** (a saddle connecting two valleys) and Latin *furca* (a two-pronged bracket), `furka` decouples double-ended path/bracket generation (Stage 1) from local saddle-point refinement (Stage 2) and post-TS MEP/IRC verification (Stage 3).
+
+> **Status:** Early alpha (`0.0.1a1`). Full release accompanying upcoming publication.
+
+## Installation
+
+```bash
+pip install furka
+```
+
+## Quick Example
+
+```python
+import numpy as np
+from furka import kabsch_rmsd
+
+coords_a = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.15], [0.0, 1.0, -0.4]])
+coords_b = coords_a + np.array([2.5, -1.0, 0.5])  # rigid translation
+
+rmsd = kabsch_rmsd(coords_a, coords_b)  # 0.0
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy src tests
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

furka-0.0.1a1/README.md

@@ -0,0 +1,38 @@
+# furka
+
+**`furka`** is a modular Python library for locating chemical transition states (first-order saddle points) and minimum energy paths (MEPs) on molecular potential energy surfaces.
+
+Named after the Swiss Alpine **Furka Pass** (a saddle connecting two valleys) and Latin *furca* (a two-pronged bracket), `furka` decouples double-ended path/bracket generation (Stage 1) from local saddle-point refinement (Stage 2) and post-TS MEP/IRC verification (Stage 3).
+
+> **Status:** Early alpha (`0.0.1a1`). Full release accompanying upcoming publication.
+
+## Installation
+
+```bash
+pip install furka
+```
+
+## Quick Example
+
+```python
+import numpy as np
+from furka import kabsch_rmsd
+
+coords_a = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.15], [0.0, 1.0, -0.4]])
+coords_b = coords_a + np.array([2.5, -1.0, 0.5])  # rigid translation
+
+rmsd = kabsch_rmsd(coords_a, coords_b)  # 0.0
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy src tests
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

furka-0.0.1a1/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "furka"
+version = "0.0.1a1"
+description = "Composable transition-state (TS) and minimum-energy-path (MEP) algorithms for computational chemistry."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+  { name = "Alain C. Vaucher" },
+]
+keywords = [
+  "chemistry",
+  "transition-state",
+  "minimum-energy-path",
+  "saddle-point",
+  "intrinsic-reaction-coordinate",
+  "potential-energy-surface",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Typing :: Typed",
+]
+dependencies = [
+  "numpy>=1.24",
+  "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+ase = ["ase>=3.22"]
+sella = ["sella>=2.3"]
+geometric = ["geometric>=1.0"]
+viz = ["plotly>=5.18"]
+
+[project.urls]
+Homepage = "https://github.com/avaucher/furka"
+Repository = "https://github.com/avaucher/furka"
+Issues = "https://github.com/avaucher/furka/issues"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.11",
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/furka"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+
+[tool.coverage.run]
+source = ["furka"]
+branch = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

furka-0.0.1a1/src/furka/__init__.py

@@ -0,0 +1,27 @@
+"""furka: Composable transition-state and minimum-energy-path algorithms."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__version__ = "0.0.1a1"
+__all__ = ["__version__", "kabsch_rmsd"]
+
+
+def kabsch_rmsd(coords_a: ArrayLike, coords_b: ArrayLike) -> float:
+    """Compute optimal rigid-body aligned RMSD (in Angstrom) between two (N, 3) geometries."""
+    a = np.asarray(coords_a, dtype=np.float64)
+    b = np.asarray(coords_b, dtype=np.float64)
+    if a.shape != b.shape or a.ndim != 2 or a.shape[1] != 3 or a.shape[0] == 0:
+        raise ValueError(
+            f"Expected matching non-empty (N, 3) coordinate arrays, got {a.shape} and {b.shape}."
+        )
+    a_centered = a - a.mean(axis=0)
+    b_centered = b - b.mean(axis=0)
+    cov = a_centered.T @ b_centered
+    u, _, vt = np.linalg.svd(cov)
+    d = 1.0 if float(np.linalg.det(u @ vt)) >= 0.0 else -1.0
+    rot = u @ np.diag([1.0, 1.0, d]) @ vt
+    diff = a_centered @ rot - b_centered
+    return float(np.sqrt(np.mean(np.sum(diff * diff, axis=1))))

furka-0.0.1a1/tests/test_rmsd.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from numpy.typing import NDArray
+
+from furka import __version__, kabsch_rmsd
+
+
+def test_version() -> None:
+    assert __version__ == "0.0.1a1"
+
+
+def test_kabsch_rmsd_identical_and_translated() -> None:
+    coords = np.array(
+        [
+            [0.000, 0.000, 0.117],
+            [0.000, 0.757, -0.469],
+            [0.000, -0.757, -0.469],
+        ]
+    )
+    assert kabsch_rmsd(coords, coords) == pytest.approx(0.0, abs=1e-12)
+    translated = coords + np.array([12.3, -4.5, 6.7])
+    assert kabsch_rmsd(coords, translated) == pytest.approx(0.0, abs=1e-12)
+
+
+def test_kabsch_rmsd_proper_rotation() -> None:
+    coords = np.array(
+        [
+            [0.0, 0.0, 0.0],
+            [1.4, 0.0, 0.0],
+            [0.0, 1.5, 0.0],
+            [0.0, 0.0, 1.6],
+        ]
+    )
+    theta = 0.73
+    c, s = np.cos(theta), np.sin(theta)
+    rot_z = np.array([[c, -s, 0.0], [s, c, 0.0], [0.0, 0.0, 1.0]])
+    rot_x = np.array([[1.0, 0.0, 0.0], [0.0, c, -s], [0.0, s, c]])
+    transformed = coords @ (rot_z @ rot_x) + np.array([-3.0, 1.2, 8.4])
+    assert kabsch_rmsd(coords, transformed) == pytest.approx(0.0, abs=1e-12)
+
+
+def test_kabsch_rmsd_chiral_reflection_not_collapsed() -> None:
+    chiral = np.array(
+        [
+            [0.0, 0.0, 0.0],
+            [1.5, 0.0, 0.0],
+            [0.0, 1.6, 0.0],
+            [0.0, 0.0, 1.7],
+        ]
+    )
+    mirror = chiral * np.array([1.0, 1.0, -1.0])
+    assert kabsch_rmsd(chiral, mirror) > 0.5
+
+
+def test_kabsch_rmsd_collinear_geometry() -> None:
+    hcn = np.array([[0.0, 0.0, -1.06], [0.0, 0.0, 0.0], [0.0, 0.0, 1.15]])
+    hcn_rot = np.array([[-1.06, 0.0, 0.0], [0.0, 0.0, 0.0], [1.15, 0.0, 0.0]])
+    assert kabsch_rmsd(hcn, hcn_rot) == pytest.approx(0.0, abs=1e-12)
+
+
+@pytest.mark.parametrize(
+    ("a", "b"),
+    [
+        (np.zeros((3, 3)), np.zeros((4, 3))),
+        (np.zeros((3, 2)), np.zeros((3, 2))),
+        (np.zeros((3,)), np.zeros((3,))),
+        (np.zeros((0, 3)), np.zeros((0, 3))),
+    ],
+)
+def test_kabsch_rmsd_invalid_shapes(a: NDArray[np.float64], b: NDArray[np.float64]) -> None:
+    with pytest.raises(ValueError, match="Expected matching non-empty"):
+        kabsch_rmsd(a, b)