Frozen Atoms

Overview

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 cap hydrogens (added at severed bonds by extract) and three sources of freeze_atoms specification.

When a residue is sliced out of a larger protein using the extract sub-command, the bond at the boundary is capped with a cap hydrogen (residue LKH, atom HL, 1.09 Å along the original bond vector). If the parent atom of that cap 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 in opt / tsopt / scan / freq / irc and in path-opt / path-search --mep-mode gsm (hard freeze; the optimizer cannot move them).

  • Hessian: rows and columns of frozen DOFs are either removed (calc.return_partial_hessian: true, the global calculator default; explicitly forced again by opt / tsopt / scan / freq / 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.

  • path-opt --mep-mode dmf and path-search --mep-mode dmf (soft restraint): instead of zeroing forces, these stages add a HarmonicFixAtoms calculator (default k_fix = 300 eV/Ų, ASE units) per image so frozen atoms relax with a harmonic restraint, not a hard constraint. Coordinates may drift slightly from the input geometry.

  • MEP / IRC: path-opt / path-search --mep-mode gsm and irc apply the hard freeze along the resolved path / IRC trajectory; --mep-mode dmf (path-opt or path-search) uses the soft restraint above.

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