mlmm-overview

name: mlmm-overview description: Orientation for mlmm-toolkit — what it is, when to use it, and how it differs from generic ML/MM MD packages (three-layer ML/movable-MM/frozen ONIOM via PDB B-factor encoding, analytical hessian_ff full-system Hessian, microiteration with link-atom Jacobian coupling, AmberTools-driven MM parameterization). TRIGGER on first-touch / "what is mlmm-toolkit" / "should I use it" / "how does it compare to OpenMM / GROMACS / Sire" questions. SKIP when the user has already named a subcommand, an install issue, an output file, a structure format, or a cluster — sibling skills cover those.

mlmm-toolkit Overview

Purpose

mlmm-toolkit is a command-line toolkit for ML/MM ONIOM workflows on solvated enzyme systems. It chains active-site definition, ML region optimization with MM-environment relaxation, MEP search, TS optimization, IRC validation, vibrational analysis, and an optional DFT single-point — all driven by GPU-resident MLIP backends together with an MM force-field layer.

The design choices that make it distinct:

1. 3-layer ONIOM via PDB B-factor encoding. The B-factor field classifies every atom into ML (0.0), movable-MM (10.0), or frozen (20.0). One PDB → one defined system, no separate topology files for the partitioning.
2. hessian_ff analytical Hessian for MM. Custom analytical Hessian for the MM force field (instead of finite-difference), used both in microiteration and in the ML/MM-coupled freq step.
3. Microiteration outer/inner loop. ML region geometry update alternates with MM relaxation; outer ML steps see a relaxed MM environment.
4. Bundled GPU pysisyphus fork. Geometry / TS / IRC stay on the same device as the MLIP.
5. AmberTools-driven MM parameterization. mlmm mm-parm builds parm7/rst7 from a PDB; define-layer assigns the ML / movable / frozen labels.

When to use it

When not to use it

• Pure QM (DFT-only) cluster: a direct ORCA / Gaussian / Q-Chem workflow is leaner.
• Free-energy simulations (umbrella sampling, metadynamics): out of scope.

Quick check

mlmm --version
mlmm --help              # lists the available subcommands
mlmm all --help          # end-to-end pipeline

If mlmm is not on PATH or imports fail, see mlmm-install-backends/SKILL.md.

Pipeline at a glance

PDB(s)          (B-factor: 0.0=ML, 10.0=movable-MM, 20.0=frozen)
  │
  ▼
[mm-parm]       AmberTools tleap → parm7 / rst7
  │
  ▼
[define-layer]  expand / refine / verify the ML/MM/Frozen labels
  │
  ▼
[path-opt]      single-pass MEP with ONIOM gradients (ML + MM coupling);
                recursive [path-search] with --refine-path
  │
  ▼
[tsopt]         TS refinement per segment
  │
  ▼
[irc]           forward/backward IRC + endpoint LBFGS
  │
  ▼
[freq]          analytical-Hessian ONIOM frequencies + QRRHO thermo
  │
  ▼
[dft]           (optional) single-point DFT on ML region only

Each step is also available as its own subcommand. mlmm all chains the whole pipeline.

Backend choices

Supported MLIP backends:

MM backend defaults to hessian_ff (CPU, analytical Hessian); the finite-difference openmm backend is selectable via --mm-backend openmm. DFT (optional) uses PySCF / GPU4PySCF.

ML/MM-aware CLI conventions

Every ML/MM-evaluating subcommand (opt, tsopt, path-search, scan, freq, irc, dft, all, …) takes:

See mlmm-cli/SKILL.md for per-subcommand specifics.

Where the code lives

Navigation map of the skill set