Index File (NDX)
================

The **NDX file** stores *index groups* for selections used in simulation and
analysis.  
It follows the **GROMACS `.ndx` format**, and is fully compatible with the
DROPPS toolchain, including:

- ``dps make_ndx`` 
- all analysis programs (``contact``, ``density``, ``gyrate``, ``cmap``)  
- internal API selection mechanisms in the trajectory wrapper  


Purpose of the NDX File
-----------------------

An NDX file provides **named groups of atoms**, e.g.:

- single residues  
- contiguous blocks of residues  
- individual chains  
- selections such as “all hydrophobic residues”  
- custom combinations of chains/residues  

Because LLPS systems typically contain **hundreds or thousands of chains**,  
DROPPS includes **special indexing commands** optimized for very large systems,
such as:

- ``splitch`` — split into chain-wise groups  
- ``abbr`` — select by residue abbreviation  
- ``res`` — select by residue number  
- ``chain`` — select using chain IDs  
- ``index`` — fetch atoms by ID index  


NDX File Format
---------------

NDX files use a simple block structure:

.. code-block:: text

   [ groupname ]
   0   1   2   3   4   5   6

Each group contains one or more integer atom indices.

**Important characteristics:**

- Indices are **0-based** or **1-based**, depending on how they were constructed.  
  DROPPS accepts both and normalizes internally.
- Groups may contain **arbitrary atom selections**.
- There is no limit on group count.
- Whitespace and line breaks do not matter.

Example groups:

.. code-block:: text

   [ System ]
   0 1 2 3 4 5 6 7 8 9

   [ Chain_A ]
   0 1 2 3 4

   [ Chain_B ]
   5 6 7 8 9


Generating NDX Files
--------------------

To generate a new index file, use:

.. code-block:: bash

   dps make_ndx -f run.tpr -o run.ndx

DROPPS's index builder is strongly GROMACS-inspired but includes extra commands
ideal for LLPS workflows.


### Interactive Commands

When the command launches, you can type:

- ``res <num>`` — select a specific residue  
- ``abbr ALA PRO GLY`` — select residues by abbreviation  
- ``chain A B C`` — select atom groups by chain ID  
- ``index 10 11 12`` — manually select atom indices  
- ``name foo bar`` — rename a group  
- ``q`` — quit and save  
- **``splitch``** — SPECIAL LLPS COMMAND  
  Splits the entire system into **chain-by-chain groups**, automatically.  
  This is essential for analyzing inter-chain and intra-chain interactions.


Example session:

.. code-block:: text

   > splitch
   Created 125 chain groups.
   > name 0 Chain_000
   > name 1 Chain_001
   > q


Using NDX Files in Analysis
---------------------------

Most DROPPS analysis tools accept the ``-n`` flag:

.. code-block:: bash

   dps contact -s run.tpr -f run.xtc -n run.ndx -o contact.xvg

CHAIN GROUPS ARE IMPORTANT  
--------------------------

LLPS systems often contain many chains (e.g., 100–1000).  
The PDF highlights that GROMACS-style selection is too slow for these systems,
so DROPPS introduces:

### ✔ ``splitch`` — automatic chain splitting  
### ✔ residue-wise abbreviation selection  
### ✔ optimized indexing for multichain LLPS  

The resulting NDX groups integrate seamlessly with the custom trajectory API.


Inspecting and Editing NDX Files
--------------------------------

NDX files are plain-text and can be edited manually:

.. code-block:: text

   [ Group_1 ]
   0 1 2 3 4 5

   [ Group_2 ]
   6 7 8 9

You may rename groups or adjust membership before running analysis programs.


When You Need Custom NDX Files
------------------------------

You will need custom NDX files when:

- computing **intra-chain vs inter-chain** contact maps  
- analyzing **specific chain–chain pairs**  
- defining **protein vs solvent** regions (if solvent is used)  
- coarse-graining complex modular sequences  
- performing **per-chain density** or **per-residue** analysis  

Custom groups ensure precise and efficient analysis, especially for large
multichain condensates.


Summary
-------

The NDX file is an essential component of the DROPPS workflow:

- defines named atom groups  
- used for selections in analysis  
- fully compatible with GROMACS NDX syntax  
- extends functionality via LLPS-optimized commands (``splitch``)  
- integrates with the trajectory object for high-performance selection  

NDX files ensure flexible and reproducible analysis across large CG LLPS
systems.