Extract frame
=============

The ``extract`` tool writes a **single frame** from a DROPPS trajectory into a
PDB file.  
You may select the frame either by **simulation time (ns)** or by **frame
index**, and optionally apply two different periodic-boundary–condition (PBC)
treatments.

This program is implemented in ``extract.py``.


Overview
--------

``dps extract`` performs:

1. Load TPR + XTC (+ optional NDX).  
2. Determine which frame to extract  
   - by time (ns)  
   - or by frame index  
3. Apply optional PBC treatment:  
   - make molecules whole  
   - or wrap atoms back into box  
4. Retrieve coordinates + box size  
5. Write frame to a PDB file with correct topology metadata.

This tool is useful for:

- extracting snapshots of LLPS systems  
- saving structures for visualization (VMD, PyMOL)  
- generating starting structures for new simulations  
- debugging trajectories and PBC behavior  


Usage
-----

.. code-block:: bash

   dps extract -s run.tpr -f run.xtc -o frame.pdb -t 100

or

.. code-block:: bash

   dps extract -s run.tpr -f run.xtc -o frame.pdb -fm 250


Arguments
---------

Required
--------

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

   TPR file containing topology and coordinates for the simulation.

.. option:: -f, --input XTC

   Trajectory file from which the frame will be extracted.

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

   Output PDB filename.  
   The extension is validated automatically.


Optional
--------

Index file
~~~~~~~~~~

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

   Optional NDX file for custom index groups.  
   (Not required unless selections are intended.)

Selection
~~~~~~~~~

.. option:: -sel, --selection INT INT ...

   Atom-group indices to extract.  
   If omitted, the *entire system* is written.

Frame specification
~~~~~~~~~~~~~~~~~~~

Exactly **one** of the following is required:

.. option:: -t, --time INT

   Simulation time (ns) of the frame to extract.

.. option:: -fm, --frame INT

   Frame index to extract.

PBC treatment
~~~~~~~~~~~~~

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

   Controls how periodic boundary conditions are applied:

   - ``mol`` (default): **make all molecules whole**  
     (no wrapping; preserves molecular connectivity)
   - ``atom``: **wrap each atom into the simulation box**

   In ``atom`` mode, coordinates are mapped using:

   .. code-block:: python

      coord % box_size

   for each axis.


Program Details
----------------

(1) **Trajectory loading**

.. code-block:: python

   trajectory = trajectory_class(tpr, ndx, xtc)

Handles errors gracefully:

::

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

(2) **Frame selection**

If neither ``--time`` nor ``--frame`` is provided:

::

   ERROR: No frame is specified.

If both are provided:

::

   ERROR: Only one of time and frame can be specified.

Frame index is determined via:

.. code-block:: python

   start_frame, _, _ = trajectory.time2frame(t, t, 0)

(3) **Coordinate extraction**

.. code-block:: python

   ts = trajectory.Universe.trajectory[start_frame]
   x, y, z = positions / 10.0

DROPPS converts:

- coordinates → nm  
- box vectors → nm

(4) **PBC treatment**

**mol mode**

::

   ## Molecules will be made whole.

**atom mode**

::

   ## Atoms will be put inside the simulation box.

Wrapping is done via:

.. code-block:: python

   coord % box_size

(5) **Write PDB**

The tool writes a proper PDB with:

- atom names  
- residue names  
- chain IDs  
- atom serial numbers  
- b-factors  
- occupancy  
- molecule lengths  

using:

.. code-block:: python

   write_pdb(output, box, names, serials, ...)


Example
-------

Extract the frame at 120 ns:

.. code-block:: bash

   dps extract \
       -s run.tpr \
       -f run.xtc \
       -o snap_120ns.pdb \
       -t 120

Extract the 50th frame and wrap atoms inside box:

.. code-block:: bash

   dps extract \
       -s run.tpr \
       -f run.xtc \
       -o snap50.pdb \
       -fm 50 \
       -pbc atom

Extract a specific residue group:

.. code-block:: bash

   dps extract \
       -s run.tpr \
       -f run.xtc \
       -n run.ndx \
       -sel 5 \
       -o chain5_frame20.pdb \
       -fm 20


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

**“ERROR: No frame is specified.”**  
You must provide either ``--time`` or ``--frame``.

**“ERROR: Only one of time and frame can be specified.”**  
Cannot use both options simultaneously.

**“An exception occurred when trying to open trajectory file”**  
TPR or XTC cannot be loaded (corrupt file, bad path).

**Output file errors**  
If PDB cannot be written (permissions, invalid path), the tool will stop.


Summary
-------

``dps extract`` provides a simple and robust method to extract PDB snapshots from
DROPPS HPS trajectories. It supports:

- time or frame-based extraction  
- atom-wise or molecule-wise PBC treatment  
- custom selection groups  
- fully formatted PDB output for visualization or further simulation  

It is an essential utility for trajectory inspection and structural analysis.