Frozen Atoms

Overview

Summary: Cluster models need a small set of atoms held in place at the truncation boundary so the optimizer cannot pull the dangling fragment into something unphysical. pdb2reaction handles this through link hydrogens (added at severed bonds by extract) and three layers of freeze_atoms specification.

When a residue is sliced out of a larger protein, the bond at the boundary is capped with a link hydrogen (residue LKH, atom HL, 1.09 Å along the original bond vector). If the parent atom of that link hydrogen is left free, gradient descent will quietly relax the cap+parent pair into a different geometry, deforming the boundary. Freezing the relevant atoms keeps the boundary stationary throughout optimization, MEP search, IRC, and vibrational analysis.

Three ways to specify frozen atoms

2. --freeze-atoms 'i,j,k,...' (CLI explicit list)

Comma-separated 1-based atom indices, applicable to any input format. Complements --freeze-links (the union is frozen at run time).

pdb2reaction tsopt -i ts_candidate.xyz -q 0 -m 1 \
  --freeze-atoms '12,15,28,29,42'

3. YAML geom.freeze_atoms (via --config)

geom:
  freeze_atoms: [12, 15, 28, 29, 42]   # 1-based indices

Useful when the list is long or you want to ship it with the rest of the run configuration. CLI and YAML lists are merged, not replaced.

pdb2reaction tsopt -i ts.xyz -q 0 -m 1 --config tsopt.yaml

How the three sources combine

The frozen-atom set used at run time is the union of:

  • YAML geom.freeze_atoms (--config FILE), plus

  • CLI --freeze-atoms, plus

  • atoms detected as LKH parents when --freeze-links is on.

There is no mode that substitutes one for another; every entry that appears in any source is frozen.

Effect on the calculation

  • Forces: zeroed for every frozen DOF (the optimizer cannot move them).

  • Hessian: rows and columns of frozen DOFs are either removed (calc.return_partial_hessian: true, the default for freq and forced for irc) or zeroed in the full matrix.

  • Vibrational analysis: when frozen atoms are present, freq automatically performs Partial Hessian Vibrational Analysis (PHVA) on the active block; the 5 cm⁻¹ vs 100 cm⁻¹ thresholds apply to the resulting eigenvalues.

  • MEP / IRC: frozen atoms keep their initial coordinates at every image / step.

Subcommand coverage

Subcommand

--freeze-links (PDB)

--freeze-atoms (any input)

YAML geom.freeze_atoms

extract

(inserts LKH/HL; flag is for downstream stages)

n/a

n/a

opt

yes

yes

yes

tsopt

yes

yes

yes

freq

yes (triggers PHVA)

yes

yes

irc

yes

yes

yes

path-opt

yes

yes

yes

path-search

yes

yes

yes

scan / scan2d / scan3d

yes

yes

yes

all

yes

yes

yes

Common pitfalls

  • Manually deleted LKH/HL records. --freeze-links finds nothing to freeze. Use --freeze-atoms to specify the boundary explicitly, or rerun extract.

  • Re-numbered atoms. --freeze-atoms and geom.freeze_atoms are 1-based and tied to input atom order; if you re-extract and the order changes, regenerate the index list.

  • XYZ/GJF without a topology. No LKH records exist, so --freeze-links is a no-op. Provide --ref-pdb FILE or an explicit --freeze-atoms list.

  • --no-freeze-links. Disables the auto-freeze. Useful only for diagnostic runs that intentionally let the boundary relax; production cluster-model runs should leave --freeze-links on.

See also