Trajectory converter
====================

The ``trjconv`` tool reads an existing trajectory and converts, extracts, or
rewrites it with options for:

- frame selection (start / end / interval),
- atom/molecule-based PBC treatment,
- atom-group selection for output,
- output format conversion (XTC ↔ PDB),
- index-group based workflow.

It is the DROPPS/CGPS equivalent of *GROMACS trjconv*, using MDAnalysis as the
transformation engine.

Implemented in ``trjconv.py``.


Overview
--------

``dps trjconv`` performs:

1. Load a complete simulation using:
   - a DROPPS TPR file (runtime information),
   - a trajectory file (XTC),
   - an index file (optional).

2. Convert **time → frame indices** using the metadata stored in the TPR.

3. Apply **MDAnalysis coordinate transformations**:
   - atom-level wrapping
   - molecule-level wrapping + unwrapping

4. Interactively select **atom groups** for PBC treatment and for output.

5. Write output to:
   - ``.xtc`` for compressed trajectory,
   - ``.pdb`` for coordinate snapshots.

Output frames follow the user-defined slicing in time.


Usage
-----

Basic conversion:

.. code-block:: bash

   dps trjconv -s run.tpr -f traj.xtc -o out.xtc -pbc none

Extract every 10 ns:

.. code-block:: bash

   dps trjconv -s run.tpr -f traj.xtc -o slim.xtc \
       -b 0 -e 200 -dt 10 -pbc atom


Arguments
---------

Required
--------

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

   DROPPS ``.tpr`` runtime file (produced by ``dps grompp``).  
   Provides metadata: box, MD parameters, time-step, etc.

.. option:: -f, --input FILE

   Input trajectory (XTC).

.. option:: -pbc {none, atom, mol}

   Algorithm for treating periodic boundary conditions:

   - ``none`` — no correction  
   - ``atom`` — wrap each atom independently  
   - ``mol`` — wrap + unwrap a molecule as a whole  

Optional
--------

.. option:: -n, --index FILE

   Optional index file containing custom groups.

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

   Output trajectory file.  
   Allowed extensions:
   - ``.xtc``  
   - ``.pdb``  

   Any other extension triggers:

   ::

      ERROR: Cannot write trajectory with extention ...

.. option:: -b, --start-time INT

   First frame to write, specified in **nanoseconds**.

.. option:: -e, --end-time INT

   Last frame to write, also in **ns**.

.. option:: -dt, --delta-time INT

   Interval between frames, in **ns**.


Interactive Selections
----------------------

``trjconv`` uses DROPPS' interactive index-group system:

### 1. PBC selection (if pbc ≠ none)

Triggered by:

.. code-block:: python

   selection_wrap, _ = trajectory.getSelection_interactive()

Depending on ``--pbc``:

- ``atom`` → apply wrapping  
- ``mol`` → apply wrapping + unwrapping

The actual transformations:

.. code-block:: python

   transformations.wrap(selection)
   transformations.unwrap(selection)

are then registered on the trajectory.

### 2. Output-group selection

Before writing output, the user selects the set of atoms to write:

.. code-block:: python

   selection_output, selection_output_name = \
       trajectory.getSelection_interactive("Group for output …")


Frame Selection
---------------

The time-to-frame mapping is handled by:

.. code-block:: python

   start_frame, end_frame, interval_frame = \
       trajectory.time2frame(b, e, dt)

Time is interpreted in **ns**, matching the MDP parameters.


Workflow
--------

Complete workflow from the implementation 

### 1. Load trajectory

.. code-block:: python

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

Failure produces:

::

   ## An exception occurred when trying to open trajectory file ...

### 2. Time slicing → frame slicing

.. code-block:: python

   start_frame, end_frame, interval = trajectory.time2frame()

### 3. Apply PBC transformations

For example, in molecule mode:

.. code-block:: python

   workflow = [wrap(selection), unwrap(selection)]
   trajectory.Universe.trajectory.add_transformations(*workflow)

### 4. Determine output format

.. code-block:: python

   file_ext = splitext(args.output)[1].lower()

Allowed: ``.pdb`` or ``.xtc``.

### 5. Select atoms for output

User chooses group interactively.

### 6. Write trajectory

.. code-block:: python

   with Writer(output_trajectory, n_atoms) as writer:
       for ts in Universe.trajectory[start:end:step]:
           writer.write(selection_output)

REPORT:

::

   ## Trajectory written to file out.xtc


Output Formats
--------------

### XTC Output

- compressed, fast, portable  
- one frame per time slice  
- positions only  

### PDB Output

- writes one frame per snapshot  
- good for visualization or testing  
- may generate multiple MODEL records automatically (depends on MDAnalysis writer)


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

**Unknown extension**

::

   ERROR: Cannot write trajectory to file.ext

**Trajectory load failed**

Usually indicates a missing or corrupted XTC file.

**Interactive selection cancelled**

User aborted interactive group selection (current behavior is to exit silently).


Summary
-------

``dps trjconv`` is a versatile, MDAnalysis-powered converter for DROPPS
trajectories. It enables:

- PBC wrapping/unwrap on atom or molecule groups  
- extraction of time windows  
- interpolation-free slicing (exact frame stepping)  
- interactive group-based selections  
- export of cleaned, wrapped, or trimmed trajectories  

It plays the same role in DROPPS as ``trjconv`` does in GROMACS, and is widely
used before analysis (density, gyration, ID/OD distributions, contact maps).