Gyrate radius

The gyrate tool computes the radius of gyration (Rg) for one or more selected groups of atoms across a trajectory. It supports:

  • verbose (per-frame) Rg time series

  • time-averaged Rg curves

  • Rg histograms (PDF)

  • interactive or scripted selection of atom groups

  • optional PBC unwrapping

This analysis module is implemented in gyrate.py.

Overview

The radius of gyration is a global measure of polymer compactness, defined as:

\[R_g = \sqrt{ \frac{ \sum_i m_i \lVert \mathbf{r_i} - \mathbf{r}_{\mathrm{com}}\rVert^2 } { \sum_i m_i } }\]

dps gyrate performs the following steps:

  1. Load trajectory (TPR + XTC + optional NDX).

  2. Select groups (interactively or via --selection-calculate).

  3. Apply optional PBC unwrapping.

  4. Iterate over chosen frames.

  5. Compute Rg for each group.

  6. Output verbose time series, time-averaged values, and/or histograms.

Usage

dps gyrate -s run.tpr -f run.xtc -ov rg.xvg -sel 0 1 2

Arguments

Required

-s, --run-input TPR

TPR file containing system topology for the trajectory.

-f, --input XTC

Trajectory file containing coordinates to analyze.

Optional

Index handling

-n, --index NDX

Optional NDX file defining custom atom groups.

Selection

-sel, --selection-calculate INT INT ...

Specify multiple index groups to compute Rg for. If omitted, an interactive multi-group selector opens.

Time control

-b, --start-time INT
-e, --end-time INT
-dt, --delta-time INT

Select frames based on simulation time (ns). Frame indices are internally computed by:

trajectory.time2frame(start, end, dt)

PBC treatment

-pbc, --treat-pbc

Apply MDAnalysis unwrap transformation to make molecules whole before computing Rg.

Output

At least one of the following must be specified:

-ov, --output-verbose FILE

Write per-frame Rg for each selected group.

-oa, --output-average FILE

Write the average Rg over all groups per frame.

-oh, --output-histogram FILE

Write the probability density distribution of Rg values.

-bw, --bin-width FLOAT

Bin width (nm) for histogram. Default: 0.1.

Algorithm Details

  1. Load trajectory

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

Handles exceptions if files cannot be read.

  1. Determine frames

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

  1. Group selection

If --selection-calculate is provided:

selections = [trajectory.getSelection(f"group {gid}")[0] for gid in args.selection_calculate]

Else: open interactive selector:

selections, selection_names = trajectory.getSelection_interactive_multiple()

  1. Optional PBC unwrap

trajectory.Universe.trajectory.add_transformations(unwrap(trajectory.Universe.atoms))

  1. Radius of gyration calculation

Using:

rg = radius_of_gyration(positions, masses)

Where:

  • center of mass is mass-weighted

  • squared distances are weighted by masses

  • final result is converted to nm: rg / 10.0

  1. Outputs

Verbose Rg (per group, per time) Written as a matrix:

  • x-axis: time (ns)

  • y-axis: Rg for each group

Average Rg

rg_matrix.mean(axis=0)

One averaged curve across groups.

Histogram

Computed from flattened Rg values:

hist, bin_edges = np.histogram(rg_flatten, bins)
hist_pdf = hist / total / bin_width

Units: nm.

Example

Compute Rg for two groups, write time series:

dps gyrate \
    -s run.tpr \
    -f run.xtc \
    -n run.ndx \
    -sel 0 1 \
    -ov rg_timeseries.xvg

Write averaged Rg for whole system:

dps gyrate \
    -s run.tpr \
    -f run.xtc \
    -oa rg_avg.xvg \
    -sel 0

Write distribution only:

dps gyrate \
    -s run.tpr \
    -f run.xtc \
    -oh rg_hist.xvg \
    -bw 0.05

Error Messages

“ERROR: No output file specified.” You must request at least one of verbose/average/histogram outputs.

“An exception occurred when trying to open trajectory file …” TPR or XTC cannot be read.

Invalid selection Triggered if NDX group indices are invalid or empty.

Summary

dps gyrate provides:

  • per-chain or per-group Rg calculations

  • time-averaged compactness profiles

  • histogram distributions

  • optional PBC treatment

  • interactive multi-group selection

It is an essential tool for characterizing polymer compactness and condensate organization in LLPS simulations.