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:

.. math::

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

.. code-block:: bash

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


Arguments
---------

Required
--------

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

   TPR file containing system topology for the trajectory.

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

   Trajectory file containing coordinates to analyze.


Optional
--------

Index handling
~~~~~~~~~~~~~~

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

   Optional NDX file defining custom atom groups.

Selection
~~~~~~~~~

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

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

Time control
~~~~~~~~~~~~

.. option:: -b, --start-time INT  
.. option:: -e, --end-time INT  
.. option:: -dt, --delta-time INT

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

.. code-block:: python

   trajectory.time2frame(start, end, dt)

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

.. option:: -pbc, --treat-pbc

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

Output
~~~~~~

At least one of the following must be specified:

.. option:: -ov, --output-verbose FILE

   Write per-frame Rg for each selected group.

.. option:: -oa, --output-average FILE

   Write the **average Rg** over all groups per frame.

.. option:: -oh, --output-histogram FILE

   Write the **probability density distribution** of Rg values.

.. option:: -bw, --bin-width FLOAT

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


Algorithm Details
-----------------

(1) **Load trajectory**

.. code-block:: python

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

Handles exceptions if files cannot be read.

(2) **Determine frames**

.. code-block:: python

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

(3) **Group selection**

If ``--selection-calculate`` is provided:

.. code-block:: python

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

Else: open interactive selector:

.. code-block:: python

   selections, selection_names = trajectory.getSelection_interactive_multiple()

(4) **Optional PBC unwrap**

.. code-block:: python

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

(5) **Radius of gyration calculation**

Using:

.. code-block:: python

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

(6) **Outputs**

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

- x-axis: time (ns)  
- y-axis: Rg for each group

**Average Rg**

.. code-block:: python

   rg_matrix.mean(axis=0)

One averaged curve across groups.

**Histogram**

Computed from flattened Rg values:

.. code-block:: python

   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:

.. code-block:: bash

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

Write averaged Rg for whole system:

.. code-block:: bash

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

Write distribution only:

.. code-block:: bash

   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.