Check trajectory
================

``dps check`` is a diagnostic tool for verifying the integrity and compatibility
of simulation input files used by DROPPS.  
It validates the consistency between **TPR**, **XTC**, and **NDX** files, and
provides a convenient interactive interface for testing index group selection.

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


Overview
--------

``dps check`` performs the following actions:

1. Loads a DROPPS trajectory (TPR + XTC + optional NDX).  
2. Prints system information:  
   - number of atoms  
   - number of chains  
   - number of bonds  
   - number of frames  
   - time range of the trajectory  
3. Prints current index groups.  
4. Tests whether selections can be performed correctly.  
5. Enters an interactive index-selection mode.  

This tool is particularly useful for:

- debugging broken trajectory files  
- verifying correct topology merging  
- testing large multi-chain NDX files  
- resolving mismatches between ``.tpr`` and ``.xtc``  
- validating indexing before running analysis tools  


Usage
-----

.. code-block:: bash

   dps check -s run.tpr [-f run.xtc] [-n run.ndx]


Arguments
---------

Required
~~~~~~~~

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

   TPR file containing all system information (structure, topology, units,
   time-step mapping, chain organization, residue indices).


Optional
~~~~~~~~

.. option:: -f, --trajectory XTC

   Optional XTC file for checking trajectory integrity and time indexing.

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

   Optional NDX file defining index groups.  
   If omitted, DROPPS automatically constructs a default set of groups.


Program Behavior
----------------

The tool proceeds through the following steps.

1. **Trajectory loading**

   .. code-block:: python

      trajectory = trajectory_class(args.run_input, args.index, args.trajectory)

   This builds a unified trajectory object including:  
   - TPR-loaded topology  
   - XTC-loaded coordinates  
   - index groups (from file or auto-generated)

2. **Header information**

   The tool prints:

   - number of atoms: ``trajectory.num_atoms()``  
   - number of chains: ``trajectory.num_chains()``  
   - number of bonds: ``trajectory.num_bonds()``  
   - number of frames: ``trajectory.num_frames()``  

   Example output:

   ::

      #################### CHECKING ####################
      ## The system contains 5750 atoms in 125 chains.
      ## The system contains 5625 bonds.
      ## The trajectory contains 1001 frames.
      ## The time of the first, last frame is 0.0, 200.0 ns.
      ##################################################

3. **Index group inspection**

   .. code-block:: python

      len(trajectory.index.index_groups)
      trajectory.index.print_all()

   This reports how many index groups exist and prints their names/contents.

4. **Selection test**

   The program automatically attempts to select the first index group:

   .. code-block:: python

      trajectory.getSelection("group 0")

   This verifies that selection logic and indexing are consistent.

5. **Interactive mode**

   The program then enters a loop:

   .. code-block:: python

      while(True):
          trajectory.getSelection_interactive()

   This lets the user interactively type commands such as:

   - ``group 0``  
   - ``res 10``  
   - ``abbr ALA GLY PRO``  
   - ``chain A``  
   - ``splitch``  
   - ``q`` (quit)

   It is the recommended way to test indexing before running tools like
   ``contact``, ``idist``, or ``density``.


Example
-------

Check validity of a simulation system:

.. code-block:: bash

   dps check -s run.tpr -f run.xtc -n run.ndx

Typical output:

::

   #################### CHECKING ####################
   ## The system contains 4140 atoms in 100 chains.
   ## The system contains 4040 bonds.
   ## The trajectory contains 2000 frames.
   ## The time of the first, last frame is 0.0, 100.0 ns.
   ##################################################
   ## The initial system now contains 102 index groups.
   ## Trying to select the first index group...
   ## Ready for data analysis.
   #################### CHECKED  ####################
   [ Group_0 ]
   0 1 2 3 4 ...
   [ Group_1 ]
   ...
   >

At the prompt, users can test arbitrary selector commands.


Typical Use Cases
-----------------

- **Verify file compatibility**  
  Ensure TPR/XTC/NDX match in chain count and residue numbering.

- **Inspect index groups**  
  Useful for multichain LLPS simulations with hundreds of chains.

- **Debug analysis errors**  
  If `contact`, `density`, or `angle` fail due to mismatched indexing.

- **Load trajectory without running analysis**  
  Quickly inspect frames, system size, or trajectory range.

- **Validate newly created NDX files**  
  Especially those generated by ``splitch`` or custom scripts.


Error Handling
--------------

Common issues detected by ``dps check``:

**TPR and XTC mismatch**

- wrong number of atoms  
- different unit cell  
- different chain count

**Invalid NDX file**

- refers to atoms not present in TPR  
- groups with inconsistent chain organization  
- duplicate or malformed groups

**Trajectory load failure**

- truncated XTC file  
- missing frame time stamps  
- corrupted coordinates


Summary
-------

``dps check`` is the recommended tool for validating simulation file integrity
before running any analysis tasks.  
It ensures:

- correct indexing  
- correct TPR–XTC matching  
- stable trajectory loading  
- working selections  
- compatibility with all other analysis modules  

Its interactive interface makes it ideal for debugging complex multichain LLPS
systems.