Source code for polyphys.probe.pairs

"""
==========================================================
:mod:`polyphys.probe.pairs`
==========================================================

The :mod:`polyphys.probe.pairs` module measures, in every frame of a
trajectory, the distances between the particles of one species, the pairs
in direct contact, and the bonds and clusters those contacts form: the
foci of the *TransFoci* studies, the large monomers of a ring among small
ones. :class:`PairDistances` is an MDAnalysis
:class:`~MDAnalysis.analysis.base.AnalysisBase`, so it runs over a slice of
frames in serial or, split across workers, in parallel, and stores one
array per quantity in its ``results``.

The research code measured the same four quantities in one loop over the
frames of each *TransFoci* study's probe function, without the minimum
image, and wrote the LAMMPS atom IDs of the foci on the diagonal of the
distance matrix. Here the diagonal carries the foci's 0-based backbone
indices (see :class:`PairDistances`, "Notes"), and the minimum image along
the periodic directions is optional.

Contents
========

- :class:`PairDistances`, the per-frame pair analysis.

Dependencies
============
- Python standard library: `math`, `pathlib`, `typing`.
- `NumPy <https://numpy.org/>`_.
- `MDAnalysis <https://docs.mdanalysis.org/>`_ 2.8 or later, through the
  ``mda`` extra: :class:`~MDAnalysis.analysis.base.AnalysisBase` and
  :class:`~MDAnalysis.analysis.results.ResultsGroup`.
- :mod:`polyphys.analyze.clusters`:
  :func:`~polyphys.analyze.clusters.pair_distances`,
  :func:`~polyphys.analyze.clusters.find_direct_contacts`,
  :func:`~polyphys.analyze.clusters.count_bonds`, and
  :func:`~polyphys.analyze.clusters.count_clusters`.
- :mod:`polyphys.spec`:
  :class:`~polyphys.spec.ProbeSpec`.
- :mod:`polyphys.manage.parser`:
  :class:`~polyphys.manage.parser.ParserBase`.
- :mod:`polyphys.probe.core`: ``_ProbeAnalysis``, the base whose ``run``
  closes the pool of the ``multiprocessing`` backend, and
  ``_compute_part``, which computes each part of a split run on its own
  copy of the analysis.

Notation
========
:math:`n`, :math:`F`
    The number of particles of the species and the frames of a run.
:math:`d_{ij}`, :math:`r_c`
    The distance between particles :math:`i < j` in a frame, in the dump's
    length unit, and the contact cutoff: :math:`i` and :math:`j` are in
    direct contact when :math:`d_{ij} \\le r_c`.
:math:`g_i`
    The backbone index of particle :math:`i`, 0-based, from which the
    pipeline's :class:`~polyphys.analyze.pipeline.FociPairDistances` takes
    the genomic distance of each pair.

Examples
========
Three foci at the corners of a 3-4-5 triangle, one frame, with a cutoff of
3.5: the first two are in contact, the third is alone.

>>> import MDAnalysis as mda
>>> import numpy as np
>>> universe = mda.Universe.empty(3, trajectory=True)
>>> universe.atoms.positions = np.array(
...     [[0.0, 0.0, 0.0], [3.0, 0.0, 0.0], [3.0, 4.0, 0.0]])
>>> analysis = PairDistances(universe.atoms, 3.5, [2, 5, 8]).run()
>>> analysis.results['distMatTFoci'][0]
array([[2., 3., 5.],
       [0., 5., 4.],
       [0., 0., 8.]])
>>> analysis.results['bondsHistTFoci'], analysis.results['clustersHistTFoci']
(array([[1, 2, 0]]), array([[0, 1, 1, 0]]))

.. versionadded:: 0.7.0
"""
import math
from pathlib import Path
from typing import Any, Self, Sequence

import numpy as np
from MDAnalysis.analysis.results import ResultsGroup
from MDAnalysis.core.groups import AtomGroup
from MDAnalysis.core.universe import Universe

from ..analyze import clusters
from ..manage.parser import ParserBase
from ..spec import ProbeSpec
from ..manage.types import EntityT, GeometryT, Pathish
from .core import _ProbeAnalysis, _compute_part

__all__ = [
    'PairDistances',
]

# The periodic directions of each geometry, for the minimum image: a
# cylinder is periodic along its axis, z, a cube in every direction.
_PERIODIC: dict[GeometryT, tuple[bool, bool, bool]] = {
    'cubic': (True, True, True),
    'cylindrical': (False, False, True),
}

# The quantities, in the order `results` and `save` list them, as the
# research code named them before the species label.
_QUANTITIES = ('distMatT', 'directContactsMatT', 'bondsHistT',
               'clustersHistT')

_BACKENDS = ('serial', 'multiprocessing', 'dask')


[docs] class PairDistances(_ProbeAnalysis): """ The pair distances, direct contacts, bonds, and clusters of one species, measured in every frame. .. versionadded:: 0.7.0 Parameters ---------- atomgroup : :class:`~MDAnalysis.core.groups.AtomGroup` The particles, at least two, in atom-ID order, which ``Universe.select_atoms`` gives; they index the matrices. cutoff : float The contact cutoff :math:`r_c`, finite and positive, in the dump's length unit. genomic_positions : sequence of int or numpy.ndarray The backbone index :math:`g_i` of each particle, 0-based, non-negative, and distinct, one per particle in the group's order; written on the diagonal of every frame's distance matrix. species : :py:obj:`~.EntityT`, default 'Foci' The species label, which names ``results`` and the files :meth:`save` writes, ``<name>-<quantity><species>.npy``. periodic : tuple of bool or None, default None The directions along which the distances use the minimum image, one flag each for ``x``, ``y``, and ``z``, with the frame's box lengths; ``None`` for none, as the research code measured. inclusive : bool, default True Whether a pair at exactly the cutoff is in contact, :math:`d_{ij} \\le r_c`, as the research code counted, rather than :math:`d_{ij} < r_c`. verbose : bool, default False Whether to show a progress bar during :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`. Attributes ---------- atomgroup : :class:`~MDAnalysis.core.groups.AtomGroup` The particles. cutoff : float The contact cutoff. genomic_positions : numpy.ndarray The backbone indices, int64, shape ``(n,)``. species : :py:obj:`~.EntityT` The species label. periodic : tuple of bool or None The minimum-image directions. inclusive : bool Whether the cutoff itself counts as contact. results : :class:`~MDAnalysis.analysis.results.Results` After :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, with ``S`` the species label: ``distMatTS``, float64 ``(n_frames, n, n)``, each frame's :math:`d_{ij}` for :math:`i < j` above the diagonal, :math:`g_i` on it, and zeros below; ``directContactsMatTS``, bool ``(n_frames, n, n)``, the symmetric contact matrix with ``True`` on the diagonal, as :func:`~polyphys.analyze.clusters.find_direct_contacts` returns it; ``bondsHistTS``, int64 ``(n_frames, n)``, ``[t, d]`` the number of particles with ``d`` contacts in frame ``t``; ``clustersHistTS``, int64 ``(n_frames, n + 1)``, ``[t, s]`` the number of clusters of size ``s`` in frame ``t``, with ``[t, 0]`` always 0. n_frames : int After :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, the number of frames analyzed, from :class:`~MDAnalysis.analysis.base.AnalysisBase`. frames : numpy.ndarray After :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, the indices of the frames analyzed, shape ``(n_frames,)``. times : numpy.ndarray After :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, the times of the frames analyzed, shape ``(n_frames,)``, in the trajectory's time unit. Raises ------ ValueError If `atomgroup` has fewer than two particles; if `cutoff` is not a finite positive number; if `genomic_positions` has not one non-negative integer per particle or repeats one; if `species` is empty; or if `periodic` is neither ``None`` nor three booleans, Python or NumPy. During :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, if a periodic direction is asked for and the frame carries no box. Notes ----- Per frame, :func:`~polyphys.analyze.clusters.pair_distances` gives the full distance matrix, with the minimum image along each direction of `periodic` using that frame's box length; :func:`~polyphys.analyze.clusters.find_direct_contacts` the contacts at the cutoff; :func:`~polyphys.analyze.clusters.count_bonds` the bonds histogram; and :func:`~polyphys.analyze.clusters.count_clusters` the clusters histogram, from the connected components of the contact matrix. The distance matrix is stored as the research code wrote it: its upper triangle, with the diagonal replaced. **Indexing.** LAMMPS numbers atoms from 1 (``read_data``: "a unique value from 1 to Natoms for each atom"), and MDAnalysis keeps those numbers as ``AtomGroup.ids`` while numbering its own atoms from 0 as ``AtomGroup.indices``. The research code wrote ``foci.atoms.ids`` on the diagonal, so the pair tags of its analysis, ``loc<i>loc<j>``, carry 1-based IDs. Here the diagonal carries the 0-based position of each particle along its chain, which :func:`~polyphys.analyze.clusters.genomic_distance` requires and :meth:`from_spec` computes; a tag of this package is therefore one less than the research tag of the same pair. The genomic distance itself is the same under either convention. The MDAnalysis contract: ``_prepare`` allocates one array per quantity for the frames of the run, ``_single_frame`` writes the current frame's entry, and ``_conclude`` does nothing. The class is marked parallelizable, with ``serial``, ``multiprocessing``, and ``dask`` backends; each worker fills the arrays of its own frames, which ``_get_aggregator`` concatenates along the frame axis (``ResultsGroup.ndarray_vstack``). Cost per frame: :math:`O(n^2)` time and space for the distance and contact matrices and the connected components. Over a run, :math:`8 F n^2` bytes for the distance matrices, :math:`F n^2` for the contact matrices, and :math:`8 F (2 n + 1)` for the two histograms: for the five foci of the *TransFoci* studies, :math:`8 \\cdot 25 + 25 + 8 \\cdot 11 = 313` bytes per frame. Positions come from MDAnalysis as float32, so each distance carries a relative round-off of about :math:`10^{-7}`. Examples -------- Two particles across the periodic boundary of a box of length 20 along z, at z = 0.5 and 19.5, are 1 apart with the minimum image and 19 without: >>> import MDAnalysis as mda >>> import numpy as np >>> universe = mda.Universe.empty(2, trajectory=True) >>> universe.load_new( ... np.array([[[0.0, 0.0, 0.5], [0.0, 0.0, 19.5]]]), format='MEMORY', ... dimensions=np.array([[20.0, 20.0, 20.0, 90.0, 90.0, 90.0]])) <Universe with 2 atoms> >>> wrapped = PairDistances(universe.atoms, 1.5, [0, 9], ... periodic=(False, False, True)).run() >>> wrapped.results['distMatTFoci'][0, 0, 1] np.float64(1.0) >>> wrapped.results['directContactsMatTFoci'][0] array([[ True, True], [ True, True]]) >>> PairDistances(universe.atoms, 1.5, [0, 9]).run().results[ ... 'distMatTFoci'][0, 0, 1] np.float64(19.0) """ _analysis_algorithm_is_parallelizable = True def __init__( self, atomgroup: AtomGroup, cutoff: float, genomic_positions: Sequence[int] | np.ndarray, *, species: EntityT = 'Foci', periodic: tuple[bool, bool, bool] | None = None, inclusive: bool = True, verbose: bool = False, ) -> None: super().__init__(atomgroup.universe.trajectory, verbose=verbose) n_atoms = atomgroup.n_atoms if n_atoms < 2: raise ValueError( f"'atomgroup' must hold at least two particles, not " f"{n_atoms}.") if not (isinstance(cutoff, (int, float)) and not isinstance(cutoff, bool) and math.isfinite(cutoff) and cutoff > 0): raise ValueError( f"'cutoff' must be a finite positive number, not " f"{cutoff!r}.") positions = np.asarray(genomic_positions) if (positions.shape != (n_atoms,) or not np.issubdtype(positions.dtype, np.integer) or np.any(positions < 0)): raise ValueError( f"'genomic_positions' must hold one non-negative integer " f"per particle, {n_atoms} in all, not " f"{list(np.ravel(genomic_positions))!r}.") if np.unique(positions).size != n_atoms: raise ValueError( f"'genomic_positions' repeats an index: " f"{positions.tolist()}.") if not (isinstance(species, str) and species): raise ValueError( f"'species' must be a non-empty label, not {species!r}.") if periodic is not None and not ( isinstance(periodic, (tuple, list)) and len(periodic) == 3 and all(isinstance(flag, (bool, np.bool_)) for flag in periodic)): raise ValueError( f"'periodic' must be None or three booleans, not " f"{periodic!r}.") self.atomgroup = atomgroup self.cutoff = float(cutoff) self.genomic_positions = positions.astype(np.int64) self.species = species self.periodic: tuple[bool, bool, bool] | None = ( None if periodic is None else (bool(periodic[0]), bool(periodic[1]), bool(periodic[2]))) self.inclusive = inclusive self._upper = np.triu_indices(n_atoms, 1) self._diagonal = np.diag_indices(n_atoms)
[docs] @classmethod def from_spec( cls, universe: Universe, spec: ProbeSpec, parser: ParserBase, *, verbose: bool = False, ) -> Self: """ Build the analysis of a whole's pair species from its study's probe spec. The particles are ``spec.pair_species`` selected with its string in ``spec.selections``; the cutoff is ``spec.contact_cutoff`` resolved for this whole; the backbone indices are the particles' positions among the atoms of ``spec.chain``, in atom-ID order; and the minimum image follows the geometry when ``spec.minimum_image`` is set. .. versionadded:: 0.7.0 Parameters ---------- universe : :class:`~MDAnalysis.core.universe.Universe` The trajectory, as :func:`~polyphys.probe.core.make_universe` opens it. spec : :class:`~polyphys.spec.ProbeSpec` The study's probe spec, with ``pair_species`` and ``contact_cutoff`` set. parser : :class:`~polyphys.manage.parser.ParserBase` The whole's parser, for the cutoff. verbose : bool, default False Whether to show a progress bar during :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`. Returns ------- PairDistances The analysis, not yet run. Raises ------ ValueError If the spec names no pair species, or if a selected particle is not among the chain's atoms. Examples -------- A ring of six monomers whose atoms 2, 4, and 6 (LAMMPS IDs) are the large ones: their backbone indices are 1, 3, and 5. >>> import MDAnalysis as mda >>> import numpy as np >>> from polyphys.tests.synthetic import RingCub >>> from polyphys.spec import ProbeSpec, ProjectSpec >>> project = ProjectSpec( ... parser=RingCub, group='bug', divisor=0.025, ... crowder_attr='phi_bulk_c', ... physical_attrs=('space', 'nmon_small', 'nmon_large'), ... species_sizes={'Mon': 'dmon_small', 'Foci': 'dmon_large', ... 'Crd': 'dcrowd'}, ... tseries_properties=('gyrTMon',)) >>> spec = ProbeSpec( ... project, {'Mon': 'resid 1', 'Foci': 'type 2'}, 'Mon', ... ('gyrT',), unwrap=False, pair_species='Foci', ... contact_cutoff=lambda info: info.dmon_large + info.dcrowd) >>> whole = RingCub( ... 'al2nl3ml8ns3ac1nc0l5dt0.005bdump1adump1ens1', ... 'whole', 'bug') >>> universe = mda.Universe.empty( ... 6, n_residues=1, atom_resindex=[0] * 6, trajectory=True) >>> universe.add_TopologyAttr('resid', [1]) >>> universe.add_TopologyAttr('ids', [1, 2, 3, 4, 5, 6]) >>> universe.add_TopologyAttr('types', ['1', '2'] * 3) >>> universe.load_new(np.array([[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], ... [2.0, 0.0, 0.0], [3.0, 0.0, 0.0], [3.0, 1.0, 0.0], ... [3.0, 2.0, 0.0]]]), format='MEMORY', dimensions=np.array( ... [[10.0, 10.0, 20.0, 90.0, 90.0, 90.0]])) <Universe with 6 atoms> >>> analysis = PairDistances.from_spec(universe, spec, whole) >>> analysis.genomic_positions, analysis.cutoff, analysis.periodic (array([1, 3, 5]), 3.0, (True, True, True)) >>> analysis.run().results['distMatTFoci'][0] array([[1. , 2. , 2.82842712], [0. , 3. , 2. ], [0. , 0. , 5. ]]) """ if spec.pair_species is None or spec.contact_cutoff is None: raise ValueError( f"{spec.name}: the probe spec names no pair species.") group = universe.select_atoms(spec.selections[spec.pair_species]) chain = universe.select_atoms(spec.selections[spec.chain]) in_chain = np.isin(group.ids, chain.ids) if not np.all(in_chain): raise ValueError( f"{spec.name}: the {spec.pair_species} atoms with IDs " f"{group.ids[~in_chain].tolist()} are not among the " f"{spec.chain} atoms.") genomic = np.flatnonzero(np.isin(chain.ids, group.ids)) periodic = _PERIODIC[spec.geometry] if spec.minimum_image else None return cls(group, ProbeSpec.resolve(spec.contact_cutoff, parser), genomic, species=spec.pair_species, periodic=periodic, verbose=verbose)
[docs] @classmethod def get_supported_backends(cls) -> tuple[str, ...]: """ The backends :meth:`~MDAnalysis.analysis.base.AnalysisBase.run` accepts: ``'serial'``, ``'multiprocessing'``, and ``'dask'``. Examples -------- >>> PairDistances.get_supported_backends() ('serial', 'multiprocessing', 'dask') """ return _BACKENDS
def _key(self, quantity: str) -> str: return f"{quantity}{self.species}" def _compute( self, indexed_frames: np.ndarray, verbose: Any = None, *, progressbar_kwargs: Any = None, ) -> Any: """ Compute one part of the run on a copy of this analysis, so that serial parts do not overwrite each other. """ return _compute_part(self, indexed_frames, verbose, progressbar_kwargs=progressbar_kwargs) def _get_aggregator(self) -> ResultsGroup: """ Concatenate each worker's arrays along the frame axis. """ return ResultsGroup(lookup={ self._key(quantity): ResultsGroup.ndarray_vstack for quantity in _QUANTITIES}) def _prepare(self) -> None: """ Allocate one array per quantity for the frames of this run or worker. """ n_atoms = self.atomgroup.n_atoms self.results[self._key('distMatT')] = np.zeros( (self.n_frames, n_atoms, n_atoms), dtype=np.float64) self.results[self._key('directContactsMatT')] = np.zeros( (self.n_frames, n_atoms, n_atoms), dtype=np.bool_) self.results[self._key('bondsHistT')] = np.zeros( (self.n_frames, n_atoms), dtype=np.int64) self.results[self._key('clustersHistT')] = np.zeros( (self.n_frames, n_atoms + 1), dtype=np.int64) def _box(self) -> Any: """The box lengths of the periodic directions, 0 elsewhere.""" if self.periodic is None: return None dimensions = self._ts.dimensions if dimensions is None: raise ValueError( f"frame {self._ts.frame} carries no box, which the " f"periodic directions {self.periodic} need.") lengths = np.asarray(dimensions[:3], dtype=np.float64) return np.where(self.periodic, lengths, 0.0) def _single_frame(self) -> None: """ Measure the four quantities on the current frame and store them in this frame's entries. """ distances = clusters.pair_distances( self.atomgroup.positions.astype(np.float64), self._box()) contacts = clusters.find_direct_contacts( distances, self.cutoff, inclusive=self.inclusive) matrix = np.zeros_like(distances) matrix[self._upper] = distances[self._upper] matrix[self._diagonal] = self.genomic_positions index = self._frame_index self.results[self._key('distMatT')][index] = matrix self.results[self._key('directContactsMatT')][index] = contacts self.results[self._key('bondsHistT')][index] = ( clusters.count_bonds(contacts)) self.results[self._key('clustersHistT')][index] = ( clusters.count_clusters(contacts))
[docs] def save(self, save_to: Pathish, name: str) -> list[Path]: """ Save each quantity's array as ``<name>-<quantity><species>.npy``. .. versionadded:: 0.7.0 Parameters ---------- save_to : str or pathlib.Path An existing directory. name : str The artifact's name, ``<parser.name>-<parser.group>`` in the studies, such as ``'epss5...ens1-bug'``. Returns ------- list of pathlib.Path The files written: the distance matrices, the contact matrices, the bonds histograms, and the clusters histograms. Raises ------ RuntimeError If :meth:`~MDAnalysis.analysis.base.AnalysisBase.run` has not been called. Examples -------- >>> import tempfile >>> import MDAnalysis as mda >>> import numpy as np >>> universe = mda.Universe.empty(2, trajectory=True) >>> universe.atoms.positions = np.array([[0.0, 0.0, 0.0], ... [0.0, 0.0, 3.0]]) >>> analysis = PairDistances(universe.atoms, 1.0, [0, 4]).run() >>> with tempfile.TemporaryDirectory() as tmp: ... paths = analysis.save(tmp, 'N2ens1-bug') ... len(paths), paths[0].name, np.load(paths[2]).tolist() (4, 'N2ens1-bug-distMatTFoci.npy', [[2, 0]]) """ if any(self._key(quantity) not in self.results for quantity in _QUANTITIES): raise RuntimeError("Call run() before save().") paths = [] for quantity in _QUANTITIES: path = Path(save_to) / f"{name}-{self._key(quantity)}.npy" np.save(path, self.results[self._key(quantity)]) paths.append(path) return paths