# 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.

```yaml
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.

```yaml
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](https://www.ks.uiuc.edu/Research/vmd/current/ug/node89.html)).
- **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":

```yaml
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

```yaml
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

```yaml
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](../how-to/use-positional-restraints.md#restrain-inside-a-slab-above-the-membrane). The authoritative lipid residue list is the constant `LIPIDSEL` in `acemd.protocols`, used by {py:func}`~acemd.protocols.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

- {py:func}`~acemd.protocols.get_cellular_restraints` — a helper that builds the extforces YAML for membrane-ligand simulations.
- [Use positional restraints](../how-to/use-positional-restraints.md) — recipe with full input files.