Selecting atoms for colvars: defining atom groups

Selection keywords

To define collective variables, atoms are usually selected by group. Each group is identified by a name that is unique in the context of the specific colvar component (e.g. for a distance component, the names of the two groups are group1 and group2). The name is followed by a brace-delimited block of selection keywords: these may be used individually or in combination with each other, and each can be repeated any number of times. Selection is incremental: each keyword adds the corresponding atoms to the selection, so that different sets of atoms can be combined. However, atoms included by multiple keywords are only counted once. Below is an example configuration for an atom group named ``atoms'', which uses an unusually varied combination of selection keywords:

atoms {

  # add atoms 1 and 3 to this group (note: the first atom in the system is 1)
  atomNumbers {
    1 3
  }

  # add atoms starting from 20 up to and including 50
  atomNumbersRange 20-50

  # add index group (requires a .ndx file to be provided globally)
  indexGroup Water

  # add all the atoms with occupancy 2 in the file atoms.pdb
  atomsFile atoms.pdb
  atomsCol O
  atomsColValue 2.0

  # add all the C-alphas within residues 11 to 20 of segments "PR1" and "PR2"
  psfSegID PR1 PR2
  atomNameResidueRange CA 11-20
  atomNameResidueRange CA 11-20
}

The resulting selection includes atoms 1 and 3, those between 20 and 50, and those in the index group called ``Water''; the indices of this group are read from the file provided by indexFile, in the global section of the configuration file.

The complete list of selection keywords available in NAMD is:

• atomNumbers $<$ (atom group context) List of atom numbers $>$
  Acceptable Values: space-separated list of positive integers
  Description: This option adds to the group all the atoms whose numbers are in the list. The number of the first atom in the system is 1: to convert from a VMD selection, use ``atomselect get serial''.

• indexGroup $<$ (atom group context) Name of index group to be used (GROMACS format) $>$
  Acceptable Values: string
  Description: If the name of an index file has been provided by indexFile, this option allows to select one index group from that file: the atoms from that index group will be used to define the current group.

• atomNumbersRange $<$ (atom group context) Atoms within a number range $>$
  Acceptable Values: $<$ Starting number$>$ -$<$ Ending number$>$
  Description: This option includes in the group all atoms whose numbers are within the range specified. The number of the first atom in the system is 1.

• atomNameResidueRange $<$ (atom group context) Named atoms within a range of residue numbers $>$
  Acceptable Values: $<$ Atom name$>$ $<$ Starting residue$>$ -$<$ Ending residue$>$
  Description: This option adds to the group all the atoms with the provided name, within residues in the given range.

• psfSegID $<$ (atom group context) PSF segment identifier $>$
  Acceptable Values: space-separated list of strings (max 4 characters)
  Description: This option sets the PSF segment identifier for atomNameResidueRange. Multiple values may be provided, which correspond to multiple instances of atomNameResidueRange, in the order of their occurrence. This option is only necessary if a PSF topology file is used.

• atomsFile $<$ (atom group context) PDB file name for atom selection $>$
  Acceptable Values: UNIX filename
  Description: This option selects atoms from the PDB file provided and adds them to the group according to numerical flags in the column atomsCol. Note: the sequence of atoms in the PDB file provided must match that in the system's topology.

• atomsCol $<$ (atom group context) PDB column to use for atom selection flags $>$
  Acceptable Values: O, B, X, Y, or Z
  Description: This option specifies which PDB column in atomsFile is used to determine which atoms are to be included in the group.

• atomsColValue $<$ (atom group context) Atom selection flag in the PDB column $>$
  Acceptable Values: positive decimal
  Description: If defined, this value in atomsCol identifies atoms in atomsFile that are included in the group. If undefined, all atoms with a non-zero value in atomsCol are included.

• dummyAtom $<$ (atom group context) Dummy atom position (Å) $>$
  Acceptable Values: (x, y, z) triplet
  Description: Instead of selecting any atom, this option makes the group a virtual particle at a fixed position in space. This is useful e.g. to replace a group's center of geometry with a user-defined position.

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.

• centerReference $<$ (atom group context) Implicitly remove translations for this 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 $<$ (atom group context) Implicitly remove rotations for this 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, around the origin otherwise. The algorithm used is the same employed by the orientation colvar component [18]. 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 $<$ (atom group context) Reference positions for fitting (Å) $>$
  Acceptable Values: space-separated list of (x, y, z) triplets
  Description: This option provides a list of reference coordinates for centerReference or rotateReference. 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.

• refPositionsFile $<$ (atom group context) File containing the reference positions for fitting $>$
  Acceptable Values: UNIX filename
  Description: Supplies the reference positions (mutually exclusive with refPositions). Atomic positions are read differently depending on the three following scenarios: i) refPositionsCol is specified: the PDB file contains a set of position larger than the size of the group, and positions are read according to the value of the column refPositionsCol (which may be the same as atomsCol). ii) refPositionsCol is not specified and the PDB file contains exactly as many ATOM records as the atoms in the group: all positions are read in sequence; iii) refPositionsCol is not specified and the PDB file contains the entire system: the positions corresponding to the numeric indices of the atom group are read.

• refPositionsCol $<$ (atom group context) PDB column containing atom flags $>$
  Acceptable Values: O, B, X, Y, or Z
  Description: Like atomsCol for atomsFile, indicates which column to use to identify the atoms in refPositionsFile.

• refPositionsColValue $<$ (atom group context) Atom selection flag in the PDB column $>$
  Acceptable Values: positive decimal
  Description: Analogous to atomsColValue, but applied to refPositionsCol.

• refPositionsGroup $<$ (atom group context) Use an alternate set of atoms to define the roto-translation $>$
  Acceptable Values: Block refPositionsGroup { ... }
  Default Value: This 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 syntax of refPositionsGroup: a group called ``atoms'' is defined, including 8 C$_{\alpha}$ atoms of a protein of 100 residues. 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.

  # Example: defining a group "atoms", with its coordinates expressed
  # on a roto-translated frame of reference defined by a second group
  atoms {
  
    psfSegID PROT
    atomNameResidueRange CA 41-48
  
    centerReference yes
    rotateReference yes
    refPositionsGroup {
      # define the frame by fitting the rest of the protein
      psfSegID PROT PROT
      atomNameResidueRange CA 1-40
      atomNameResidueRange CA 49-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 $<$ (atom group context) Include the roto-translational contribution to colvar gradients $>$
  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.

• enableForces $<$ (atom group context) Apply forces from this colvar to this group $>$
  Acceptable Values: boolean
  Default Value: on
  Description: If this option is off, no forces are applied from this colvar to this 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.

Treatment of periodic boundary conditions.

In simulations with periodic boundary conditions, NAMD maintains the coordinates of all the atoms within a molecule contiguous to each other (i.e. there are no spurious ``jumps'' in the molecular bonds). The colvar module relies on this when calculating a group's center of geometry, but the condition may fail if the group spans different molecules: in that case, writing the NAMD output files wrapAll or wrapWater could produce wrong results when a simulation run is continued from a previous one. The user should then determine, according to which type of colvars are being calculated, whether wrapAll or wrapWater can be enabled. In general, internal coordinate wrapping by NAMD does not affect the calculation of colvars if each atom group satisfies one or more of the following:

i)

it is composed by only one atom;

ii)

it is used by a colvar component which does not make use of its center of geometry, but only of pairwise distances (distanceInv, coordNum, hBond, alpha, dihedralPC);

iii)

it is used by a colvar component that ignores the ill-defined Cartesian components of its center of mass (such as the $x$ and $y$ components of a membrane's center of mass modeled with distanceZ);

iv)

it has all of its atoms within the same molecule.

Computational cost of colvars based on group size.

In parallel MD simulations, the calculation of most interaction terms are spread over many computational nodes, but the calculation of colvars is not parallelized. Therefore, additional calculations are executed by the node calculating the colvars, and most importantly, additional communication is added between the first node and the other nodes. The latency-tolerant design and dynamic load balancing of NAMD alleviate both factors: however, under some circumstances, a noticeable performance impact may be observed. To mitigate that, atom groups should be kept relatively small (up to a few thousands, depending on the computational cost to simulate the system by itself).