molclusters.cluster¶
cluster
¶
Provides the groups of molecules that MolClusters tracks and analyses.
Classes:
- MolGroup: A group of molecules (residues) of a Universe, with properties such as
mass, charge, dipole moment, radius of gyration, shape and density, computed on
the group made whole across periodic boundaries. Nuclei are MolGroups.
- Cluster: A MolGroup that is a tracked molecular cluster: it has an id, a birth
time and a read-only graph of the connections between its molecules. Clusters
are created and updated by a `ClusterTracker`; everyone else only reads them.
Constants:
- EA2D: Conversion factor for dipole moments from e·Å (MDAnalysis's unit) to
Debye.
Dependencies:
- MDAnalysis: For molecular dynamics trajectory and structure analysis.
- NetworkX: For the graph of a cluster's connections.
- NumPy: For numerical computations.
MolGroup
¶
MolGroup(universe: Universe, residues: Iterable[int] | ResidueGroup)
A group of molecules (residues) of a Universe, and its properties.
Geometric properties are computed on the group made whole across periodic
boundaries (see whole), and always for the Universe's current frame.
The group describes its residues, so it can't be changed through what it hands
out: its arrays are read-only (to change one, work on a copy:
array.copy()), and residues is a new group every time. Positions and
topology attributes belong to the shared Universe, not the group, and changing
them changes every group.
Attributes:
| Name | Type | Description |
|---|---|---|
_uni |
Universe
|
The MDAnalysis Universe object associated with the group. |
_rg |
ResidueGroup
|
The group's residues, over indices no one else holds. |
__cache_key |
tuple[int, bytes] | None
|
Frame and residue indices that |
__cache |
dict[str, object]
|
Values computed for the current frame and residues (see |
Initialize the MolGroup with a universe and residues.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
universe
|
Universe
|
The MDAnalysis Universe object associated with the group. |
required |
residues
|
Union[Iterable[int], ResidueGroup]
|
The residues of the group, either as an iterable with residue IDs or a
ResidueGroup. Residue IDs are taken as positions in the topology plus
one, so they must be numbered 1 to N (see |
required |
Source code in src/molclusters/cluster.py
universe
property
¶
The Universe the group belongs to.
Returns:
| Type | Description |
|---|---|
Universe
|
The group's Universe. |
residues
property
¶
residues: ResidueGroup
The group's residues.
Returns:
| Type | Description |
|---|---|
ResidueGroup
|
The residues of the group, as a new group: changing its indices
( |
atoms
property
¶
atoms: AtomGroup
The atoms of the group's residues.
Returns:
| Type | Description |
|---|---|
AtomGroup
|
The atoms of the group, in the Universe's current positions (see
|
size
property
¶
size: int
The number of molecules in the group.
Returns:
| Type | Description |
|---|---|
int
|
The number of residues in the group. |
resnames
property
¶
resnames: ndarray
The residue names of the group.
Returns:
| Type | Description |
|---|---|
ndarray
|
The residue names in the group (read-only). |
resids
property
¶
resids: ndarray
The residue IDs of the group.
Returns:
| Type | Description |
|---|---|
ndarray
|
The residue IDs in the group (read-only). |
composition
property
¶
center_of_mass
property
¶
center_of_mass: ndarray
Calculate the center of mass of the group, made whole.
Unlike MDAnalysis's own center_of_mass, a group split across periodic
boundaries gets the center of its whole shape, not a point between its
pieces.
Returns:
| Type | Description |
|---|---|
ndarray
|
The center of mass, wrapped into the primary unit cell (read-only). |
sphericity
property
¶
sphericity: float
Calculate how spherical the group is, from its gyration tensor.
This is one minus the asphericity (Dima & Thirumalai), not Wadell's surface-area sphericity: 1 when the three principal moments of the gyration tensor are equal (a sphere, but also e.g. a cube), 0 for a rod (all mass on a line), and 0.75 for a flat disk or ring.
Returns:
| Type | Description |
|---|---|
float
|
1 - asphericity, between 0 (rod) and 1 (spherical). |
dipole_moment
property
¶
dipole_moment: float
Calculate the dipole moment of the group, about its center of mass.
For a neutral group the dipole is the same about any point. For a group with a net charge q (ions, charged nuclei or clusters) it isn't: moving the reference point by d changes the dipole by -q d, so its value is the dipole about the center of mass specifically, and only comparable between groups with that convention in mind.
Returns:
| Type | Description |
|---|---|
float
|
The dipole moment of the group in Debye (D). |
dipole
property
¶
dipole: ndarray
Calculate the dipole vector of the group, about its center of mass.
See dipole_moment for what that reference point means for charged groups.
Returns:
| Type | Description |
|---|---|
ndarray
|
The dipole vector of the group in Debye (D) (read-only). |
shape_parameter
property
¶
shape_parameter: float
Calculate the shape parameter of the group.
Returns:
| Type | Description |
|---|---|
float
|
The shape parameter of the group, a measure of its geometric anisotropy. |
bsphere
property
¶
radius_of_gyration
property
¶
radius_of_gyration: float
Calculate the radius of gyration of the group.
Returns:
| Type | Description |
|---|---|
float
|
The radius of gyration of the group. |
radius_buffer
property
¶
radius_buffer: float
Half the mean van der Waals radius of the group's atoms, by element.
The radius of gyration only sees the atoms' centers, so a sphere built from it ends at the outer atoms' centers and leaves their size out. Adding half, not all, of the atoms' van der Waals radius to it roughly accounts for that, since bonded atoms' van der Waals spheres overlap: on methanol-malic acid mixtures, the full radius puts a lone malic acid at 0.70 g/cm^3 and half at 1.21 (1.61 for the solid), and barely changes large clusters.
Returns:
| Type | Description |
|---|---|
float
|
The buffer added to the equivalent sphere's radius, in angstroms. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the atoms have no elements, or an element has no van der Waals radius in MDAnalysis' table. |
radius
property
¶
radius: float
The radius of the group's equivalent sphere.
That is the uniform sphere with the group's radius of gyration, which has a
radius of sqrt(5/3) times it (a uniform sphere of radius R has a radius of
gyration of sqrt(3/5) R), grown by radius_buffer to roughly account for
the size of the atoms.
Returns:
| Type | Description |
|---|---|
float
|
The group's equivalent sphere radius, in angstroms. |
diameter
property
¶
diameter: float
Calculate the diameter of the group's equivalent sphere (see radius).
Returns:
| Type | Description |
|---|---|
float
|
Twice the group's radius, in angstroms. |
volume
property
¶
volume: float
Calculate the volume of the group's equivalent sphere (see radius).
Returns:
| Type | Description |
|---|---|
float
|
Volume in cubic angstroms. |
density
property
¶
density: float
Calculate the density of the group.
Returns:
| Type | Description |
|---|---|
float
|
The density of the group in g/cm^3. |
charge
property
¶
charge: float
Calculate the total charge of the group.
Returns:
| Type | Description |
|---|---|
float
|
The total charge of the group. |
__whole
¶
Get the group's whole positions and shift, computed once per frame.
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
See |
Source code in src/molclusters/cluster.py
__compute_whole_positions
¶
Compute the group's atom positions with the group made whole.
The group is translated so that its first residue sits at the box center,
and each residue is made whole and wrapped into the box by its center of
geometry, which gathers a group spanning less than half the box around the
center. A larger group would be torn apart that way, so the residues are
then placed one after another along a spanning tree of the group (see
_placement_order), each at the periodic image nearest its tree neighbour.
The Universe's positions are left exactly as they were.
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
Whole positions, one row per atom of |
Source code in src/molclusters/cluster.py
__place_residues
¶
Move each residue to the periodic image nearest its placed neighbour.
Changes positions in place, by whole box vectors per residue: none at all
for a group spanning less than half the box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
atoms
|
AtomGroup
|
The group's atoms. |
required |
positions
|
ndarray
|
Their positions, each residue whole and wrapped into the box. |
required |
Source code in src/molclusters/cluster.py
whole
¶
Temporarily place the group's atoms in whole, centered positions.
Inside the with block the group's atoms are whole across periodic
boundaries, so geometric properties (and writers) see the real shape. On
exit, even on error, the atoms go back to their original positions.
Positions are never changed for good because they belong to the shared Universe: other groups over overlapping residues (e.g. a nucleus inside a cluster) would otherwise move atoms under each other and corrupt each other's geometry.
The whole positions are cached per frame and residue set (see
_frame_cache), so the unwrap runs once per frame no matter how many
properties are read.
Yields:
| Type | Description |
|---|---|
AtomGroup
|
The group's atoms, in whole positions. |
Source code in src/molclusters/cluster.py
__add__
¶
__add__(other: ResidueGroup | Self) -> MolGroup
Combine this group with a ResidueGroup or another MolGroup.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
Union[ResidueGroup, MolGroup]
|
The ResidueGroup or MolGroup to combine with. |
required |
Returns:
| Type | Description |
|---|---|
MolGroup
|
A new MolGroup with the residues of both. |
Source code in src/molclusters/cluster.py
__len__
¶
__len__() -> int
Get the number of molecules in the group.
Returns:
| Type | Description |
|---|---|
int
|
The number of residues in the group. |
__iter__
¶
Cluster
¶
Cluster(universe: Universe, subconntab: _SubConnTable, *, cluster_id: int)
Bases: MolGroup
A tracked molecular cluster.
A MolGroup with an id, a birth time and the graph of the connections between
its molecules. Clusters are created and updated by a ClusterTracker and are
otherwise read-only: the graph is frozen, attributes included, and a new one
replaces it every frame; its arrays are read-only (see MolGroup).
A Cluster is the same object for as long as it lives, and its properties are those of the Universe's current frame, so it describes a given frame only while the Universe is at that frame.
Clusters compare and hash by identity, which is the tracked cluster: the tracker
keeps one object per cluster for its whole life. To keep data per cluster, key
it by id rather than by the Cluster, so a dead cluster (and its cached whole
positions) isn't kept in memory.
Attributes:
| Name | Type | Description |
|---|---|---|
_graph |
Graph
|
The frozen graph of the cluster's molecules and their connections. |
_id |
int
|
The cluster's id. |
_birth_time |
float
|
The time of the frame the cluster was created at. |
_wrap_reported |
bool
|
Whether the cluster was already reported wrapping around the box. |
Initialize a Cluster from a connected group of the current frame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
universe
|
Universe
|
The MDAnalysis Universe object associated with the cluster. |
required |
subconntab
|
_SubConnTable
|
The connected group of molecules the cluster is made of. |
required |
cluster_id
|
int
|
The cluster's id, as handed out by whoever tracks it (e.g. a
|
required |
Source code in src/molclusters/cluster.py
id
property
¶
id: int
The cluster's id, unique among the clusters of its tracker.
Returns:
| Type | Description |
|---|---|
int
|
The id of the cluster. |
graph
property
¶
graph: Graph
The molecules of the cluster and their connections, as a frozen graph.
Nodes are residue IDs, and each edge joins two connected molecules. A
"cm" rule's edge has the distance between their centers of mass; an
"hb" rule's has the donor-acceptor distance and D-H-A angle of the
shortest of their H-bonds, and n_hbonds, how many they share.
Returns:
| Type | Description |
|---|---|
Graph
|
The graph of the cluster, which can't be modified, nor can the
attributes of its edges, nodes or itself ( |
birth_time
property
¶
birth_time: float
The time of the frame the cluster was created at.
Returns:
| Type | Description |
|---|---|
float
|
The birth time of the cluster. |
age
property
¶
age: float
The time since the cluster was created.
Returns:
| Type | Description |
|---|---|
float
|
The age of the cluster at the Universe's current frame. |
neighbors
¶
Get the neighbors of a molecule in the cluster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int
|
The reference molecule. |
required |
level
|
int | None
|
How many connections away to look (1 when None). |
None
|
Returns:
| Type | Description |
|---|---|
set[int]
|
The molecules at most |
Source code in src/molclusters/cluster.py
distance
¶
Get the distance between two connected molecules of the cluster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
moli
|
int
|
The first molecule. |
required |
molj
|
int
|
The second molecule. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The distance of the connection between the two molecules. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/molclusters/cluster.py
__contains__
¶
__iter__
¶
__len__
¶
__len__() -> int
Get the number of molecules in the cluster.
Returns:
| Type | Description |
|---|---|
int
|
The number of molecules in the cluster. |