GSD file to xtc converter
=========================

The ``gsd2xtc`` tool converts **HOOMD GSD trajectory files** into **GROMACS XTC**
files. This is essential when moving from HOOMD-blue simulations to analysis
pipelines based on MDAnalysis, GROMACS tools, or the DROPPS ecosystem.

The converter performs:

- coordinate unit conversion (Å → nm or your internal units)  
- box vector scaling  
- insertion of artificial time stamps  
- frame-by-frame writing using the MDAnalysis XTC writer  

Implemented in ``gsd2xtc.py``.


Overview
--------

GSD trajectories often lack:

- **physical box dimensions**  
- **physical time information**  
- consistent **length units**  

``gsd2xtc`` resolves these inconsistencies by:

1. Loading the GSD file into an **MDAnalysis Universe**  
2. Scaling coordinates and box lengths by a factor of **10.0**  
   (i.e., converting internal units → nm)  
3. Assigning a time stamp to each frame based on the user-provided ``--time-step``  
4. Writing the modified frames into a compressed and portable **XTC trajectory**  

The output trajectory is immediately usable for DROPPS analysis scripts such as
``gyrate``, ``density``, ``contact_map``, ``idist``, ``odist``, and more.


Usage
-----

Basic conversion:

.. code-block:: bash

   dps gsd2xtc -f traj.gsd -o traj.xtc

Specify time-step (ns per frame):

.. code-block:: bash

   dps gsd2xtc -f traj.gsd -o out.xtc -ts 0.25


Arguments
---------

Required
--------

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

   Input GSD trajectory file.

Optional
--------

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

   Output XTC filename.  
   If omitted, extension will be corrected to ``.xtc`` by:

   .. code-block:: python

      output_filename = validate_extension(args.output, "xtc")

.. option:: -ts, --time-step FLOAT

   Time (in **ns**) assigned to each frame.  
   Default = ``0.1`` ns.

   Internal conversion:

   .. code-block:: python

      time_step = args.time_step * 1000   # stored in ps for MDAnalysis

   Each frame is time-stamped as:

   .. code-block:: python

      ts.time = time_step + i * time_step


Program Workflow
----------------


(1) **Load GSD trajectory**

.. code-block:: python

   u = mda.Universe(args.input)

If box vectors are all zeros:

::

   Warning: No PBC detected. Setting default PBC dimensions.

A cubic box is automatically inserted.

(2) **Determine output filename**

.. code-block:: python

   output_filename = validate_extension(args.output, "xtc")

(3) **Coordinate scaling**

The script multiplies all coordinates by:

.. code-block:: python

   factor = 10.0
   ts.positions *= factor

(4) **Box scaling**

Similarly:

.. code-block:: python

   ts.dimensions = [Lx*10, Ly*10, Lz*10, alpha, beta, gamma]

Angles remain unchanged.

(5) **Assign time stamps**

Using provided ``--time-step``:

.. code-block:: python

   ts.time = time_step + i * time_step

(6) **Write XTC file**

.. code-block:: python

   with XTC.XTCWriter(output_filename, n_atoms) as xtc_writer:
       xtc_writer.write(u)

Progress is shown using ``tqdm``.


Example
-------

Convert with default 0.1 ns per frame:

.. code-block:: bash

   dps gsd2xtc -f polymer.gsd -o polymer.xtc

Convert 100k-frame HOOMD trajectory with 0.02 ns spacing:

.. code-block:: bash

   dps gsd2xtc -f sim.gsd -o sim.xtc -ts 0.02


Output Details
--------------

The resulting XTC contains:

- properly scaled coordinates (nanometers)  
- properly scaled box vectors  
- sequential timestamps  
- compressed XTC format compatible with:

  - MDAnalysis  
  - GROMACS tools  
  - DROPPS analysis modules


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

Common issues include:

**GSD file cannot be opened**

::

   IOError loading Universe

**Invalid output filename**

Handled by ``validate_extension``.

**Zero box dimensions**

A warning appears and a default cubic box is applied.

**MDAnalysis XTC writer errors**

Occur if input positions become invalid; typically due to corrupted GSD input.


Summary
-------

``dps gsd2xtc`` is a lightweight but powerful converter that transforms HOOMD GSD
trajectories into standard GROMACS XTC files. Its main features include:

- automatic unit scaling  
- box reconstruction  
- time stamping  
- frame-by-frame conversion  
- compatibility with the full DROPPS analysis ecosystem

This tool is essential for workflows where HOOMD-blue simulations must be
analyzed alongside other MD engines or integrated into larger pipelines.