mlmm-structure-io

name: mlmm-structure-io description: PDB / XYZ / GJF / Amber parm7+rst7 input-file reference for mlmm-toolkit, plus the charge / multiplicity decision workflow and the B-factor layer encoding (ML=0 / movable-MM=10 / frozen-MM=20) that defines a three-layer ONIOM system from a single prepared PDB. TRIGGER on editing or inspecting a structure file, deciding -q / -l / -m, interpreting residue / charge / spin in an input, or assigning B-factor layers. SKIP for subcommand syntax, output parsing, install, or HPC questions.

mlmm-toolkit Structure I/O

Purpose

mlmm-toolkit reads four formats; each carries different information and is preferred for different stages:

PDB / XYZ / GJF use Å for coordinates and conventional element symbols. parm7 is the Amber topology format (text but byte-aligned).

Per-format details:

Decision tree: which format to feed mlmm-toolkit

Is the input the full enzyme + parm7 you'll run ML/MM on?
  └── PDB (full enzyme, with B-factor layer assignment) + parm7
      → all of opt / tsopt / scan / path-search / freq / irc / dft

Is the input a single TS candidate to validate?
  └── XYZ + --ref-pdb (full enzyme PDB) + --parm
      → tsopt / freq / irc / all (TS-only mode)

Is the input a Gaussian g16 ONIOM input you want to import?
  └── GJF → mlmm oniom-import → reconstructs PDB + extracts layer info

Do you need a parm7 / rst7 from a raw enzyme PDB?
  └── mlmm mm-parm → PDB + AmberTools tleap → parm7 + rst7

ML/MM-aware CLI conventions

Most subcommands take --parm FILE (the parm7) plus one of:

• --detect-layer (default on) — read the layer assignment from the input PDB's B-factor field
• --model-pdb FILE — explicit ML-region PDB
• --model-indices '1-50,75,100-110' — explicit atom-index list

When -i is XYZ, also pass --ref-pdb so atom ordering and residue context are recoverable.

Editing approach (agent-side)

When an agent must edit a structure file:

1. Read the file first to understand current layout (residues, atom counts, B-factor layer assignment, charge/multiplicity if present).
2. Identify the change and confirm it does not violate format conventions (PDB column widths, XYZ first-line atom count, parm7 byte alignment).
3. For unknown charge / multiplicity values, confirm with the user or do a literature lookup before guessing — see charge-multiplicity.md for the workflow.
4. For layer-assignment changes (B-factor edits), use mlmm define-layer rather than hand-editing if possible.

Subcommand × format compatibility

Quick reference

PDB ATOM/HETATM record (cols 1-based, inclusive)
     name(13-16) altloc(17) resName(18-20) chainID(22)
     resSeq(23-26)  X(31-38)  Y(39-46)  Z(47-54)
     occupancy(55-60)  bfactor(61-66, used as layer: 0.0/10.0/20.0)
     element(77-78)

XYZ  line 1: <natoms>
     line 2: <comment, optional ASE Properties=…>
     line 3+: <element>  <x>  <y>  <z>

GJF  %nproc=...  %mem=...
     # <route line:  functional/basis  options>

     <title>

     <charge> <spin>
     <element>  <x>  <y>  <z>
     ...

parm7  Amber topology — generate with `mlmm mm-parm`; do not hand-edit.
       Pair with rst7 (coordinate snapshot).

Full byte-by-byte / per-keyword detail in the per-format mds.

Charge / multiplicity defaults

• -m 1 (singlet, closed shell) is the default for almost every organic / biological / metal-coordination cluster.
• Use -m 2 for radicals, -m 3+ for unusual high-spin metals.
• -q is the ML region charge. -l 'RES:Q' derives -q from per-residue charges + mlmm's internal amino-acid table.
• For XYZ inputs (no header), -q and -m must be on the CLI.

If unsure about charge or spin, do not guess silently — follow charge-multiplicity.md.

See also

• mlmm-cli/extract.md, mm-parm.md, define-layer.md — pre-pipeline.
• mlmm-cli/SKILL.md — common flag conventions across subcommands.
• mlmm-workflows-output/SKILL.md — what comes out of the pipeline (XYZ / PDB).