Add angle terms¶

The addangle tool adds angle potentials to a coarse-grained topology (.itp) file. It is typically used in DROPPS/CGPS workflows to impose secondary-structure constraints or intrinsic bending stiffness for polymer-like proteins.

The tool reads:

an input .itp file
an ASCII angle list describing which residues should receive angle terms
writes a new .itp file with the newly added angle interactions

This program is implemented in addangle.py.

Overview¶

dps addangle automates the process of inserting Angle entries into a GROMACS-style .itp file.

Operations performed:

Load input topology (.itp)
Read a user-provided angle list file
Ignore terminal residues
Convert residue-indexed atoms → atom indices used inside the ITP
Create angle terms:

\[V(\theta) = k(\theta - \theta_0)^2\]
Append angle terms to the existing topology
Write the updated .itp file to disk

Angle terms are added using dropps.fileio.itp_reader.Angle objects.

Usage¶

dps addangle \
    -ip input.itp \
    -op output.itp \
    -al angle_list.txt

Arguments¶

Required arguments¶

-ip, --input-topology FILE¶: Input topology file (must end with .itp).

-op, --output-topology FILE¶: Output topology file to write after adding angle terms. If extension is not .itp, the program appends .itp.

-al, --angle-list FILE¶

ASCII file containing:

residue_id   theta(deg)   k

where:

residue_id starts from 1, in residue numbering
angle is centered at residue residue_id → atoms (i−1, i, i+1)
theta is in degrees
k is in kJ/mol / deg²

Angle List Format¶

Each line (ignoring blank lines):

<center-residue>   <theta>   <k>

Example:

 120.0   25.0
 122.0   30.0
110.0   15.0

Program Workflow¶

Validate input ITP

if input_itp_name[-4:] != ".itp":
    ERROR

Load topology

topology = read_itp(input_itp_name)

This loads:

atoms
residues
any existing angles

Load and filter angle list

Blank lines are skipped.

Terminal residues are ignored automatically:

N-terminal: topology.atoms[0].residueid
C-terminal: topology.atoms[-1].residueid

Warnings are printed if the user attempts to add angles at terminal residues.

Residue → atom index conversion

Residue indices inside the ITP may not start at 1.

The tool computes shifted indices:

a1_id = (a2 - 1) - residue_NTD
a2_id = a2 - residue_NTD
a3_id = (a2 + 1) - residue_NTD

These become atom indices inside the angle list.

Angle creation

Uses the Angle class:

Angle(a1_id, a2_id, a3_id,
      theta_in_degree * degree,
      force * kilojoule_per_mole / degree**2)

Angle terms are appended to topology.angles.

Write output ITP

write_itp(output_itp_name, topology)

Final file is printed to the user.

Output File¶

The output .itp contains:

the original atom list
the original bond list
newly added angle terms appended to the [ angles ] section
values expressed in OpenMM/SI units converted correctly into GROMACS format

Example¶

Example angle list:

 120   35
 118   40
 130   20

Run:

dps addangle -ip protein.itp -op protein_with_angles.itp -al angles.txt

Program output:

## Input topology has been readed and loaded to memory.
## Frame contains 140 beads and angle list contains 3 entries.
## Adding angle to atoms 4-5-6 (resid: 4-5-6) at 120.0 degree with 35.0 kJ/mol/deg^2.
## Adding angle to atoms 5-6-7 (resid: 5-6-7) at 118.0 degree with 40.0 kJ/mol/deg^2.
## Adding angle to atoms 6-7-8 (resid: 6-7-8) at 130.0 degree with 20.0 kJ/mol/deg^2.
## Output topology file written to protein_with_angles.itp.

Error Messages¶

“ERROR: Input file X is not an itp file.” Only .itp files are accepted.

“An exception occurred when trying to open angle file …” Angle list cannot be opened.

Warnings: terminal residues ignored When user specifies angle at residue 1 or the last residue.

Other errors come directly from read_itp or write_itp.

Summary¶

dps addangle is a lightweight but powerful tool to append angle potentials to any .itp topology file. It is ideal for:

adding backbone stiffness in CG models
imposing secondary structure constraints
adjusting polymer bending rigidity
preparing enhanced coarse-grained simulation topologies

The tool integrates seamlessly with the DROPPS HPS/CGPS topology ecosystem.