mlmm-toolkit 0.2.2.dev0__tar.gz

mlmm_toolkit-0.2.2.dev0/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install -r docs/requirements_docs.txt
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

mlmm_toolkit-0.2.2.dev0/.github/workflows/docs_quality.yml

@@ -0,0 +1,42 @@
+name: Docs Quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  reference-and-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install minimal dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e . --no-deps
+          pip install click pyyaml numpy biopython scipy ase \
+            autograd dask distributed h5py fabric jinja2 joblib \
+            matplotlib natsort psutil rmsd sympy scikit-learn \
+            pandas tabulate plotly kaleido ParmEd
+
+      - name: Run docs quality suite
+        timeout-minutes: 20
+        env:
+          DOCS_DUMP_CASE_TIMEOUT_SEC: "180"
+        run: |
+          set -o pipefail
+          python scripts/run_docs_quality.py --skip-dump | tee docs_quality_timing.log
+
+      - name: Upload docs quality timing log
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs_quality_timing_log
+          path: docs_quality_timing.log

mlmm_toolkit-0.2.2.dev0/.github/workflows/pytest.yml

@@ -0,0 +1,43 @@
+name: Pytest
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install mlmm with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e . --no-deps
+          pip install click pyyaml numpy biopython scipy ase \
+            autograd dask distributed h5py fabric jinja2 joblib \
+            matplotlib natsort psutil rmsd sympy scikit-learn \
+            pandas tabulate plotly kaleido ParmEd \
+            pytest pytest-cov pytest-timeout
+        timeout-minutes: 15
+
+      - name: Run pytest
+        run: |
+          pytest tests/ -v --tb=short -x --timeout=120 --cov=mlmm --cov-report=term-missing --cov-fail-under=20
+        timeout-minutes: 10
+
+      - name: Run hessian_ff tests
+        run: |
+          pytest hessian_ff/tests/ -v --tb=short -x --timeout=120 --cov=hessian_ff --cov-report=term-missing --cov-fail-under=50
+        timeout-minutes: 10

mlmm_toolkit-0.2.2.dev0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build twine
+
+      - name: Build package
+        run: |
+          rm -rf dist
+          python -m build
+
+      - name: Verify distribution
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

mlmm_toolkit-0.2.2.dev0/.github/workflows/smoke_test.yml

@@ -0,0 +1,125 @@
+name: Smoke Test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  cli-smoke:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install mlmm (CPU-only, UMA backend)
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e . --no-deps
+          pip install click pyyaml numpy biopython scipy ase \
+            autograd dask distributed h5py fabric jinja2 joblib \
+            matplotlib natsort psutil rmsd sympy scikit-learn \
+            pandas tabulate plotly kaleido ParmEd
+        timeout-minutes: 15
+
+      - name: CLI version and help
+        run: |
+          set -e
+          mlmm --version
+          for cmd in all extract define-layer mm-parm opt tsopt freq irc dft scan scan2d scan3d path-opt path-search trj2fig add-elem-info oniom-export oniom-import fix-altloc energy-diagram; do
+            echo "--- mlmm $cmd --help ---"
+            mlmm "$cmd" --help
+          done
+
+      - name: Progressive help (--help-advanced)
+        run: |
+          set -e
+          for cmd in opt tsopt freq scan dft extract path-search path-opt irc all; do
+            echo "--- mlmm $cmd --help-advanced ---"
+            mlmm "$cmd" --help-advanced
+          done
+
+      - name: Backend import checks
+        run: |
+          python -c "
+          from mlmm.mlmm_calc import _MLBackend, _UMABackend
+          print('UMA backend class: OK')
+          from mlmm.mlmm_calc import _ASEMLBackend
+          print('ASE backend base: OK')
+          from mlmm.mlmm_calc import _create_ml_backend
+          print('Factory function: OK')
+          from mlmm.defaults import MLMM_CALC_KW
+          assert 'backend' in MLMM_CALC_KW
+          assert MLMM_CALC_KW['backend'] == 'uma'
+          assert 'embedcharge' in MLMM_CALC_KW
+          print('Defaults: OK')
+          "
+
+      - name: Backend lazy import guards
+        run: |
+          python -c "
+          # Verify non-UMA backends raise ImportError cleanly
+          import torch
+          from mlmm.mlmm_calc import _OrbBackend, _MACEBackend, _AIMNet2Backend
+          for cls, name in [(_OrbBackend, 'ORB'), (_MACEBackend, 'MACE'), (_AIMNet2Backend, 'AIMNet2')]:
+              try:
+                  cls(ml_device=torch.device('cpu'))
+                  print(f'{name}: available (installed)')
+              except ImportError as e:
+                  print(f'{name}: ImportError raised correctly: {e}')
+              except Exception as e:
+                  print(f'{name}: unexpected error: {e}')
+                  raise
+          "
+
+      - name: Invalid backend rejection
+        run: |
+          # Verify --backend with invalid value is rejected by Click
+          ! mlmm opt --help 2>&1 | grep -q "INTERNAL ERROR" || true
+          # This should fail with a Click error, not a traceback
+          ! mlmm opt -i /dev/null --parm /dev/null -q 0 --backend invalid_value 2>&1 && echo "Invalid backend correctly rejected"
+
+  import-optional:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install mlmm (minimal, no CUDA)
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e . --no-deps
+          pip install click pyyaml numpy biopython scipy ase \
+            autograd dask distributed h5py fabric jinja2 joblib \
+            matplotlib natsort psutil rmsd sympy scikit-learn \
+            pandas tabulate plotly kaleido ParmEd
+        timeout-minutes: 15
+
+      - name: Verify optional deps don't break import
+        run: |
+          python -c "
+          # Core import should succeed even without optional backends
+          import mlmm
+          from mlmm import mlmm_calc
+          from mlmm import defaults
+          print('Core imports: OK')
+
+          # CLI entry point should be loadable
+          from mlmm.cli import cli
+          print('CLI entry point: OK')
+
+          "

mlmm_toolkit-0.2.2.dev0/.gitignore

@@ -0,0 +1,55 @@
+.history/
+
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+venv/
+env/
+env.bak/
+env1/
+env2/
+.env
+
+.vscode/
+*.code-workspace
+
+build/
+dist/
+*.egg-info/
+*.egg
+
+test-reports/
+.coverage
+.pytest_cache/
+
+# Smoke test outputs
+tests/smoke/test[0-9]*/
+tests/smoke/test*.out
+tests/smoke/test_*/
+tests/smoke/*_smoke.pdb
+tests/smoke/*_smoke_refactor.pdb
+tests/smoke/test_*.png
+
+# Sphinx documentation
+docs/_build/
+docs/_static/*.css.map
+docs/_static/*.js.map
+docs/_autosummary/
+docs/.myst_cache/
+docs/.ipynb_checkpoints/
+
+*.bak
+*.swp
+*.tmp
+*.tmp.*
+*~
+
+PLAN.md
+
+# hessian_ff build artifacts
+hessian_ff/native/.build_*/
+
+# setuptools-scm generated version file
+mlmm_toolkit/_version.py

mlmm_toolkit-0.2.2.dev0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to **mlmm-toolkit** will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.2.1] — 2026-03-18
+
+### Added
+- GitHub Pages deployment and PyPI release workflows.
+- Bidirectional scan (4-tuple) documentation (EN/JA).
+
+### Fixed
+- Regenerated CLI reference docs to match current `--help` output.
+- Documentation accuracy: defaults, YAML examples, EN/JA alignment.
+- Generalized UMA-specific wording to MLIP where applicable.
+- Improved hessian_ff JIT build error message.
+
+## [0.2.0] — 2026-03-16
+
+**Complete rewrite from `mlmm` (v0.1.1) to `mlmm-toolkit` (v0.2.0).**
+This release replaces the previous pysisyphus-wrapper architecture with a unified Click-based CLI toolkit. The package name, CLI interface, dependency stack, and internal architecture have all changed.
+
+### Breaking Changes
+
+- **Package name**: `mlmm-toolkit` on PyPI. Install with `pip install mlmm-toolkit`.
+- **CLI completely redesigned**: The old entry points (`mlmm`, `def_ml_region`, `bond_scan`, `ts_search`, `energy_summary`, `trj2fig`, `add_elem_info`, `get_freeze_indices`, `xyz_geom2pdb`) are replaced by a single `mlmm <subcommand>` interface with 21 subcommands.
+- **OpenMM removed**: MM calculations now use `hessian_ff`, a bundled C++ native extension for Amber force fields. OpenMM and OpenMM-CUDA-12 are no longer dependencies.
+- **RDKit removed**: No longer required.
+- **pysisyphus bundled**: No longer installed from a separate git repository; a modified fork is included in the package.
+- **fairchem-core from PyPI**: No longer installed from a custom git fork.
+- **numpy constraint relaxed**: `numpy<2.0` → `numpy>=1.24` (NumPy 2.x compatible).
+- **Configuration**: Inline kwargs replaced by a centralized `defaults.py` as the single source of truth for all default values.
+
+### Added — CLI & Workflow
+
+- **`mlmm all`**: End-to-end workflow command. Given PDB files (R → P), automatically extracts active-site pockets, generates MM parameters, assigns ONIOM layers, runs MEP search, and optionally performs TS optimization, IRC, vibrational analysis, and single-point DFT — all in one invocation.
+- **`mlmm opt`**: Single-structure geometry optimization with LBFGS (grad mode) or RFO (hess mode) with microiteration support.
+- **`mlmm scan` / `scan2d` / `scan3d`**: 1D, 2D, and 3D constrained distance scans along user-specified atom pairs.
+- **`mlmm path-search`**: Recursive minimum-energy path search with GSM (Growing String Method) and DMF (Direct Max Flux).
+- **`mlmm path-opt`**: Single-pass MEP optimization (GSM or DMF).
+- **`mlmm tsopt`**: Transition-state optimization (dimer method with partial Hessian, or RS-I-RFO with full Hessian).
+- **`mlmm irc`**: Intrinsic reaction coordinate calculation from a TS geometry. Outputs `forward_last.pdb` and `backward_last.pdb` endpoint structures.
+- **`mlmm freq`**: Vibrational analysis and thermochemistry (partial or full Hessian).
+- **`mlmm dft`**: GPU-accelerated single-point DFT via PySCF / gpu4pyscf (`pip install "mlmm-toolkit[dft]"`).
+- **`mlmm extract`**: Active-site pocket extraction from full protein-ligand PDB structures.
+- **`mlmm mm-parm`**: Automatic Amber parm7/rst7 generation via AmberTools (tleap + GAFF2/AM1-BCC).
+- **`mlmm define-layer`**: Assign 3-layer ML/MM partitioning via B-factor encoding (ML=0, MovableMM=10, FrozenMM=20).
+- **`mlmm oniom-export` / `oniom-import`**: Gaussian/ORCA ONIOM input/output interoperability.
+- **`mlmm add-elem-info`**: Fix missing or incorrect PDB element columns.
+- **`mlmm fix-altloc`**: Resolve alternate location indicators in PDB files.
+- **`mlmm energy-diagram`**: Plot energy profiles with Plotly (interactive HTML + static PNG).
+- **`mlmm trj2fig`**: Trajectory visualization (PNG snapshots from XYZ trajectories).
+
+### Added — Core Features
+
+- **Multi-backend MLIP support**: UMA (default), ORB, MACE, AIMNet2 — selectable via `-b/--backend` on all subcommands.
+- **ONIOM-like ML/MM decomposition**: `E = E_MM_real + E_ML_model − E_MM_model` with link-atom Jacobian transformation.
+- **hessian_ff**: Bundled C++ native extension for analytical Amber force field energies, forces, and Hessians (replaces OpenMM).
+- **Microiteration scheme**: Efficient optimization of large ML/MM systems (~10,000 atoms) by separating ML and MM degrees of freedom.
+- **xTB embed-charge correction**: Optional point-charge embedding for the ML region (`--embedcharge`).
+- **Partial Hessian approach**: Compute Hessians only for the ML region + boundary atoms, enabling TS optimization and frequency analysis on large systems.
+- **Automatic versioning**: setuptools-scm replaces hard-coded `__version__`.
+- **Progressive help**: `--help` shows primary options; `--help-advanced` shows the full option set.
+- **DefaultGroup**: Lazy-loading Click subcommand architecture with automatic boolean normalization (`--flag/--no-flag` and `--flag True/False` both supported).
+
+### Added — Dependencies & Extras
+
+- **Optional backends**: `pip install "mlmm-toolkit[orb]"`, `"mlmm-toolkit[mace]"`, `"mlmm-toolkit[aimnet2]"`.
+- **Optional DFT**: `pip install "mlmm-toolkit[dft]"` for PySCF + gpu4pyscf-cuda12x + CuPy.
+- **Optional PDBFixer**: `pip install "mlmm-toolkit[pdbfixer]"` for hydrogen addition.
+- **New core dependencies**: `click`, `torch_geometric`, `torch_scatter`, `pyparsing`, `tabulate`.
+- **Bundled packages**: `pysisyphus` (modified fork), `thermoanalysis`, `hessian_ff`.
+
+### Added — Documentation & Testing
+
+- Bilingual documentation (English + Japanese) under `docs/` and `docs/ja/`.
+- Per-subcommand reference docs with CLI tables and YAML configuration examples.
+- `CONTRIBUTING.md` with contributor guidelines.
+- GitHub Actions CI: `pytest.yml`, `smoke_test.yml`, `docs_quality.yml`.
+- 198 unit tests with `pytest --timeout=120`.
+- Smoke test suite: 34 end-to-end tests covering all subcommands.
+- Working examples in `examples/toy_system/` and `examples/methyltransferase/`.
+
+### Fixed (relative to v0.1.1)
+
+- IRC energy-based initial displacement: Added `step_length` clamp (max 0.5 au) to prevent divergence when `min_eigval ≈ 0`.
+- Hessian cache: Fixed `set_calculator()` clearing `within_partial_hessian` before `cart_hessian` assignment.
+- HessianOptimizer: Fixed GPU/CPU device mismatch in `hessian_recalc`.
+- Frequency analysis: Added float64 enforcement and explicit `(H+Hᵀ)/2` symmetrization.
+- PDB element inference: Fixed `_infer_element_from_pdb_atom_name()` misidentifying protein hydrogens (e.g., `HG2` → `Hg`). Now uses residue-context-aware `guess_element()`.
+- Silent `except Exception: pass` blocks converted to `logger.debug(...)` across all modules.
+- Charge derivation: Uses `--model-pdb` instead of full input when provided.
+- TypeError in `_pseudo_irc_and_match` when mapping value is `None`.
+
+### Architecture — v0.1.1 → v0.2.0
+
+| Aspect | v0.1.1 (`mlmm`) | v0.2.0 (`mlmm-toolkit`) |
+|--------|------------------|--------------------------|
+| Package name | `mlmm` | `mlmm-toolkit` |
+| Codebase size | ~3,700 lines (13 files) | ~35,000 lines (40+ files) |
+| CLI framework | 8 separate entry points (argparse) | 1 entry point, 21 Click subcommands |
+| MM backend | OpenMM (finite difference) | hessian_ff (analytical C++) |
+| ML backends | UMA, AIMNet2 | UMA, ORB, MACE, AIMNet2 |
+| pysisyphus | Git dependency | Bundled (modified fork) |
+| fairchem-core | Git fork | PyPI release |
+| Configuration | Inline kwargs | Centralized `defaults.py` |
+| ONIOM support | Basic link atoms | Full Jacobian + 3-layer B-factor |
+| Documentation | README only | Full bilingual docs (EN/JA) |
+| CI/CD | None | GitHub Actions (3 workflows) |
+| Tests | None | 198 unit + 34 smoke tests |

mlmm_toolkit-0.2.2.dev0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to mlmm-toolkit
+
+Thank you for your interest in contributing to **mlmm-toolkit**.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/t-0hmura/mlmm_toolkit.git
+cd mlmm_toolkit
+
+# Create a conda environment
+conda create -n mlmm python=3.11
+conda activate mlmm
+
+# Install in editable mode
+pip install -e .
+```
+
+## Running Tests
+
+```bash
+# Run the full test suite
+pytest tests/ -v --tb=short
+
+# Run with coverage
+pytest tests/ -v --tb=short --cov=mlmm --cov-report=term-missing
+```
+
+## Code Style
+
+- Use `from __future__ import annotations` in all modules.
+- Use `logging.getLogger(__name__)` for structured logging; avoid bare `print()`.
+- CLI options should include `show_default=True` where applicable.
+- Warning messages via `click.echo()` should use `err=True` to write to stderr.
+
+## Submitting Changes
+
+1. Fork the repository and create a feature branch.
+2. Make your changes and add tests where appropriate.
+3. Ensure all tests pass locally.
+4. Open a pull request with a clear description of the changes.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[GPL-3.0 License](LICENSE).