Make index
==========

The ``make_ndx`` tool creates and edits **index files (.ndx)** used throughout
DROPPS analysis modules.  
It provides an interactive environment—similar to GROMACS ``make_ndx``—allowing
you to list groups, create new groups, combine groups, select atoms by rules,
and finally save an ``.ndx`` file.

This tool is implemented in ``make_ndx.py``.


Overview
--------

Index files are a core part of the DROPPS analysis system, allowing the user to
define arbitrary groups of atoms, residues, or chains. These groups are used by
tools such as:

- ``cmap`` (contact maps)  
- ``gyrate`` (radius of gyration)  
- ``density`` (density profiles)  
- ``idist`` and ``odist`` (distance metrics)  
- any tool requiring chain-wise splitting (``splitch``)

``dps make_ndx`` provides:

1. Load topology directly from a **TPR** file  
2. Optionally load an existing **NDX** file  
3. Enter a fully interactive prompt for editing groups  
4. Use powerful commands from the ``indexGroups`` engine  
5. Save results to a new index file when the user quits


Usage
-----

.. code-block:: bash

   dps make_ndx -s run.tpr -o index.ndx

Load an existing file before editing:

.. code-block:: bash

   dps make_ndx -s run.tpr -n old.ndx -o new.ndx


Arguments
---------

.. option:: -s, --run-input TPR

   **Required.**  
   TPR file providing the topology, atom/residue information, and chain
   definitions.

.. option:: -n, --index NDX

   **Optional.**  
   Load an existing index file before entering the interactive session.

.. option:: -o, --output FILE

   **Required.**  
   Path to the output `.ndx` file that will be written when exiting.


Program Flow
------------

(1) **Read TPR file**

.. code-block:: python

   tpr = read_tpr(args.run_input)

If reading fails, the program prints:

::

   ERROR: Cannot open tpr file ...

and exits.

(2) **Initialize index engine**

.. code-block:: python

   index = indexGroups(tpr.mdtopology, tpr.itp_list)

This object provides:

- built-in groups  
- atom/residue/chain metadata  
- group combination engine  
- command processor  
- help menu  
- `.ndx` writer  

(3) **Load existing index (optional)**

.. code-block:: python

   index.load_ndx(args.index)

Errors result in:

::

   ERROR: Cannot open index file ...

(4) **Print initial groups**

The command:

.. code-block:: python

   index.command('p')

prints all current groups.

(5) **Interactive prompt**

A loop begins:

::

   > <your command>

Supported actions include:

- ``p`` — print all groups  
- ``q`` — write ndx & quit  
- ``a <expr>`` — select atoms by rule  
- ``r <expr>`` — select residues  
- ``chain <expr>`` — select chain(s)  
- ``name <pattern>`` — match atom names  
- Boolean operations:  
  - `|` union  
  - `&` intersection  
  - `!` complement  
- Numeric selection by group ID  
- Combining groups (`a 5 | 7`, `!4`, etc.)

All helpers are provided through:

.. code-block:: python

   index.showhelp()

(6) **Quit and save**

Typing ``q`` saves the final groups:

.. code-block:: python

   index.write_ndx(args.output)

and exits immediately.


Interactive Commands
--------------------

The indexing engine exposes powerful commands (actual commands depend on
``indexGroups``, but typical examples include):

Selecting atoms:

::

   a 1-100
   a name CA
   a resname GLY

Selecting residues:

::

   r 5-30

Chain operations:

::

   chain 0
   chain A B C

Set operations:

::

   3 | 5         # union  
   2 & !4        # intersection with complement  
   7 - 1         # difference  

Create new groups:

::

   name backbone
   a name N CA C O

Re-print groups:

::

   p


Example Session
---------------

Typical interactive workflow:

::

   $ dps make_ndx -s run.tpr -o mygroups.ndx
   ## Loading topology from run.tpr.
   Loading index entries from file None.
   > p
   0 System
   1 Protein
   2 Water
   ...

   > a name CA
   > a name CB
   > 10 | 11          # combine groups
   > p
   12 Combined_CA_CB

   > q
   ## Writing ndx to mygroups.ndx
   ## Finished.


Error Messages
--------------

**“ERROR: Cannot open tpr file …”**  
Given TPR file cannot be read.

**“ERROR: Cannot open index file …”**  
Existing index file specified by ``--index`` is invalid.

Other errors (invalid command syntax, unknown group, etc.) are printed by the
``indexGroups`` engine.


Summary
-------

``dps make_ndx`` is a compact yet powerful interactive tool for building index
files that feed into all analysis operations in the DROPPS ecosystem. Features:

- direct topology loading  
- optional merging with existing ndx files  
- robust expression engine for atom/residue/chain selection  
- full interactive editing environment  
- easy saving to a new index file

This tool is essential for preparing customized groups used by the DROPPS
analysis modules.