define-layer

mlmm define-layer partitions a PDB/mmCIF enzyme system into three layers around the ML region and writes the assignments as PDB B-factors, with a CIF companion for bridged input. The ML region can be specified via a model PDB/mmCIF or explicit atom indices; when both are given, the explicit indices take precedence. Use it to define the three-layer ML/MM system before single-structure optimization or end-to-end runs.

The three layers and their B-factor encodings:

Layer

Name

B-factor

Description

1

ML

0.0

Atoms in the ML region

2

Movable-MM

10.0

MM atoms/residues within --radius-freeze of ML

3

Frozen

20.0

MM atoms/residues beyond --radius-freeze

Layer assignment strategy:

  • Residues without ML atoms: the entire residue is assigned to a single layer based on the minimum distance from any ML atom to any atom in the residue.

  • Residues with ML atoms: non-ML atoms in the same residue are classified individually by distance.

Examples

Command form (provide at least one of --model-pdb or --model-indices):

mlmm define-layer -i INPUT.pdb (--model-pdb PDB | --model-indices TEXT) [options]

Define the ML region from a model PDB:

mlmm define-layer -i system.pdb --model-pdb ml_region.pdb -o labeled.pdb

Define the ML region from 0-based atom indices:

mlmm define-layer -i system.pdb --model-indices "0,1,2,3,4" --zero-based -o labeled.pdb

Widen the Movable-MM cutoff to 10.0 Å:

mlmm define-layer -i system.pdb --model-pdb ml_region.pdb \
 --radius-freeze 10.0 -o labeled.pdb

Workflow

  1. ML region identification – The ML region is defined by --model-pdb (atom matching against the input PDB) or --model-indices (explicit atom indices). If --model-indices is provided, it takes precedence over --model-pdb.

  2. Distance computation – For each non-ML atom (or residue), the minimum distance from any ML atom is computed.

  3. Layer assignment – Non-ML atoms/residues are assigned to Movable-MM or Frozen by --radius-freeze.

  4. Output – The output PDB has B-factors set to layer values (0, 10, 20). A summary of layer assignments is printed to the console.

Outputs

  • <output>.pdb – PDB with B-factors set to 0 / 10 / 20

  • Console summary table of layer assignments and atom counts

CLI options

Option

Description

Default

-i, --input PATH

Input PDB or mmCIF file containing the full system.

Required

--model-pdb PATH

PDB or mmCIF file defining atoms in the ML region.

None

--model-indices TEXT

Comma-separated atom indices for the ML region (e.g. "1,2,3,4" or "1-10,15,20-25"); 1-based by default, use --zero-based for 0-based. Takes precedence over --model-pdb.

None

--radius-freeze FLOAT

Distance cutoff (Å) from ML region for Movable-MM. Atoms beyond this are Frozen.

8.0

-o, --output PATH

Output PDB file with B-factors set to layer values.

<input>_layered.pdb

--one-based / --zero-based

Interpret --model-indices as 1-based or 0-based.

True (1-based)

The full flag list is in the generated command reference.

See Also

  • Common Error Recipes — Symptom-first failure routing

  • Troubleshooting — Detailed troubleshooting guide

  • mm-parm — Build AMBER topology (parm7/rst7) before layer definition

  • opt — Single-structure optimization using the layered system

  • all — End-to-end workflow that includes automatic layer definition