radius_of_gyration

mdhelper.algorithm.molecule.radius_of_gyration(group: AtomGroup = None, grouping: str = None, *, positions: list[tuple[tuple[float]]] | ndarray[float] = None, masses: list[tuple[float]] | ndarray[float] = None, com: ndarray[float] = None, images: ndarray[int] = None, dimensions: ndarray[float] = None, n_groups: int = None, components: bool = False) → float | ndarray[float]

Computes the radii of gyration for a collection of particles.

For a group with \(N\) particles with masses \(m_i\) and positions \(\mathbf{r}_i\), the radius of gyration is defined as

\[R_\mathrm{g}=\sqrt{ \frac{\sum_i^N m_i\|\mathbf{r}_i-\mathbf{R}_\mathrm{com}\|^2} {\sum_i^N m_i}}\]

where \(\mathbf{R}_\mathrm{com}\) is the center of mass.

Alternatively, the radii of gyration around the coordinate axes can be calculated by only summing the radii components orthogonal to each axis. For example, the radius of gyration around the \(x\)-axis is

\[R_{\mathrm{g},x}=\sqrt{ \frac{\sum_i^N m_i[(\mathbf{r}_{i,y}-\mathbf{R}_{\mathrm{com},y})^2 +(\mathbf{r}_{i,z}-\mathbf{R}_{\mathrm{com},z})^2]}{\sum_i^N m_i}}\]

Note

This function supports a wide variety of inputs, depending on how the particle information is provided and what should be calculated.

When an MDAnalysis.core.groups.AtomGroup object is provided, the particle masses and positions are extracted from it. If the AtomGroup abides by the standard topological heirarchy, you can specify the desired grouping and the appropriate radii of gyration will be calculated. Otherwise, if and only if the AtomGroup contains equisized or identical groups corresponding to the desired grouping (i.e., the AtomGroup has particles that are or can be treated as nonbonded entities or topological groups with the same number of but not necessarily identical constituents), you can provide the total number of groups and the particle masses and positions will be distributed accordingly. If the AtomGroup does not have the correct structural information and the residues or segments do not contain the same number of atoms, see the second-to-last paragraph.

If the trajectory is not unwrapped, the number of periodic boundary crossings (and optionally, the system dimensions if they are not embedded in the AtomGroup) can be provided.

Alternatively, the unwrapped particle masses and positions can be provided directly as a numpy.ndarray, list, or tuple. To calculate the overall radius of gyration, the array-like object holding the masses should be one-dimensional, while that containing the positions should be two-dimensional. To calculate radii of gyration for group(s), the array-like object holding the masses should be two-dimensional (order: group, particle mass), while that containing the positions should be three-dimensional (order: group, particle position, axis). When a list or tuple is used, the inner arrays do not have to be homogeneously shaped, thus allowing you to calculate the radii of gyration for residues or segments with different numbers of atoms.

You may also provide only one of the particle masses or positions, in which case the missing information will be retrieved from the AtomGroup. This is generally not recommended since the shapes of the provided and retrieved arrays may be incompatible.

Parameters:

groupMDAnalysis.AtomGroup, optional

Collection of atoms to compute the radii of gyration for. If not provided, the particle masses and posititions must be provided directly in masses and positions.

groupingstr, optional

Determines which radius of gyration is calculated if particle massses and positions are retrieved from group.

Valid values:

• None: Radius of gyration of all particles in group.

• "residues": Radius of gyration for each residue in group.

• "segments": Radius of gyration for each chain in group.

massesarray-like, keyword-only, optional

Particle masses.

Shape:

The general shape is \((N,)\).

For equisized or identical groups,

• \((N,)\) for the overall radius of gyration,

• \((N_\mathrm{res},\,N/N_\mathrm{res})\) for the residue radii of gyration, where \(N_\mathrm{res}\) is the number of residues, or

• \((N_\mathrm{seg},\,N/N_\mathrm{seg}\) for the segment radii of gyration, where \(N_\mathrm{seg}\) is the number of segments.

For groups with different numbers of atoms, the array-like object should contain inner lists or tuples holding the masses of the particles in each group.

Reference unit: \(\mathrm{g/mol}\).

positionsarray-like, keyword-only, optional

Unwrapped particle positions.

Shape:

The general shape is \((N,\,3)\).

For equisized or identical groups,

• \((N,\,3)\) for the overall radius of gyration,

• \((N_\mathrm{res},\,N/N_\mathrm{res},\,3)\) for the residue radii of gyration, or

• \((N_\mathrm{seg},\,N/N_\mathrm{seg},\,3)\) for the segment radii of gyration.

For groups with different numbers of atoms, the array-like object should contain inner lists or tuples holding the coordinates of the particles in each group.

Reference unit: \(\mathrm{Å}\).

comnumpy.ndarray, keyword-only, optional

Center(s) of mass.

Shape:

• \((3,)\) for the overall radius of gyration.

• \((N_\mathrm{res},\,3)\) for the residue radii of gyration.

• \((N_\mathrm{seg},\,3)\) for the segment radii of gyration.

imagesnumpy.ndarray, keyword-only, optional

Image flags for the particles in group. Must be provided for correct results if particle positions are wrapped.

Shape: \((N,\,3)\).

dimensionsnumpy.ndarray, keyword-only, optional

System dimensions. Must be provided if images is provided and group does not contain the system dimensions.

Shape: \((3,)\).

Reference unit: \(\mathrm{Å}\).

n_groupsint, keyword-only, optional

Number of residues or segments. Must be provided if group has an irregular topological heirarchy or the masses and positions arrays have the generic shapes.

componentsbool, keyword-only, default: False

Specifies whether the components of the radii of gyration are calculated and returned instead.

Returns:

gyradiifloat or numpy.ndarray

Radii of gyration.

Shape:

• Scalar for grouping=None.

• \((N_\mathrm{res},)\) for grouping="residues".

• \((N_\mathrm{seg},)\) for grouping="segments".

Reference unit: \(\mathrm{Å}\).