Quickstart: mlmm scan

Goal

Generate restrained endpoint structures and trajectories from a single structure using a YAML scan specification.

Prerequisites

  • Input structure: pocket.pdb

  • MM topology: real.parm7

  • ML region definition: ml_region.pdb, explicit model indices, or valid B-factor layers

These are typically generated by mlmm all, mlmm extract, and mlmm mm-parm.

One YAML stages entry defines one stage. Multiple distance tuples within an entry are advanced concertedly; multiple entries form a sequential multistage scan. Use scan2d when two distances must instead form independent grid axes.

1. Prepare scan.yaml

one_based: true
stages:
 - [[12, 45, 2.20]]
 - [[10, 55, 1.35], [23, 34, 1.80]]

2. Run scan

mlmm scan -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -s scan.yaml -o ./result_scan

Note

To validate the spec without running (GPU-free), add --print-parsed. This prints the parsed targets and exits before any calculation, so it does not produce the scan outputs listed below.

Output validation

  • result_scan/stage_01/result.pdb

  • result_scan/stage_02/result.pdb

  • result_scan/scan_trj.xyz (always written); result_scan/scan.pdb when conversion and a reference topology are available

Inline literal input (without YAML file)

Instead of a YAML spec file, you can pass scan targets directly on the command line:

mlmm scan -i layered.pdb --parm system.parm7 -q 0 \
  --scan-lists '[(1,5,1.4)]' --no-preopt --no-endopt

Or using PDB atom selectors:

mlmm scan -i layered.pdb --parm system.parm7 -q 0 \
  --scan-lists '[("TYR,285,CA","MMT,309,C10",2.20)]' --no-preopt --no-endopt

Both 1-based atom indices and PDB atom name strings are accepted. See scan.md for full details.

For detailed options, run mlmm scan --help-advanced.

Next step