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:

Load TPR + XTC (+ optional NDX).
Determine which frame to extract - by time (ns) - or by frame index
Apply optional PBC treatment: - make molecules whole - or wrap atoms back into box
Retrieve coordinates + box size
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¶

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

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

Arguments¶

Required¶

-s, --run-input TPR¶: TPR file containing topology and coordinates for the simulation.

-f, --input XTC¶: Trajectory file from which the frame will be extracted.

-o, --output FILE¶: Output PDB filename. The extension is validated automatically.

Optional¶

Index file¶

-n, --index NDX¶: Optional NDX file for custom index groups. (Not required unless selections are intended.)

Selection¶

-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:

-t, --time INT¶: Simulation time (ns) of the frame to extract.

-fm, --frame INT¶: Frame index to extract.

PBC treatment¶

-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:

coord % box_size

for each axis.

Program Details¶

Trajectory loading

trajectory = trajectory_class(tpr, ndx, xtc)

Handles errors gracefully:

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

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:

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

Coordinate extraction

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

DROPPS converts:

coordinates → nm
box vectors → nm

PBC treatment

mol mode

## Molecules will be made whole.

atom mode

## Atoms will be put inside the simulation box.

Wrapping is done via:

coord % box_size

Write PDB

The tool writes a proper PDB with:

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

using:

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

Example¶

Extract the frame at 120 ns:

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

Extract the 50th frame and wrap atoms inside box:

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

Extract a specific residue group:

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.