`mm-parm`¶

Overview¶

Summary: Build Amber prmtop/rst7 topology files from a PDB with automatic GAFF2 ligand parameterization, disulfide detection, and optional hydrogen addition via PDBFixer.

mlmm mm-parm generates Amber topology/coordinate files from a PDB. The input PDB is used without structural fixing by default. Unknown residues are automatically parameterized with antechamber (GAFF2, AM1-BCC charges) and parmchk2. Residues explicitly listed in --ligand-charge are treated as ligand/cofactor definitions and are prioritized for GAFF2 parameterization. Disulfide bonds are inferred geometrically from SG-SG (or S-S) distances within 2.3 Å. Amino-acid residues listed in AMINO_ACIDS but still unrecognized by the selected force field are not handled automatically – the build aborts with a message asking you to parameterize them manually.

When --add-h, hydrogens are added at the specified --ph using PDBFixer before tleap processing. No other structural fixing is performed. With --ff-set ff14SB, the force field switches to ff14SB (proteins) + TIP3P (water) (+ phosaa14SB).

Minimal example¶

mlmm mm-parm -i input.pdb --out-prefix complex \
 -l "GPP=-3,MMT=-1" --ligand-mult "GPP=1,MMT=1"

Output checklist¶

<prefix>.parm7 – Amber prmtop topology
<prefix>.rst7 – Amber ASCII inpcrd coordinates
<prefix>.pdb – LEaP savepdb output (see naming rules below)

Common examples¶

Basic topology build with hydrogen addition.

mlmm mm-parm -i input.pdb --out-prefix complex \
 -l "GPP=-3,MMT=-1" --ligand-mult "GPP=1,MMT=1" \
 --add-ter --ff-set ff19SB --add-h --ph 7.0

Build without hydrogen addition.

mlmm mm-parm -i input.pdb --out-prefix complex \
 -l "GPP=-3" --no-add-h

Workflow¶

Input preparation – The input PDB is read as-is (no structural fixing). If --add-h is set, hydrogens are added via PDBFixer at the specified --ph.
TER insertion – When --add-ter (default), TER records are inserted before and after contiguous blocks of ligand/water/ion residues.
Unknown residue parameterization – Residues not recognized by the force field are parameterized with antechamber (GAFF2, AM1-BCC) and parmchk2. Residues named in --ligand-charge are prioritized for this route. Formal charge and spin multiplicity are controlled via --ligand-charge and --ligand-mult.
Disulfide detection – CYS/CYM/CYX pairs with SG-SG (or S-S) distance <= 2.3 Å are bonded automatically.
Topology build – tleap generates parm7/rst7/pdb files using the selected force field set.

CLI options¶

Option	Description	Default
`-i, --input PATH`	Input PDB (used as-is unless `--add-h`).	Required
`--out-prefix TEXT`	Output prefix for parm7/rst7/pdb files.	Stem of input PDB
`-l, --ligand-charge TEXT`	Map residue name to formal charge, e.g. `"GPP=-3,MMT=-1"`.	None
`--ligand-mult TEXT`	Map residue name to spin multiplicity, e.g. `"HEM=1,NO=2"`. Unspecified residues default to singlet (1).	None
`--keep-temp/--no-keep-temp`	Keep intermediate files/logs in a working directory (for debugging).	`False`
`--add-ter/--no-add-ter`	Insert TER before/after ligand/water/ion blocks.	`True`
`--add-h/--no-add-h`	Add hydrogens at `--ph` using PDBFixer.	`False`
`--ph FLOAT`	pH for PDBFixer hydrogen addition (used only with `--add-h`).	`7.0`
`--ff-set {ff19SB\|ff14SB}`	Force field set: ff19SB (default) or ff14SB.	`ff19SB`

Limitations and when to use `--parm` instead¶

mm-parm relies on AmberTools tleap with GAFF2 automatic parameterization and works well when the substrate is a typical organic molecule. For the following cases, it is strongly recommended to prepare your own topology externally (e.g. with tleap, MCPB.py, or glycam.org tools) and supply it via the --parm flag of each subcommand:

Metalloenzymes – Metal centers require specialized bonded/non-bonded parameters (e.g. MCPB.py, the bonded model, or ZAFF). Automatic GAFF2 parameterization cannot handle metal-ligand coordination.
Glycans and carbohydrate-containing systems – Glycan linkages need GLYCAM force field parameters that are not included in the standard GAFF2/ff19SB setup.
Non-standard amino acids or post-translational modifications – Phosphorylated, methylated, or other modified residues may require custom frcmod/lib files.
MD snapshot initial structures – When starting from an MD trajectory snapshot, reusing the same .parm7 file from the MD simulation is the most appropriate approach. This ensures consistency between the MM energy surface used for ML/MM and the one used in the preceding MD, avoiding artifacts from re-parameterization (e.g. different partial charges or atom-type assignments).

# Example: supply a pre-built topology from MD
mlmm opt -i snapshot_layered.pdb --parm md_system.parm7 -q -1 -m 1 \
  --opt-mode grad --out-dir result

mm-parm¶