center_of_mass

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

Computes the center(s) of mass for a collection of particles.

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

\[\mathbf{R}_\mathrm{com}=\dfrac{\sum_{i=1}^N m_i \mathbf{r}_i}{\sum_{i=1}^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 center(s) of mass 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 center of mass, the array-like object holding the masses should be one-dimensional, while that containing the positions should be two-dimensional. To calculate center(s) of mass 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 centers of mass 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 center(s) of mass for. If not provided, the particle masses and posititions must be provided directly in masses and positions.

groupingstr, optional

Determines which center of mass is calculated if particle massses and positions are retrieved from group.

Valid values:

• None: Center of mass of all particles in group.

• "residues": Centers of mass for each residue in group.

• "segments": Centers of mass 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 center of mass,

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

• \((N_\mathrm{seg},\,N/N_\mathrm{seg}\) for the segment center(s) of mass, 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 center of mass,

• \((N_\mathrm{res},\,N/N_\mathrm{res},\,3)\) for the residue center(s) of mass, or

• \((N_\mathrm{seg},\,N/N_\mathrm{seg},\,3)\) for the segment center(s) of mass.

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{Å}\).

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.

rawbool, keyword-only, default: False

Determines whether particle masses and positions are returned if they were retrieved from group.

Returns:

comnumpy.ndarray

Center(s) of mass.

Shape:

• \((3,)\) for grouping=None.

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

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

massesnumpy.ndarray

Particle masses. Only returned if group was provided and contains equisized or identical groups, and raw=True.

Shape:

• \((N,)\) for grouping=None.

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

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

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

positionsnumpy.ndarray

Unwrapped particle positions. Only returned if group was provided and contains equisized or identical groups, and raw=True.

Shape:

• \((N,\,3)\) for grouping=None.

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

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

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