Non-bonded interaction distance-testing

The last critical parameter for non-bonded interaction calculations is the parameter pairlistdist. To reduce the cost of performing the non-bonded interactions, NAMD uses a non-bonded pair list which contained all pairs of atoms for which non-bonded interactions should be calculated. Performing the search for pairs of atoms that should have their interactions calculated is an expensive operation. Thus, the pair list is only calculated periodically, at least once per cycle. Unfortunately, pairs of atoms move relative to each other during the steps between preparation of the pair list. Because of this, if the pair list were built to include only those pairs of atoms that are within the cutoff distance when the list is generated, it would be possible for atoms to drift closer together than the cutoff distance during subsequent timesteps and yet not have their non-bonded interactions calculated.

Let us consider a concrete example to better understand this. Assume that the pairlist is built once every ten timesteps and that the cutoff distance is 8.0 Å. Consider a pair of atoms A and B that are 8.1 Å apart when the pairlist is built. If the pair list includes only those atoms within the cutoff distance, this pair would not be included in the list. Now assume that after five timesteps, atoms A and B have moved to only 7.9 Å apart. A and B are now within the cutoff distance of each other, and should have their non-bonded interactions calculated. However, because the non-bonded interactions are based solely on the pair list and the pair list will not be rebuilt for another five timesteps, this pair will be ignored for five timesteps causing energy not to be conserved within the system.

To avoid this problem, the parameter pairlistdist allows the user to specify a distance greater than the cutoff distance for pairs to be included in the pair list, as shown in Figure 4. Pairs that are included in the pair list but are outside the cutoff distance are simply ignored. So in the above example, if the pairlistdist were set to $10.0$ Å, then the atom pair A and B would be included in the pair list, even though the pair would initially be ignored because they are further apart than the cutoff distance. As the pair moved closer and entered the cutoff distance, because the pair was already in the pair list, the non-bonded interactions would immediately be calculated and energy conservation would be preserved. The value of pairlistdist should be chosen such that no atom pair moves more than pairlistdist$-$cutoff in one cycle. This will insure energy conservation and efficiency.

Figure 4: Depiction of the difference between the cutoff distance and the pair list distance. The pair list distance specifies a sphere that is slightly larger than that of the cutoff so that pairs are allowed to move in and out of the cutoff distance without causing energy conservation to be disturbed.

The pairlistdist parameter is also used to determine the minimum patch size. Unless the splitPatch parameter is explicitly set to position, hydrogen atoms will be placed on the same patch as the ``mother atom'' to which they are bonded. These hydrogen groups are then distance tested against each other using only a cutoff increased by the the value of the hgroupCutoff parameter. The size of the patches is also increased by this amount. NAMD functions correctly even if a hydrogen atom and its mother atom are separated by more than half of hgroupCutoff by breaking that group into its individual atoms for distance testing. Margin violation warning messages are printed if an atom moves outside of a safe zone surrounding the patch to which it is assigned, indicating that pairlistdist should be increased in order for forces to be calculated correctly and energy to be conserved.

Margin violations mean that atoms that are in non-neighboring patches may be closer than the cutoff distance apart. This may sometimes happen in constant pressure simulations when the cell shrinks (since the patch grid remains the same size). The workaround is to increase the margin parameter so that the simulation starts with fewer, larger patches. Restarting the simulation will also regenerate the patch grid.

In rare special circumstances atoms that are involved in bonded terms (bonds, angles, dihedrals, or impropers) or nonbonded exclusions (especially implicit exclusions due to bonds) will be placed on non-neighboring patches because they are more than the cutoff distance apart. This can result in the simulation dying with a message of ``bad global exclusion count''. If an ``atoms moving too fast; simulation has become unstable'', ``bad global exclusion count'', or similar error happens on the first timestep then there is likely something very wrong with the input coordinates, such as the atoms with uninitialized coordinates or different atom orders in the PSF and PDB file. Looking at the system in VMD will often reveal an abnormal structure. Be aware that the atom IDs in the ``Atoms moving too fast'' error message are 1-based, while VMD's atom indices are 0-based. If an ``atoms moving too fast; simulation has become unstable'', ``bad global exclusion count'', or similar error happens later in the simulation then the dynamics have probably become unstable, resulting in the system ``exploding'' apart. Energies printed at every timestep should show an exponential increase. This may be due to a timestep that is too long, or some other strange feature. Saving a trajectory of every step and working backwards in can also sometimes reveal the origin of the instability.

• pairlistdist $<$ distance between pairs for inclusion in pair lists (Å) $>$
  Acceptable Values: positive decimal $\geq$ cutoff
  Default Value: cutoff
  Description: A pair list is generated pairlistsPerCycle times each cycle, containing pairs of atoms for which electrostatics and van der Waals interactions will be calculated. This parameter is used when switching is set to on to specify the allowable distance between atoms for inclusion in the pair list. This parameter is equivalent to the X-PLOR parameter CUTNb. If no atom moves more than pairlistdist$-$ cutoff during one cycle, then there will be no jump in electrostatic or van der Waals energies when the next pair list is built. Since such a jump is unavoidable when truncation is used, this parameter may only be specified when switching is set to on. If this parameter is not specified and switching is set to on, the value of cutoff is used. A value of at least one greater than cutoff is recommended.

• stepspercycle $<$ timesteps per cycle $>$
  Acceptable Values: positive integer
  Default Value: 20
  Description: Number of timesteps in each cycle. Each cycle represents the number of timesteps between atom reassignments. For more details on non-bonded force evaluation, see Section 5.2.

• splitPatch $<$ how to assign atoms to patches $>$
  Acceptable Values: position or hydrogen
  Default Value: hydrogen
  Description: When set to hydrogen, hydrogen atoms are kept on the same patch as their parents, allowing faster distance checking and rigid bonds.

• hgroupCutoff (Å) $<$ used for group-based distance testing $>$
  Acceptable Values: positive decimal
  Default Value: 2.5
  Description: This should be set to twice the largest distance which will ever occur between a hydrogen atom and its mother. Warnings will be printed if this is not the case. This value is also added to the margin.

• margin $<$ extra length in patch dimension (Å) $>$
  Acceptable Values: positive decimal
  Default Value: 0.0
  Description: An internal tuning parameter used in determining the size of the cubes of space with which NAMD uses to partition the system. The value of this parameter will not change the physical results of the simulation. Unless you are very motivated to get the very best possible performance, just leave this value at the default.

• pairlistMinProcs $<$ min procs for pairlists $>$
  Acceptable Values: positive integer
  Default Value: 1
  Description: Pairlists may consume a large amount of memory as atom counts, densities, and cutoff distances increase. Since this data is distributed across processors it is normally only problematic for small processor counts. Set pairlistMinProcs to the smallest number of processors on which the simulation can fit into memory when pairlists are used.

• pairlistsPerCycle $<$ regenerate x times per cycle $>$
  Acceptable Values: positive integer
  Default Value: 2
  Description: Rather than only regenerating the pairlist at the beginning of a cycle, regenerate multiple times in order to better balance the costs of atom migration, pairlist generation, and larger pairlists.

• outputPairlists $<$ how often to print warnings $>$
  Acceptable Values: non-negative integer
  Default Value: 0
  Description: If an atom moves further than the pairlist tolerance during a simulation (initially (pairlistdist - cutoff)/2 but refined during the run) any pairlists covering that atom are invalidated and temporary pairlists are used until the next full pairlist regeneration. All interactions are calculated correctly, but efficiency may be degraded. Enabling outputPairlists will summarize these pairlist violation warnings periodically during the run.

• pairlistShrink $<$ tol *= (1 - x) on regeneration $>$
  Acceptable Values: non-negative decimal
  Default Value: 0.01
  Description: In order to maintain validity for the pairlist for an entire cycle, the pairlist tolerance (the distance an atom can move without causing the pairlist to be invalidated) is adjusted during the simulation. Every time pairlists are regenerated the tolerance is reduced by this fraction.

• pairlistGrow $<$ tol *= (1 + x) on trigger $>$
  Acceptable Values: non-negative decimal
  Default Value: 0.01
  Description: In order to maintain validity for the pairlist for an entire cycle, the pairlist tolerance (the distance an atom can move without causing the pairlist to be invalidated) is adjusted during the simulation. Every time an atom exceeds a trigger criterion that is some fraction of the tolerance distance, the tolerance is increased by this fraction.

• pairlistTrigger $<$ trigger is atom beyond (1 - x) * tol $>$
  Acceptable Values: non-negative decimal
  Default Value: 0.3
  Description: The goal of pairlist tolerance adjustment is to make pairlist invalidations rare while keeping the tolerance as small as possible for best performance. Rather than monitoring the (very rare) case where atoms actually move more than the tolerance distance, we reduce the trigger tolerance by this fraction. The tolerance is increased whenever the trigger tolerance is exceeded, as specified by pairlistGrow.