q2mm 5.0.0a1__tar.gz

q2mm-5.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff check q2mm/ test/ scripts/
+      - run: python -m ruff format --check q2mm test scripts examples
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -v

q2mm-5.0.0a1/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: docs
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

q2mm-5.0.0a1/.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(python -c "import os; print(next(f[5:-7] for f in os.listdir('dist') if f.startswith('q2mm-') and f.endswith('.tar.gz')))")
+          echo "Tag version: $TAG"
+          echo "Package version: $PKG_VERSION"
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "ERROR: Tag v$TAG does not match package version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  github-release:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Determine if pre-release
+        id: prerelease
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          if echo "$TAG" | grep -qE '(a|b|rc|dev|alpha|beta)'; then
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+            echo "$TAG is a pre-release"
+          else
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+            echo "$TAG is a stable release"
+          fi
+
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ steps.prerelease.outputs.is_prerelease }}
+          files: dist/*
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: build
+
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/q2mm
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

q2mm-5.0.0a1/.gitignore

@@ -0,0 +1,60 @@
+# ── Q2MM runtime artifacts ──────────────────────────────────
+timer.dat
+root.log
+
+# ── Generated Psi4 logs (large, regenerated by generate_qm_data.py) ──
+examples/sn2-test/qm-reference/psi4-output*.dat
+
+# ── Python ──────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.manifest
+*.spec
+.installed.cfg
+MANIFEST
+
+# ── Virtual environments ───────────────────────────────────
+.env
+.venv
+env/
+venv/
+ENV/
+
+# ── Testing / coverage ────────────────────────────────────
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+.tox/
+.nox/
+.hypothesis/
+
+# ── Type checking ─────────────────────────────────────────
+.mypy_cache/
+.dmypy.json
+.pyre/
+
+# ── Editors / IDEs ────────────────────────────────────────
+.idea/
+*.swp
+*.swo
+*~
+
+# ── OS files ──────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# ── MkDocs ────────────────────────────────────────────────
+/site/
+
+# ── Jupyter ───────────────────────────────────────────────
+.ipynb_checkpoints/

q2mm-5.0.0a1/.vscode/launch.json

@@ -0,0 +1,53 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Run SN2 Pipeline",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/examples/sn2-test/run_tsff_pipeline.py",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        },
+        {
+            "name": "Run Tests",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["-v", "--tb=short"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        },
+        {
+            "name": "Run Tests (current file)",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["-v", "${file}"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        },
+        {
+            "name": "Generate Benchmarks",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/scripts/generate_benchmarks.py",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        },
+        {
+            "name": "Validate vs Upstream",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/scripts/validate_against_upstream.py",
+            "args": ["--mode", "both"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        }
+    ]
+}

q2mm-5.0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Eric C. Hansen
+
+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.

q2mm-5.0.0a1/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: q2mm
+Version: 5.0.0a1
+Summary: Quantum-guided molecular mechanics force field optimization
+Author: Eric Hansen
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ericchansen/q2mm
+Project-URL: Documentation, https://ericchansen.github.io/q2mm/
+Keywords: force-field,molecular-mechanics,optimization,transition-state,computational-chemistry,Q2MM,OpenMM
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: amber
+Requires-Dist: parmed; extra == "amber"
+Provides-Extra: openmm
+Requires-Dist: openmm; extra == "openmm"
+Provides-Extra: qcel
+Requires-Dist: qcelemental; extra == "qcel"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: qcelemental; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Provides-Extra: all
+Requires-Dist: openmm; extra == "all"
+Requires-Dist: parmed; extra == "all"
+Requires-Dist: qcelemental; extra == "all"
+Dynamic: license-file
+
+# Q2MM
+
+**Quantum-guided molecular mechanics force field optimization.**
+
+[![CI](https://github.com/ericchansen/q2mm/actions/workflows/ci.yml/badge.svg)](https://github.com/ericchansen/q2mm/actions/workflows/ci.yml)
+
+Q2MM optimizes molecular mechanics (MM) force field parameters by minimizing
+the difference between MM-calculated properties and quantum mechanics (QM)
+reference data. It is designed for building **transition state force fields
+(TSFFs)** that enable rapid virtual screening of enantioselective catalysts.
+
+**📖 [Documentation](https://ericchansen.github.io/q2mm/)**
+
+## Why Q2MM?
+
+- **Hessian-informed initialization** — the Seminario method extracts bond and
+  angle force constants directly from QM Hessians, providing excellent starting
+  parameters before optimization begins.
+- **Open-source backends** — first-class support for [OpenMM](https://openmm.org/)
+  and [Psi4](https://psicode.org/) alongside commercial packages (Gaussian,
+  Schrödinger, Tinker).
+- **Clean, modular architecture** — format-agnostic data models (`ForceField`,
+  `Q2MMMolecule`) decouple algorithms from file formats.
+- **Modern optimization** — powered by `scipy.optimize` with L-BFGS-B,
+  Nelder-Mead, trust-region, and Levenberg-Marquardt methods.
+- **Transition state support** — negative force constants, torsion parameters,
+  and proper eigenvalue handling for saddle-point geometries.
+
+## Quick Start
+
+```bash
+pip install -e .
+```
+
+```python
+import numpy as np
+from q2mm.models.molecule import Q2MMMolecule
+from q2mm.models.seminario import estimate_force_constants
+
+# Load QM data (coordinates + Hessian from your QM package)
+mol = Q2MMMolecule.from_xyz("ts-optimized.xyz")
+mol.hessian = np.load("ts-hessian.npy")  # Hartree/Bohr²
+
+# Estimate force constants from the QM Hessian (Seminario method)
+ff = estimate_force_constants(mol, au_hessian=True)
+
+print(f"Bonds: {len(ff.bonds)}, Angles: {len(ff.angles)}")
+for b in ff.bonds:
+    print(f"  {b.elements}: k={b.force_constant:.3f} mdyn/Å")
+```
+
+See the [Tutorial](https://ericchansen.github.io/q2mm/tutorial/) for a
+complete end-to-end workflow.
+
+## Supported Backends
+
+| Backend | Type | License |
+|---------|------|---------|
+| **OpenMM** | MM | MIT |
+| **Psi4** | QM | BSD-3 |
+| **Tinker** | MM | Free (academic) |
+| **Gaussian** | QM | Commercial |
+| **Schrödinger** | QM/MM | Commercial |
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).
+

q2mm-5.0.0a1/README.md

@@ -0,0 +1,68 @@
+# Q2MM
+
+**Quantum-guided molecular mechanics force field optimization.**
+
+[![CI](https://github.com/ericchansen/q2mm/actions/workflows/ci.yml/badge.svg)](https://github.com/ericchansen/q2mm/actions/workflows/ci.yml)
+
+Q2MM optimizes molecular mechanics (MM) force field parameters by minimizing
+the difference between MM-calculated properties and quantum mechanics (QM)
+reference data. It is designed for building **transition state force fields
+(TSFFs)** that enable rapid virtual screening of enantioselective catalysts.
+
+**📖 [Documentation](https://ericchansen.github.io/q2mm/)**
+
+## Why Q2MM?
+
+- **Hessian-informed initialization** — the Seminario method extracts bond and
+  angle force constants directly from QM Hessians, providing excellent starting
+  parameters before optimization begins.
+- **Open-source backends** — first-class support for [OpenMM](https://openmm.org/)
+  and [Psi4](https://psicode.org/) alongside commercial packages (Gaussian,
+  Schrödinger, Tinker).
+- **Clean, modular architecture** — format-agnostic data models (`ForceField`,
+  `Q2MMMolecule`) decouple algorithms from file formats.
+- **Modern optimization** — powered by `scipy.optimize` with L-BFGS-B,
+  Nelder-Mead, trust-region, and Levenberg-Marquardt methods.
+- **Transition state support** — negative force constants, torsion parameters,
+  and proper eigenvalue handling for saddle-point geometries.
+
+## Quick Start
+
+```bash
+pip install -e .
+```
+
+```python
+import numpy as np
+from q2mm.models.molecule import Q2MMMolecule
+from q2mm.models.seminario import estimate_force_constants
+
+# Load QM data (coordinates + Hessian from your QM package)
+mol = Q2MMMolecule.from_xyz("ts-optimized.xyz")
+mol.hessian = np.load("ts-hessian.npy")  # Hartree/Bohr²
+
+# Estimate force constants from the QM Hessian (Seminario method)
+ff = estimate_force_constants(mol, au_hessian=True)
+
+print(f"Bonds: {len(ff.bonds)}, Angles: {len(ff.angles)}")
+for b in ff.bonds:
+    print(f"  {b.elements}: k={b.force_constant:.3f} mdyn/Å")
+```
+
+See the [Tutorial](https://ericchansen.github.io/q2mm/tutorial/) for a
+complete end-to-end workflow.
+
+## Supported Backends
+
+| Backend | Type | License |
+|---------|------|---------|
+| **OpenMM** | MM | MIT |
+| **Psi4** | QM | BSD-3 |
+| **Tinker** | MM | Free (academic) |
+| **Gaussian** | QM | Commercial |
+| **Schrödinger** | QM/MM | Commercial |
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).
+