External forces#

External forces are specified under the top-level extforces key of the input file as a list. Each entry has a type and a set of type-specific options.

extforces:
  - type: <restraint type>
    # ...type-specific options...

Currently supported types: positionalRestraint, intermolecularRepulsion.

Positional restraints#

positionalRestraint applies a harmonic (or flat-bottom) restraint that pulls selected atoms toward a reference position.

extforces:
  - type: positionalRestraint
    sel: null                  # required
    axes: "xyz"
    fbWidth: [0, 0, 0]
    fbCenter: null
    fbCenterOffset: [0, 0, 0]
    setPoints:                 # required
      - k@time

sel#

  • Type: atom selection (VMD-style).

  • Default: none. Required.

Atoms the restraint applies to. Exclude hydrogens (e.g. via noh) when timestep > 2 fs, because constrained hydrogens can otherwise produce NaN coordinates when restrained.

axes#

  • Values: any concatenation of x, y, z, with optional +/- prefix.

  • Default: "xyz".

Axes along which the restraint acts. A +/- prefix activates the restraint only when the atom moves in that direction from its reference position; motion in the opposite direction is unrestrained. With "+z", the atom is pulled back if it moves in +z, but free to move in -z. With "-z", the opposite: free to move in +z, blocked in -z.

fbWidth#

  • Type: list of 3 non-negative numbers, or a single number applied to all axes.

  • Default: [0, 0, 0].

Width of the flat-bottom potential, in Å.

  • fbWidth = 0 (the default): pure harmonic restraint to each atom’s reference position.

  • fbWidth > 0, fbCenter = null: each atom is restrained inside a box of size fbWidth centred on its own reference position.

  • fbWidth > 0, fbCenter set: all atoms in sel are restrained inside a single shared box of size fbWidth centred on fbCenter.

fbCenter#

  • Type: atom-selection string.

  • Default: none.

Centre of the flat-bottom box. The centre of mass of the matching atoms defines a (potentially moving) centre that the box tracks throughout the simulation.

fbCenterOffset#

  • Type: list of 3 real numbers (Å).

  • Default: [0, 0, 0].

Offset applied to fbCenter. Useful for restraining a ligand “10 Å above the membrane COM”:

fbcenter: "(lipid or resname AR CHL DHA ...) and noh"
fbcenteroffset: [0, 0, 10]

setPoints#

  • Type: list of "k@time" strings.

  • Default: []. Required.

Force constant in kcal/mol/Ų as a function of time. The force constant is linearly interpolated between successive set-points.

  • If no set-point is given for time 0, the restraint starts at k = 0 and ramps to the first set-point.

  • If no set-point is given for the last simulation step, the last force constant carries through to the end.

Time suffixes: us, ns, ps, fs. Without a suffix the value is interpreted as a step count.

Examples#

Slowly remove a CA restraint over 100 ns#

extforces:
  - type: positionalRestraint
    sel: "protein and name CA"
    axes: "xyz"
    setpoints:
      - 1@0ns
      - 0@100ns

Keep a ligand within 10 Å of a protein’s CA centre of mass#

extforces:
  - type: positionalRestraint
    sel: "resname MOL"
    axes: "xyz"
    fbwidth: 10
    fbcenter: "protein and name CA"
    setpoints:
      - 0.5@0

Keep ligands inside a 20 Å slab above a membrane#

See the worked recipe in Use positional restraints: restrain inside a slab above the membrane. The authoritative lipid residue list is the constant LIPIDSEL in acemd.protocols, used by get_cellular_restraints().

Intermolecular repulsion#

intermolecularRepulsion applies a purely repulsive potential between distinct molecules of a selection, leaving their interactions with everything else untouched. Use it to stop many copies of a molecule aggregating with each other: cosolvent probes that should sample a protein surface rather than clump together, ligand copies in a multi-copy binding run, ions that should not pair.

extforces:
  - type: intermolecularRepulsion
    sel: null                  # required
    sel2: null
    sigma: null                # required
    epsilon: null              # required

The potential is the Weeks-Chandler-Andersen form: a Lennard-Jones potential truncated at its minimum and shifted to zero there, which removes all attraction and leaves only the repulsive core.

U(r) = 4*epsilon*[(sigma/r)^12 - (sigma/r)^6] + epsilon    for r <  2^(1/6)*sigma
U(r) = 0                                                   for r >= 2^(1/6)*sigma

Pairs of atoms within the same molecule are excluded, so the force never fights the force field’s own bonded terms. Molecules are identified by bonded connectivity rather than by residue, so a cosolvent built from several residues counts as one molecule.

sel#

  • Type: atom selection (VMD-style).

  • Default: none. Required.

Atoms the repulsion applies to. With sel2 unset, molecules within sel are repelled from each other.

sel2#

  • Type: atom selection.

  • Default: none.

When set, the repulsion acts between sel and sel2 instead of within sel. The same-molecule exclusion still applies, so overlapping selections (sel: "name CA" against sel2: "name CB") cannot push a single molecule apart.

sigma#

  • Type: positive number (Å).

  • Default: none. Required.

Effective exclusion radius per selected atom. It also sets the range of the force, because the potential is exactly zero beyond 2^(1/6) * sigma, so sigma: 5 gives a reach of 5.61 Å.

sigma is normally chosen far larger than any atomic Lennard-Jones σ. Each selected atom becomes a broad soft sphere, so whole molecules repel as blobs rather than atom by atom; this coarseness is deliberate, since what is wanted is a molecular exclusion volume. Raise sigma to make molecules keep further apart.

epsilon#

  • Type: non-negative number (kcal/mol).

  • Default: none. Required.

Energy scale of the repulsion. At r = sigma the potential is exactly epsilon, which makes it a convenient handle on the barrier height: well above kT (≈0.6 kcal/mol at 300 K) makes overlap effectively forbidden, below it merely discourages it.

Examples#

Keep cosolvent fragments from clumping#

extforces:
  - type: intermolecularRepulsion
    sel: "resname XYZ"
    sigma: 5.0
    epsilon: 0.024

Every XYZ molecule is pushed away from every other XYZ molecule within 5.61 Å, while its interactions with the protein and the solvent stay exactly as the force field defines them.

Keep a ligand out of the membrane#

extforces:
  - type: intermolecularRepulsion
    sel: "resname MOL"
    sel2: "lipid"
    sigma: 6.0
    epsilon: 0.5

Reference coordinates (fbRefCoor)#

fbRefCoor is a top-level input-file option (not part of extforces), but it changes how positional restraints behave.

  • Type: path to a PDB file.

  • Default: none.

When set, atom reference positions for positionalRestraint are read from this PDB file instead of from the simulation’s starting coordinates. The atoms in the PDB must match the simulation system (same atom order).

See also#