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: .. code-block:: bash dps modifyres \ -ip protein.itp \ -if protein.pdb \ -op protein_mod.itp \ -of protein_mod.pdb \ -ff hps \ -m S129SMP Multiple modifications: .. code-block:: bash dps modifyres -ip a.itp -if a.pdb -op out.itp -of out.pdb \ -ff hps -m S129SMP T231TMP S42FOO Arguments --------- Required -------- .. option:: -ip, --input-topology FILE Input ITP file representing the original topology. .. option:: -if, --input-structure FILE Input PDB file with atomic coordinates. .. option:: -op, --output-topology FILE Modified output topology (``.itp`` extension auto-added if missing). .. option:: -of, --output-structure FILE Modified output structure (``.pdb`` extension auto-added if missing). .. option:: -m, --modifications ORIGINALNUMBERMODIFIED One or more modifications, e.g: :: S129SMP (residue 129: original S → modified SMP) Y39YMP (tyrosine modification) Optional -------- .. option:: -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: .. code-block:: python 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: .. code-block:: python topology_new.atoms[i-1] = Atom(, mass, charge) ### 3. New atom added .. code-block:: python topology_new.atoms.append(Atom(, mass, charge)) ### 4. Bond added .. code-block:: python 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: .. code-block:: python 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 .. code-block:: python structure_new[number-1]["name"] = ### 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.