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

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

Arguments

Required

-s, --run-input TPR

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

Optional

-f, --trajectory XTC

Optional XTC file for checking trajectory integrity and time indexing.

-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

    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

    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:

    trajectory.getSelection("group 0")

    This verifies that selection logic and indexing are consistent.

  5. Interactive mode

    The program then enters a loop:

    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:

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.