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.

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().

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#