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:

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

   .. math::

      V(\theta) = k(\theta - \theta_0)^2

6. Append angle terms to the existing topology  
7. Write the updated ``.itp`` file to disk

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


Usage
-----

.. code-block:: bash

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


Arguments
---------

Required arguments
~~~~~~~~~~~~~~~~~~

.. option:: -ip, --input-topology FILE

   Input topology file (must end with ``.itp``).

.. option:: -op, --output-topology FILE

   Output topology file to write after adding angle terms.  
   If extension is not ``.itp``, the program appends ``.itp``.

.. option:: -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:

::

    45   120.0   25.0
    46   122.0   30.0
    100  110.0   15.0


Program Workflow
----------------

(1) **Validate input ITP**

.. code-block:: python

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

(2) **Load topology**

.. code-block:: python

   topology = read_itp(input_itp_name)

This loads:

- atoms  
- residues  
- any existing angles  

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

(4) **Residue → atom index conversion**

Residue indices inside the ITP may not start at 1.

The tool computes shifted indices:

.. code-block:: python

   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.

(5) **Angle creation**

Uses the ``Angle`` class:

.. code-block:: python

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

Angle terms are appended to ``topology.angles``.

(6) **Write output ITP**

.. code-block:: python

   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:

::

   5   120   35
   6   118   40
   7   130   20

Run:

.. code-block:: bash

   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.