Metadata-Version: 2.4
Name: mlmm-toolkit
Version: 0.4.0
Summary: mlmm - ML/MM toolkit for enzyme reaction analysis
Author-email: Takuto Ohmura <ohmura.takuto@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/t-0hmura/mlmm_toolkit
Project-URL: Repository, https://github.com/t-0hmura/mlmm_toolkit
Project-URL: Documentation, https://t-0hmura.github.io/mlmm_toolkit/
Project-URL: Bug Tracker, https://github.com/t-0hmura/mlmm_toolkit/issues
Keywords: computational-chemistry,enzyme,QM/MM,ML/MM,UMA,transition-state,reaction-mechanism
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.txt
License-File: pysisyphus/LICENSE
License-File: thermoanalysis/LICENSE
Requires-Dist: fairchem-core<3,>=2.22
Requires-Dist: pydmf>=1.2
Requires-Dist: torch<2.14,>=2.13
Requires-Dist: ninja
Requires-Dist: numpy<2.5,>=2.0
Requires-Dist: biopython<2.0,>=1.80
Requires-Dist: ase>=3.26.0
Requires-Dist: ParmEd>=4.3.1
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: click<9.0,>=8.1
Requires-Dist: plotly>=6.1.1
Requires-Dist: kaleido
Requires-Dist: autograd
Requires-Dist: dask
Requires-Dist: distributed
Requires-Dist: h5py
Requires-Dist: jinja2
Requires-Dist: natsort
Requires-Dist: psutil
Requires-Dist: rmsd
Requires-Dist: scipy
Requires-Dist: sympy
Requires-Dist: scikit-learn
Requires-Dist: pyparsing
Requires-Dist: pandas
Requires-Dist: pymsym<0.4,>=0.3.5
Provides-Extra: orb
Requires-Dist: orb-models>=0.7.0; python_version >= "3.12" and extra == "orb"
Requires-Dist: orb-models<0.6,>=0.5.5; python_version < "3.12" and extra == "orb"
Provides-Extra: aimnet
Requires-Dist: aimnet>=0.2.0; extra == "aimnet"
Provides-Extra: pdbfixer
Requires-Dist: pdbfixer; extra == "pdbfixer"
Provides-Extra: openmm
Requires-Dist: openmm; extra == "openmm"
Provides-Extra: dft
Requires-Dist: pyscf>=2.13.0; extra == "dft"
Requires-Dist: gpu4pyscf-cuda13x<2,>=1.8.1; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dft"
Requires-Dist: cupy-cuda13x<15,>=13.6; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dft"
Requires-Dist: basis-set-exchange>=0.11; extra == "dft"
Provides-Extra: dft-cuda12
Requires-Dist: pyscf>=2.13.0; extra == "dft-cuda12"
Requires-Dist: gpu4pyscf-cuda12x<2,>=1.8.1; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dft-cuda12"
Requires-Dist: cupy-cuda12x<15,>=13.6; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dft-cuda12"
Requires-Dist: basis-set-exchange>=0.11; extra == "dft-cuda12"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ipywidgets; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: furo>=2024.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo-dark.svg">
    <img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo.svg" alt="mlmm-toolkit" width="520">
  </picture>
</p>

# `mlmm-toolkit`: An End-to-End ML/MM ONIOM Platform for Automated Enzymatic Reaction Mechanism Analysis

[![PyPI](https://img.shields.io/pypi/v/mlmm-toolkit.svg)](https://pypi.org/project/mlmm-toolkit/) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/t-0hmura/mlmm_toolkit/blob/main/examples/mlmm_colab.ipynb)

[Documentation](https://t-0hmura.github.io/mlmm_toolkit/) | [日本語ドキュメント](https://t-0hmura.github.io/mlmm_toolkit/ja/)

<img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/overview.jpg" alt="Overview of ML/MM toolkit" width="90%">

`mlmm-toolkit` is a Python CLI toolkit for analyzing reaction mechanisms in enzyme complexes with ML/MM, an ONIOM combination of machine-learning interatomic potentials (MLIPs) and molecular mechanics (MM), starting from **PDB/mmCIF** structures. It replaces the QM region of conventional QM/MM with a machine-learning interatomic potential (MLIP, default: UMA) while keeping the surrounding protein under an analytical Amber force field (`hessian_ff`).

You can test a reaction mechanism in a **single command** like:

```bash
mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' --tsopt --thermo
```

Starting from the reactant (R) and product (P) structures of the full system, the command above runs:

**ML/MM model setup (ML-region selection + MM parameter preparation) → Minimum energy path (MEP) search → TS optimization → IRC → Thermochemistry**

## Features

- Find a reaction path and its TS from two or more full-system structures you built, without defining a reaction coordinate ([Endpoint mode](docs/quickstart-all.md)).
- Build the path from one structure by driving a reaction coordinate you choose ([Scan-list mode](docs/quickstart-scan.md)).
- Start the TS search directly from a TS candidate ([TS-only mode](docs/quickstart-tsopt.md)).
- Split a multi-step reaction into steps, each with its own TS ([path-search](docs/path-search.md)).
- Set up the ML region, the Amber topology, and the MM layers from a PDB file automatically ([Building the ML region and layers](docs/model-setup.md)).
- Choose the MLIP: UMA, ORB, MACE, or AIMNet2 ([MLIP backends](docs/backends.md)).
- Refine the TS with GPU-accelerated DFT/MM in the same tool ([DFT backend](docs/dft-backend.md)).
- Export to and import from Gaussian ONIOM and ORCA QM/MM input ([oniom-export](docs/oniom-export.md) / [oniom-import](docs/oniom-import.md)).
- Run each stage on its own as a subcommand ([CLI subcommands](#cli-subcommands)).
- Let AI agents run the workflow with the bundled skills ([Agent skills](#agent-skills)).

## Installation

- **OS:** Linux. Native Windows is not supported because AmberTools (`tleap`) is not available there.
- **Python:** 3.11 or later, 3.12 recommended. ORB requires 3.11 or 3.12.
- **GPU:** an NVIDIA GPU.
- **AmberTools (`tleap`):** builds the topology in `mm-parm` and `all`; not needed when you reuse a matching `--parm7`.
- **C++20 compiler:** for the default `hessian_ff` MM backend; `cxx-compiler` in the conda command below installs it.
- **pdbfixer:** needed only for `mm-parm --add-h`.

Full requirements and step-by-step setup: [docs/installation.md](docs/installation.md).

```bash
# 1. New env + AmberTools + CUDA-enabled PyTorch, all from conda-forge
#    (cuda129 instead of cuda130 when nvidia-smi shows CUDA below 13.0)
conda create -n mlmm-toolkit -c conda-forge --override-channels python=3.12 ambertools=24.8 "numpy>=2,<2.5" pdbfixer cxx-compiler cyipopt "pytorch=2.13.0=cuda130*" cuda-nvcc -y
conda activate mlmm-toolkit

# 2. Install mlmm-toolkit and headless Chrome (for PNG export of plots)
pip install mlmm-toolkit
plotly_get_chrome -y

# 3. Authenticate Hugging Face once (only required for the default UMA backend)
#    Accept the FAIR Chemistry License v1 at https://huggingface.co/facebook/UMA, then:
hf auth login                               # interactive
# OR, for non-interactive CI/HPC jobs: export HF_TOKEN=hf_xxx
```

> **Avoid AmberTools conflicts:** on clusters with a system AmberTools module loaded, run `module unload amber` before installing to prevent a ParmEd conflict with the conda-installed AmberTools.

**Optional extras** (install only what you need):

| Extra | Adds |
|---|---|
| `[orb]` / `[aimnet]` | Orb / AIMNet2 MLIP backend (`-b orb` / `-b aimnet2`) — *not* HF-gated |
| `[dft]` / `[dft-cuda12]` | DFT calculator and standalone command with native CUDA 13 / CUDA 12 GPU4PySCF |
| `[pdbfixer]` | PDBFixer extra (alternative to the conda install above) |
| `[openmm]` | OpenMM low-level backend, including virtual-site water models |

The MACE backend (`-b mace`) does not install into the same environment as UMA; create a dedicated environment as described in [docs/installation.md](docs/installation.md).

CUDA module loads, alternative-backend recipes, DMF/`cyipopt` setup, Plotly Chromium, and HPC job-script templates: [docs/installation.md](docs/installation.md) and [docs/device-hpc.md](docs/device-hpc.md).

## Preparing an Enzyme-Substrate System

For most systems the only hard requirement is a **PDB with explicit hydrogens** (at the intended protonation state). `mlmm all` then builds the MM topology, selects the ML region, and runs the whole pipeline in one command — see [Quick Examples](#quick-examples) for the three input modes (multi-structure R → P, single-structure scan, TS-only). The preparation steps below are **optional**.

1. **Build a structural model of the complex.**
   Download coordinates from the Protein Data Bank. If an experimental structure is not available, use structure-prediction programs such as **AlphaFold3**, **Boltz2**, or **Chai**; docking programs; or GUI software such as **PyMOL**. Add hydrogens at the intended protonation state (or let `mm-parm --add-h --ph 7` add them), and match `-l RES:CHARGE` to the H count actually present (e.g. SAM with 23 H = `SAM:1`, 22 H = `SAM:0`). For multi-structure (R → P) runs, every PDB must share the same atoms in the same order.

2. **(Optional) Build the MM topology yourself — it is automatic by default.**
   `mlmm all` (via [`mlmm mm-parm`](docs/mm-parm.md)) generates the Amber `.parm7` / `.rst7` from the PDB automatically; unknown residues (ligands, cofactors) are parameterized with GAFF2 / AM1-BCC — pass formal charges with `-l 'RES:CHARGE'`. Build the topology by hand when it helps — a custom force field, special solvation, or a system the automatic route cannot handle — then pass it with `--parm7`. To mimic aqueous conditions, solvate the complex and remove water molecules beyond ~6 Å (see the [OpenMM cookbook](https://openmm.github.io/openmm-cookbook/latest/tutorials) / tleap).

3. **(Optional) Define the ML region yourself.**
   `mlmm all` extracts the ML region from `-c/--center` and `-r/--radius` automatically. To define it yourself instead, build an ML-region PDB — with [`mlmm extract`](docs/extract.md) or any molecular viewer — and feed it to `mlmm all` (or the per-stage subcommands) with `--model-pdb`; this skips the automatic extraction:

   ```bash
   mlmm extract -i complex.pdb -c 'SAM,GPP' -r 6.0 -l 'SAM:1,GPP:-3' -o ml_region.pdb
   ```

   **Important:** the ML-region PDB is a subset of the full-system atoms: keep their order, names, residue IDs, and chain IDs unchanged, do not add link H, and use the same selection for every state (in PyMOL, tick **"Original atom order"** when exporting). See [How to construct a reliable `model.pdb`](docs/model-setup.md#how-to-construct-a-reliable-modelpdb).

## Quick Examples

The source repository includes full-system [COMT](examples/comt/README.md) and [BezA](examples/beza/README.md) endpoint mechanisms, a methyltransferase scan, and a 122-atom ML/MM fixture; see [`examples/`](https://github.com/t-0hmura/mlmm_toolkit/tree/main/examples). The commands below use the BezA structures and run from the repository root.

```bash
# Endpoint mode (R + P → MEP, with TS + thermochemistry)
mlmm all -i examples/beza/1.R.pdb examples/beza/3.P.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' \
    --tsopt --thermo --out-dir result_mep

# Scan-list mode (single structure → staged bond scan → MEP)
mlmm all -i examples/beza/1.R.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' \
    -s '[("SAM 320 CS1","GPP 321 C7",1.60)]' --tsopt --thermo --out-dir result_scan

# TS-only validation (your own TS candidate → tsopt → IRC → freq)
mlmm all -i TS_candidate_layered.pdb --parm7 complex.parm7 -q 1 --tsopt --thermo --out-dir result_tsonly
```

For Gaussian ONIOM / ORCA QM/MM input-deck export and import, use [`oniom-export`](docs/oniom-export.md) / [`oniom-import`](docs/oniom-import.md). For a walkthrough, see [docs/getting-started.md](docs/getting-started.md) and [docs/quickstart-all.md](docs/quickstart-all.md).

Each stage (`mm-parm` → `extract` → `define-layer` → `opt` → `path-opt` → `tsopt` → `irc` → `freq` → `dft`) also runs as its own subcommand; see [CLI Subcommands](#cli-subcommands) for the per-stage pages.

## Output

Each calculation command writes to its own directory, `./result_<command>/` by default (for example `./result_opt/`, `./result_tsopt/`, or `./result_path_opt/`); `-o/--out-dir` sets another. The preparation commands `extract` and `mm-parm` write their files to the current directory; `define-layer` writes next to its input by default.

A non-dry `all` run writes the deliverables reached by its enabled stages to `./result_all/`:

- `segments/seg_NN/{reactant,ts,product}.*` — the canonical R / TS / P structures to cite
- `mep_trj.pdb` / `mep_trj.xyz` — the merged reaction path; `energy_diagram_MEP.png` — barrier diagram
- `summary.log` / `summary.json`
- Reusable inputs for follow-up runs: `ml_region.pdb` (`--model-pdb`), `mm_parm/*.parm7` (`--parm7`), `layered/` (B-factor-annotated full-system PDBs)
- Directly inspectable model systems before/after link-H insertion:
  `ml_region_without_linkH.xyz` and `ml_region_with_linkH.xyz`,
  plus matching .pdb files for PDB input

Pipeline scratch lives under `_work/`; keep it if you may redo the post-processing with `--resume-segment`. Full layout and filename conventions: [docs/output-layout.md](docs/output-layout.md).

## Colab GUI workspace

**An interactive GUI workspace is available in Google Colab.** It brings full-system coordinates and topology input, ML-region setup, Mol* visualization and atom picking, controls generated from the live CLI, execution, and linked MEP/IRC/result inspection into one notebook. Choose a GPU runtime and [open the Colab GUI workspace](https://colab.research.google.com/github/t-0hmura/mlmm_toolkit/blob/main/examples/mlmm_colab.ipynb).

<img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/colab_workspace.png" alt="mlmm-toolkit Colab GUI workspace showing Mol* structure setup and ML/MM controls" width="90%">

## CLI Subcommands

| Subcommand | Role | Doc |
|---|---|---|
| `all` (default) | End-to-end: extract → MM topology/layers → MEP → TS → IRC → freq → DFT | [all](docs/all.md) |
| `mm-parm` | Generate parm7/rst7 via AmberTools | [mm-parm](docs/mm-parm.md) |
| `extract` | Extract active-site pocket | [extract](docs/extract.md) |
| `define-layer` | Assign 3-layer ML/MM B-factor encoding | [define-layer](docs/define-layer.md) |
| `fix-altloc` | Resolve PDB alternate conformations | [fix-altloc](docs/fix-altloc.md) |
| `add-elem-info` | Repair PDB element columns (77–78) | [add-elem-info](docs/add-elem-info.md) |
| `opt` | Geometry optimization (L-BFGS / RFO) | [opt](docs/opt.md) |
| `tsopt` | TS optimization (Dimer / RS-P-RFO) | [tsopt](docs/tsopt.md) |
| `path-opt` | MEP via GSM or DMF | [path-opt](docs/path-opt.md) |
| `path-search` | Recursive MEP search with refinement | [path-search](docs/path-search.md) |
| `scan` / `scan2d` / `scan3d` | 1D / 2D / 3D bond-distance scans | [scan](docs/scan.md) · [scan2d](docs/scan2d.md) · [scan3d](docs/scan3d.md) |
| `freq` | Vibrational analysis + thermochemistry | [freq](docs/freq.md) |
| `irc` | IRC (EulerPC) | [irc](docs/irc.md) |
| `dft` | Single-point DFT | [dft](docs/dft.md) |
| `sp` | Single-point ML/MM ONIOM | [sp](docs/sp.md) |
| `bond-summary` | Compare structures, report bond changes | [bond-summary](docs/bond-summary.md) |
| `trj2fig` / `energy-diagram` | Energy plot / R→TS→P diagram | [trj2fig](docs/trj2fig.md) · [energy-diagram](docs/energy-diagram.md) |
| `oniom-export` | Gaussian ONIOM / ORCA QM/MM input-deck export | [oniom-export](docs/oniom-export.md) |
| `oniom-import` | Gaussian ONIOM / ORCA QM/MM input-deck import | [oniom-import](docs/oniom-import.md) |

How the ML/MM calculator works (ONIOM energy, link atoms, units, and the Python API): [docs/mlmm-calc.md](docs/mlmm-calc.md).

## Documentation

- [Getting Started](docs/getting-started.md) · [Installation](docs/installation.md) · [Quickstart: all](docs/quickstart-all.md) · [Building the ML region and layers](docs/model-setup.md) · [DFT backend](docs/dft-backend.md) · [Troubleshooting](docs/troubleshooting.md)
- Full site: <https://t-0hmura.github.io/mlmm_toolkit/>

## Agent Skills

`skills/` holds Agent Skills that let an AI coding agent run `mlmm-toolkit` workflows and subcommands. Copy the skill folders into `.claude/skills/` or `~/.claude/skills/` for Claude Code, or into `.agents/skills/` or `~/.agents/skills/` for Codex. The list and an example copy command are in [`skills/README.md`](skills/README.md).

## Getting Help

```bash
mlmm --help                       # top-level
mlmm <subcmd> --help              # core options
mlmm <subcmd> --help-advanced     # full option set
```

Issues: <https://github.com/t-0hmura/mlmm_toolkit/issues>.

## Related tools

| Tool | Use case |
|---|---|
| [**pdb2reaction**](https://github.com/t-0hmura/pdb2reaction) | Pure-MLIP reaction paths for **cluster models and small molecules** from PDB / XYZ / GJF. |
| [**uma_pysis**](https://github.com/t-0hmura/uma_pysis) | Lightweight **YAML-driven UMA–pysisyphus interface** for quick/exploratory reaction-mechanism studies (GS / TS / IRC / ΔG). |

## Known limitations

- **MACE + UMA cannot coexist** (`e3nn` version conflict). Use separate conda envs.
- **DFT/MM** is practical for an ML region of up to about **500 atoms for a single point** and about **300 atoms for an optimization** on an HPC GPU, and up to about **200 atoms on a consumer GPU** (ωB97M-V/def2-SVP, the default; from experience).
- **MACE and ORB need fp64** (`--precision fp64`, their default); in fp32, extra imaginary modes appear more often. fp64 is slow on consumer GPUs: on HPC GPUs, ORB in fp64 is very cost-effective, and on a consumer GPU, UMA in fp32 gives the best balance.
- **CPU-only execution** is supported but usually **much slower than GPU**.
- The bundled pysisyphus is a modified fork; do not install upstream pysisyphus in the same environment.

## Citation

```bibtex
@article{ohmura2025mlmm,
  author  = {Ohmura, Takuto and Inoue, Sei and Terada, Tohru},
  title   = {ML/MM toolkit -- Towards Accelerated Mechanistic Investigation of Enzymatic Reactions},
  journal = {ChemRxiv}, year = {2025}, doi = {10.26434/chemrxiv-2025-jft1k}
}
```

## Contributing

Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

GNU General Public License v3 or later (GPL-3.0-or-later).
