wcenter

mdtools.structure.wcenter(ag, weights=None, pbc=False, cmp='group', make_whole=False, debug=False)[source]

Calculate the weighted center of (compounds of) an MDAnalysis AtomGroup.

Parameters:

ag (MDAnalysis.core.groups.AtomGroup) – The MDAnalysis AtomGroup for which to calculate the weighted center.
weights (array_like or None, optional) – Weights to be used, given as a 1d array containing the weights for each Atom in ag. Weights are mapped to Atoms by the order they appear in ag. Setting weights to None is equivalent to passing identical weights for all Atoms in ag and therefore this is equivalent to calculating the center of geometry. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will be nan.
pbc (bool, optional) – If True and cmp is 'group', move all Atoms in ag to the primary unit cell before calculating the weighted center. If True and cmp is not 'group', the weighted center of each compound will be calculated without moving any Atoms to keep the compounds intact (if they were intact before). Instead, the resulting position vectors will be moved to the primary unit cell after calculating the weighted center.
cmp ({'group', 'segments', 'residues', 'molecules', 'fragments', 'atoms'}, optional) – The compounds of ag for which to calculate the weighted center. If 'group', the weighted center of all Atoms in ag will be returned as a single position vector. If 'atoms', simply the positions of all atoms in ag will be returned (2d array). Else, the weighted center of each Segment, Residue, molecule, or fragment contained in ag will be returned as an array of position vectors, i.e. a 2d array. Refer to the MDAnalysis’ user guide for an explanation of these terms. Note that in any case, also if cmp is e.g. 'residues', only the Atoms belonging to ag are taken into account, even if the compound might comprise additional Atoms that are not contained in ag.
make_whole (bool, optional) – If True, compounds whose bonds are split across periodic boundaries are made whole before calculating their center. Note that all Atoms in ag are wrapped back into the primary unit cell before making compounds whole to ensure that the algorithm is working properly. This means that making compounds whole in an unwrapped trajectory will lead to a wrapped trajectory with whole compounds (some Atoms may lie outside the primary unit cell, but each compound’s center will lie inside the primary unit cell). Note that make_whole has no effect if cmp is set to 'atoms'.
debug (bool, optional) – If True, run in debug mode.

Returns:

centers (numpy.ndarray) – Position of the weighted center of each compound in ag. If cmp was set to 'group', the output will be a single position vector of shape (3,). Else, the output will be a 2d array of shape (n, 3) where n is the number of compounds in ag.

Raises:

RuntimeWarning : – If debug is True and the weighted center of any compound is nan.

See also

MDAnalysis.core.groups.AtomGroup.center(): Weighted center of (compounds of) the group
MDAnalysis.core.groups.AtomGroup.center_of_geometry(): Center of geometry of (compounds of) the group
MDAnalysis.core.groups.AtomGroup.center_of_mass(): Center of mass of (compounds of) the group
mdtools.structure.center(): Different types of centers of (compounds of) an MDAnalysis AtomGroup
mdtools.structure.wcenter_pos(): Calculate the weighted center of a position array
mdtools.structure.coc(): Center of charge of (compounds of) an MDAnalysis AtomGroup
mdtools.structure.cog(): Center of geometry of (compounds of) an MDAnalysis AtomGroup
mdtools.structure.com(): Center of mass of (compounds of) an MDAnalysis AtomGroup

Notes

This function uses the center() method of the input AtomGroup to calculate the weighted center.

Important

If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will be nan! If debug is set to True, a warning will be raised if any compound’s weighted center is nan.

If make_whole is True, all Atoms in ag are wrapped back into the primary unit cell using mdtools.box.wrap() before calling center() with the option unwrap set to True. This is done to ensure that the unwrap algorithm (better called “make whole” algorithm) of center() is working properly. This means that making compounds whole in an unwrapped trajectory will lead to a wrapped trajectory with whole compounds (some Atoms may lie outside the primary unit cell, but each compound’s center will lie inside the primary unit cell). make_whole has no effect if cmp is set to 'atoms'.

Todo

Check if it is really necessary to wrap all Atoms back into the primary unit cell before calling center() with unwrap set to True. The currently done back-wrapping is a serious problem, because it implies an inplace change of the Atom coordinates.