Modify residue

The modifyres tool adds residue-level chemical modifications to both:

  • an ITP topology file, and

  • a PDB structure file

by inserting new atoms, updating atom types, adding bonded interactions, and placing new atoms in 3D space based on physically meaningful geometric rules.

This tool add PTM by two-bead-per-residue forcefields. Use pdb2dps instead for one-bead-per-residue PTM.

This tool is used to generate post-translational modifications (PTMs) or custom residue variants (e.g., phosphorylation analogues, methylation types) inside DROPPS/CGPS simulations.

Implemented in modifyres.py.

Overview

dps modifyres performs the following operations:

  1. Select a forcefield containing definitions of modified residue types.

  2. Parse the input ITP and PDB files.

  3. Read user-specified modifications of the form:

    ORIGINAL + RESIDUE_NUMBER + MODIFIED
e.g.  S129SMP

  4. For each modified residue: - Replace the original backbone atom with a modified backbone atom type. - Append a new sidechain atom to represent the modification. - Add new bond(s) and angle(s) from forcefield parameters. - Generate new 3D coordinates for the added atom using geometric sampling.

  5. Write out: - a modified ITP file - a modified PDB file

Usage

Modify residue S129 → SMP and write new topology:

dps modifyres \
    -ip protein.itp \
    -if protein.pdb \
    -op protein_mod.itp \
    -of protein_mod.pdb \
    -ff hps \
    -m S129SMP

Multiple modifications:

dps modifyres -ip a.itp -if a.pdb -op out.itp -of out.pdb \
    -ff hps -m S129SMP T231TMP S42FOO

Arguments

Required

-ip, --input-topology FILE

Input ITP file representing the original topology.

-if, --input-structure FILE

Input PDB file with atomic coordinates.

-op, --output-topology FILE

Modified output topology (.itp extension auto-added if missing).

-of, --output-structure FILE

Modified output structure (.pdb extension auto-added if missing).

-m, --modifications ORIGINALNUMBERMODIFIED

One or more modifications, e.g:

S129SMP    (residue 129: original S → modified SMP)
Y39YMP     (tyrosine modification)

Optional

-ff, --forcefield NAME

Select forcefield from available *.ff files. If not provided, you will be prompted interactively.

Forcefield Handling

The tool searches for *.ff files in:

  1. dropps/share/forcefields/

  2. current working directory

If both directories contain the same filename, the program aborts:

ERROR: Conflict detected! The following .ff file(s) exist in both ...

Once a forcefield is selected:

forcefield = getff(parameter_file_path)

The following items are loaded per modification:

  • base residue mapping

  • atom type names

  • sigma/lambda parameters

  • charges

  • masses

  • bond lengths & force constants

  • angle definitions

Modification Format

A modification string must match:

([A-Za-z]+)(\d+)([A-Za-z]+)

Example:

  • S129SMP - original residue = S - index = 129 - modified type = SMP

Safety checks:

  • Terminal residues cannot be modified (current version).

  • Original residue name must match topology.

  • Modified residue name must exist in the forcefield.

ITP Topology Modifications

For each modified residue:

### 1. New atom types created

Two new atom types are appended:

  • XXXB — modified backbone

  • XXXS — modified sidechain

Example for SMP:

  • SMPB = new backbone type

  • SMPS = new sidechain type

These incorporate:

  • sigma

  • lambda

  • T0/T1/T2 (HPS parameters)

From forcefield definitions.

### 2. Atom replacement

Original atom at residue index i is replaced:

topology_new.atoms[i-1] = Atom(<modified B>, mass, charge)

### 3. New atom added

topology_new.atoms.append(Atom(<modified S>, mass, charge))

### 4. Bond added

Bond(i, new_atom_index, bond_length, bond_k)

### 5. Two angles added

Between:

  • (i-1) – i – new_atom

  • (i+1) – i – new_atom

PDB Structure Modifications

After modifying topology, the tool updates the structure.

### 1. New atom position generation

The function:

find_new_atom_position()

randomly samples 5000 directions on a sphere around the residue, looking for a point that:

  • is exactly the correct bond length from the modified backbone atom

  • maximizes the minimum distance from all other atoms

This avoids clashes and creates natural geometry.

### 2. Backbone atom name is replaced

structure_new[number-1]["name"] = <modified B>

### 3. New atom appended to structure list

With:

  • new coordinates

  • same residue name, chain, resseq

  • original occupancy, B-factor

  • atomic element

Output Files

Two final files are generated:

File | Description —- | ———– output.itp | Updated topology with new atom types, atoms, bonds, angles output.pdb | Updated coordinates including the new modified atom

Example printed logs:

## Modified original atom S129 to SMPB
## Added new atom 415 SMPS
## Add bond from 129 to 415.
## Add angle 128-129-415, theta=..., k=...
## Modify pdb: new atom is placed at (x,y,z)

Error Messages

Unrecognized residue

ERROR: Residue S not recognized in forcefield.

Unknown modified type

ERROR: Modified residue SMP not recognized in forcefield.

Terminal residues not allowed

ERROR: Cannot add modification to terminal residue.

Mismatch between PDB and ITP

ERROR: Length of topology and structure file not match.

Summary

dps modifyres allows automated addition of complex residue modifications by updating both topology and structure consistently. It supports:

  • forcefield-aware new atom types

  • proper bonded/angle interactions

  • physically sensible 3D atom placement

  • multi-residue modification

  • robust validation and error checking

This tool is essential for simulations involving PTMs (e.g., phosphorylations, mimics, methylations, acetylations) or custom coarse-grained residue variants.