align

An align directive rigidly aligns the pipeline system (or a selection of it) to a reference coordinate file by computing the least-RMSD rotation and translation between two atom sets, then applying that transformation. Internally it uses VMD’s measure fit command.

Parameters

ref_pdb (required)

Path to the reference PDB file. The file must be present in the working directory when the task runs.

ref_psf (optional)

Path to a reference PSF file. When provided, both the PSF and PDB are loaded together in VMD so that the full topology is available for selection purposes. When omitted the reference is loaded as a plain PDB, which is sufficient for coordinate-based fitting.

mobile_sel (optional, default: "all" )

A VMD atomselect string identifying which atoms of the pipeline system are used to compute the fit. The atom count and order must match those selected by ref_sel in the reference.

ref_sel (optional, default: inherits mobile_sel )

A VMD atomselect string identifying which atoms of the reference system are used to compute the fit. When omitted, mobile_sel is reused, which is correct whenever both systems share the same topology.

apply_to (optional, default: "all" )

A VMD atomselect string identifying which atoms of the pipeline system are actually moved by the fitted transformation. This allows you to compute the fit on a subset (e.g. backbone only) while translating and rotating the entire system.

Congruency check

Before computing the fit, the generated VMD script verifies that mobile_sel and ref_sel select the same number of atoms. If they differ, VMD prints a descriptive error message and exits with a non-zero code, which pestifer surfaces as a task failure.

Note

measure fit requires both selections to contain the same number of atoms in the same order. Atom-count equality is checked automatically; atom ordering is the user’s responsibility. When in doubt, use consistent selection strings and load the reference with its PSF.

Examples

Align the entire pipeline system to a reference PDB (PDB-only reference, fit and move all atoms):

tasks:
  - manipulate:
      mods:
        align:
          - ref_pdb: reference.pdb

Fit on backbone atoms only, move the whole system, using a reference that has its own topology:

tasks:
  - manipulate:
      mods:
        align:
          - ref_pdb: reference.pdb
            ref_psf: reference.psf
            mobile_sel: "backbone"
            apply_to: "all"

Fit protein chain A to a reference chain using different selection strings for mobile and reference:

tasks:
  - manipulate:
      mods:
        align:
          - ref_pdb: reference.pdb
            mobile_sel: "chain A and backbone"
            ref_sel: "chain B and backbone"
            apply_to: "all"

Workflow note

The align directive moves the pipeline system to match the reference. If instead you need to align an incoming external system to the pipeline system (for example, before a merge), that external system must first have its own PSF built in a separate pestifer run, because merge requires a PSF for every input system. The alignment is a coordinate-only operation so the PSF from that separate run can be reused directly; there is no need to rebuild it after alignment.