Moving frame of reference.

The following options define an automatic calculation of an optimal translation (centerReference) or optimal rotation (rotateReference), that superimposes the positions of this group to a provided set of reference coordinates. This can allow, for example, to effectively remove from certain colvars the effects of molecular tumbling and of diffusion. Given the set of atomic positions $\mathbf{x}_{i}$ , the colvar $\xi$ can be defined on a set of roto-translated positions $\mathbf{x}_{i}' = R(\mathbf{x}_{i} - \mathbf{x}^{\mathrm{C}}) + \mathbf{x}^{\mathrm{ref}}$ . $\mathbf{x}^{\mathrm{C}}$ is the geometric center of the $\mathbf{x}_{i}$ , $R$ is the optimal rotation matrix to the reference positions and $\mathbf{x}^{\mathrm{ref}}$ is the geometric center of the reference positions.

Components that are defined based on pairwise distances are naturally invariant under global roto-translations. Other components are instead affected by global rotations or translations: however, they can be made invariant if they are expressed in the frame of reference of a chosen group of atoms, using the centerReference and rotateReference options. Finally, a few components are defined by convention using a roto-translated frame (e.g. the minimal RMSD): for these components, centerReference and rotateReference are enabled by default. In typical applications, the default settings result in the expected behavior.

Warning on rotating frames of reference and periodic boundary conditions.

rotateReference affects coordinates that depend on minimum-image distances in periodic boundary conditions (PBC). After rotation of the coordinates, the periodic cell vectors become irrelevant: the rotated system is effectively non-periodic. A safe way to handle this is to ensure that the relevant inter-group distance vectors remain smaller than the half-size of the periodic cell. If this is not desirable, one should avoid the rotating frame of reference, and apply orientational restraints to the reference group instead, in order to keep the orientation of the reference group consistent with the orientation of the periodic cell.

Warning on rotating frames of reference and ABF.

Note that centerReference and rotateReference may affect the Jacobian derivative of colvar components in a way that is not taken into account by default. Be careful when using these options in ABF simulations or when using total force values.

• centerReference $\langle\,$ Implicitly remove translations for this group$\,\rangle$
  Context: atom group
  Acceptable values: boolean
  Default value: off
  Description: If this option is on, the center of geometry of the group will be aligned with that of the reference positions provided by either refPositions or refPositionsFile. Colvar components will only have access to the aligned positions. Note: unless otherwise specified, rmsd and eigenvector set this option to on by default.

• rotateReference $\langle\,$ Implicitly remove rotations for this group$\,\rangle$
  Context: atom group
  Acceptable values: boolean
  Default value: off
  Description: If this option is on, the coordinates of this group will be optimally superimposed to the reference positions provided by either refPositions or refPositionsFile. The rotation will be performed around the center of geometry if centerReference is on, or around the origin otherwise. The algorithm used is the same employed by the orientation colvar component [50]. Forces applied to the atoms of this group will also be implicitly rotated back to the original frame. Note: unless otherwise specified, rmsd and eigenvector set this option to on by default.

• refPositions $\langle\,$ Reference positions for fitting (Å)$\,\rangle$
  Context: atom group
  Acceptable values: space-separated list of (x, y, z) triplets
  Description: This option provides a list of reference coordinates for centerReference and/or rotateReference, and is mutually exclusive with refPositionsFile. If only centerReference is on, the list may contain a single (x, y, z) triplet; if also rotateReference is on, the list should be as long as the atom group, and its order must match the order in which atoms were defined.

• refPositionsFile $\langle\,$ File containing the reference positions for fitting$\,\rangle$
  Context: atom group
  Acceptable values: UNIX filename
  Description: This option provides a list of reference coordinates for centerReference and/or rotateReference, and is mutually exclusive with refPositions. The acceptable file format is XYZ, which is read in double precision, or PDB; the latter is discouraged if the precision of the reference coordinates is a concern. Atomic positions are read differently depending on the following scenarios: (i) the file contains exactly as many records as the atoms in the group: all positions are read in sequence; (ii) (most common case) the file contains coordinates for the entire system: only the positions corresponding to the numeric indices of the atom group are read; (iii) if the file is a PDB file and refPositionsCol is specified, positions are read according to the value of the column refPositionsCol (which may be the same as atomsCol). In each case, atoms are read from the file in order of increasing number.

• refPositionsCol $\langle\,$ PDB column containing atom flags$\,\rangle$
  Context: atom group
  Acceptable values: O, B, X, Y, or Z
  Description: Like atomsCol for atomsFile, indicates which column to use to identify the atoms in refPositionsFile (if this is a PDB file).

• refPositionsColValue $\langle\,$ Atom selection flag in the PDB column$\,\rangle$
  Context: atom group
  Acceptable values: positive decimal
  Description: Analogous to atomsColValue, but applied to refPositionsCol.

• fittingGroup $\langle\,$ Use an alternate set of atoms to define the roto-translation$\,\rangle$
  Context: atom group
  Acceptable values: Block fittingGroup { ... }
  Default value: This atom group itself
  Description: If either centerReference or rotateReference is defined, this keyword defines an alternate atom group to calculate the optimal roto-translation. Use this option to define a continuous rotation if the structure of the group involved changes significantly (a typical symptom would be the message ``Warning: discontinuous rotation!'').

  The following example illustrates the use of fittingGroup as part of a Distance to Bound Configuration (DBC) coordinate for use in ligand restraints for binding affinity calculations.[58] The group called ``atoms'' describes coordinates of a ligand's atoms, expressed in a moving frame of reference tied to a binding site (here within a protein). An optimal roto-translation is calculated automatically by fitting the C$_{\alpha}$ trace of the rest of the protein onto the coordinates provided by a PDB file. To define a DBC coordinate, this atom group would be used within an rmsd function.

  # Example: defining a group "atoms" (the ligand) whose coordinates are expressed
  # in a roto-translated frame of reference defined by a second group (the receptor)
  atoms {
  
    atomNumbers 1 2 3 4 5 6 7 # atoms of the ligand (1-based)
  
    centerReference yes
    rotateReference yes
    fittingGroup {
      # define the frame by fitting alpha carbon atoms
      # in 2 protein segments close to the site
      psfSegID PROT PROT
      atomNameResidueRange CA 1-40
      atomNameResidueRange CA 59-100
    }
    refPositionsFile all.pdb # can be the entire system
  }
  

The following two options have default values appropriate for the vast majority of applications, and are only provided to support rare, special cases.

• enableFitGradients $\langle\,$ Include the roto-translational contribution to colvar gradients$\,\rangle$
  Context: atom group
  Acceptable values: boolean
  Default value: on
  Description: When either centerReference or rotateReference is on, the gradients of some colvars include terms proportional to $\partial{}R/\partial\mathbf{x}_{i}$ (rotational gradients) and $\partial\mathbf{x}^{\mathrm{C}}/\partial\mathbf{x}_{i}$ (translational gradients). By default, these terms are calculated and included in the total gradients; if this option is set to off, they are neglected. In the case of a minimum RMSD component, this flag is automatically disabled because the contributions of those derivatives to the gradients cancel out.

• enableForces $\langle\,$ Apply forces from this colvar to this group$\,\rangle$
  Context: atom group
  Acceptable values: boolean
  Default value: on
  Description: If this option is off, no forces are applied the atoms in the group. Other forces are not affected (i.e. those from the MD engine, from other colvars, and other external forces). For dummy atoms, this option is off by default.