"""
==========================================================
:mod:`polyphys.probe.histograms`
==========================================================
The :mod:`polyphys.probe.histograms` module bins the positions of every
species of a study in every frame of a trajectory: one-dimensional
histograms along the directions of the geometry, kept per frame, and
two-dimensional maps in the three Cartesian planes, kept as the mean map
of each block of consecutive frames. :class:`SpatialHistograms` is an
MDAnalysis :class:`~MDAnalysis.analysis.base.AnalysisBase`, so it runs over
a slice of frames in serial or, split across workers, in parallel;
:func:`histogram_edges` builds the bin edges of one whole from its probe
spec and parser, with the research code's bin sizes and the studies'
geometry.
The research code binned the same species in one loop over the frames of
each study's probe function, after shifting every position by half the
parser's box, and summed the counts over the frames. Here the one-dimensional
counts are kept per frame, so that the time dependence and the block
statistics of a profile remain available, and the two-dimensional maps,
which would not fit in memory per frame, are averaged over blocks of
``block_frames`` frames. The sum over frames of either is what the research
code saved.
Contents
========
- :class:`SpatialHistograms`, the per-frame and per-block binning.
- :func:`histogram_edges`, the bin edges of a whole.
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.measurer`: the histogram helpers
:func:`~polyphys.analyze.measurer.fixedsize_bins`,
:func:`~polyphys.analyze.measurer.radial_histogram`,
:func:`~polyphys.analyze.measurer.radial_cyl_histogram`,
:func:`~polyphys.analyze.measurer.axial_histogram`,
:func:`~polyphys.analyze.measurer.azimuth_cyl_histogram`, and
:func:`~polyphys.analyze.measurer.planar_cartesian_histogram`.
- :mod:`polyphys.spec`:
:class:`~polyphys.spec.ProbeSpec` and
:data:`~polyphys.spec.RecenterT`.
- :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:`F`, :math:`b`, :math:`K = \\lceil F / b \\rceil`
The frames of a run, the block length, and the number of blocks; block
:math:`k` holds the frames :math:`kb, \\ldots, \\min((k + 1) b, F) - 1`
in the order the run visits them.
:math:`\\mathbf{r}_i = (x_i, y_i, z_i)`
The position of particle :math:`i` after recentering, in the dump's
length unit, the monomer diameter in the studies.
:math:`r`, :math:`\\theta`, :math:`z`
In a cylinder whose axis is :math:`z`: :math:`\\sqrt{x^2 + y^2}`,
:math:`\\operatorname{atan2}(y, x)` in :math:`[-\\pi, \\pi]`, and the
axial coordinate. In a cube, :math:`r = |\\mathbf{r}|` from the box
center.
:math:`D`, :math:`Z`, :math:`L`, :math:`a_w`
The parser's ``dcyl``, ``lcyl``, and ``lcube``, and the wall-bead size
:math:`a_w = 1` of the cylindrical studies, so that the LAMMPS box is
:math:`(D + a_w) \\times (D + a_w) \\times Z` or :math:`L^3`.
Examples
========
Two particles in a periodic cube of side 20, three frames, with the dump
reader's frame already translated to the origin, so that ``'half'`` moves
the box center to the origin:
>>> import MDAnalysis as mda
>>> import numpy as np
>>> frames = np.array([
... [[10.0, 10.0, 10.0], [12.5, 10.0, 10.0]],
... [[10.0, 10.0, 10.0], [10.0, 10.0, 11.0]],
... [[10.0, 10.0, 10.0], [10.0, 13.5, 10.0]]])
>>> universe = mda.Universe.empty(2, trajectory=True)
>>> universe.load_new(frames, format='MEMORY', dimensions=np.tile(
... [20.0, 20.0, 20.0, 90.0, 90.0, 90.0], (3, 1)))
<Universe with 2 atoms>
>>> edges = {'r': np.arange(0.0, 17.5, 1.0)}
>>> for key in 'xyz':
... edges[key] = np.linspace(-10.0, 10.0, 5)
>>> analysis = SpatialHistograms(
... {'Mon': universe.atoms}, edges, geometry='cubic', block_frames=2)
>>> analysis = analysis.run()
>>> analysis.results['rHistTMon'][:, :4]
array([[1, 0, 1, 0],
[1, 1, 0, 0],
[1, 0, 0, 1]])
>>> analysis.results['blockFrames']
array([2, 1])
.. versionadded:: 0.7.0
"""
import math
from pathlib import Path
from typing import Any, Callable, Mapping, Self
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 measurer
from ..manage.parser import ParserBase
from ..spec import ProbeSpec, RecenterT
from ..manage.types import (
AxisT,
BinT,
DirectionT,
EntityT,
GeometryT,
Pathish,
)
from .core import _ProbeAnalysis, _compute_part
__all__ = [
'SpatialHistograms',
'histogram_edges',
]
# The size of the beads whose centers form the cylindrical wall, which the
# parsers document: the LAMMPS box spans the wall-bead centers, so its
# transverse length is dcyl + _WALL_BEAD.
_WALL_BEAD = 1.0
# The directions of the one-dimensional histograms in each geometry, in the
# research code's order, and the edges each geometry's two-dimensional maps
# need. 'z' edges serve both the axial histogram and the maps of a cylinder.
_DIRECTIONS: Mapping[GeometryT, tuple[DirectionT, ...]] = {
'cubic': ('r',),
'cylindrical': ('r', 'z', 'theta'),
}
_CARTESIAN: tuple[DirectionT, ...] = ('x', 'y', 'z')
_PLANES: tuple[str, ...] = ('xy', 'xz', 'yz')
_AXIS: AxisT = 2 # the cylinder axis, z, in every study
# The directions each geometry makes periodic, along which a position is
# wrapped into the box before binning: every one in a periodic cube, the
# axis only in a cylinder (LAMMPS boundary ``ff ff pp``).
_PERIODIC: Mapping[GeometryT, tuple[int, ...]] = {
'cubic': (0, 1, 2),
'cylindrical': (_AXIS,),
}
# One frame's one-dimensional histogram along a direction.
_Histogram = Callable[[np.ndarray, np.ndarray], np.ndarray]
def _radial_cyl(positions: np.ndarray, edges: np.ndarray) -> np.ndarray:
return measurer.radial_cyl_histogram(positions, edges, _AXIS)
def _axial(positions: np.ndarray, edges: np.ndarray) -> np.ndarray:
return measurer.axial_histogram(positions, edges, _AXIS)
def _azimuth(positions: np.ndarray, edges: np.ndarray) -> np.ndarray:
return measurer.azimuth_cyl_histogram(positions, edges, _AXIS)
_HISTOGRAMS: Mapping[GeometryT, Mapping[DirectionT, _Histogram]] = {
'cubic': {'r': measurer.radial_histogram},
'cylindrical': {'r': _radial_cyl, 'z': _axial, 'theta': _azimuth},
}
_BACKENDS = ('serial', 'multiprocessing', 'dask')
def _required_edges(geometry: GeometryT) -> tuple[DirectionT, ...]:
"""The edge keys a geometry's histograms and maps need, in order."""
return tuple(dict.fromkeys((*_DIRECTIONS[geometry], *_CARTESIAN)))
def _check_recenter(recenter: Any) -> RecenterT:
"""Validate a recentering and return it with a triple as floats."""
if isinstance(recenter, str) and recenter == 'none':
return 'none'
if isinstance(recenter, str) and recenter == 'half':
return 'half'
if (isinstance(recenter, (tuple, list)) and len(recenter) == 3
and all(isinstance(value, (int, float))
and not isinstance(value, bool)
and math.isfinite(value) for value in recenter)):
return (float(recenter[0]), float(recenter[1]), float(recenter[2]))
raise ValueError(
f"'recenter' must be 'none', 'half', or a triple of finite numbers, "
f"not {recenter!r}.")
def _planar(
positions: np.ndarray, plane: str, edges: Mapping[str, np.ndarray]
) -> np.ndarray:
"""One frame's map in `plane`, rows along its first axis."""
if plane == 'xy':
return measurer.planar_cartesian_histogram(
positions, [edges['x'], edges['y']], 2)
if plane == 'yz':
return measurer.planar_cartesian_histogram(
positions, [edges['y'], edges['z']], 0)
# dim=1 bins (z, x); transpose to the research code's (x, z).
return measurer.planar_cartesian_histogram(
positions, [edges['z'], edges['x']], 1).T
[docs]
def histogram_edges(
spec: ProbeSpec, parser: ParserBase
) -> dict[str, np.ndarray]:
"""
The bin edges of one whole's histograms and maps.
The bin sizes are the spec's, resolved for this whole by
:meth:`~polyphys.spec.ProbeSpec.resolve`; the ranges follow
the geometry, so that every position inside the confinement falls
between the edges:
- Cylinder: ``'r'`` over :math:`[0, (D + a_w) / 2]`, the wall surface,
with 'nonnegative' bins; ``'z'`` over :math:`[-Z / 2, Z / 2]` and
``'x'``, ``'y'`` over :math:`[-(D + a_w) / 2, (D + a_w) / 2]` with
'ordinary' bins; ``'theta'`` over :math:`[-\\pi, \\pi]` with
'periodic' bins.
- Cube: ``'r'`` over :math:`[0, \\sqrt{3} L / 2]`, the corner, with
'nonnegative' bins; ``'x'``, ``'y'``, ``'z'`` over
:math:`[-L / 2, L / 2]` with 'ordinary' bins.
The research code ranged ``'r'``, ``'x'``, and ``'y'`` of a cylinder
over :math:`D / 2` and ``'r'`` of a cube over :math:`L / 2`, and
silently dropped the positions beyond them; the maintainer extended the
ranges on 2026-11-04, since :class:`SpatialHistograms` raises on such a
position instead.
.. versionadded:: 0.7.0
Parameters
----------
spec : :class:`~polyphys.spec.ProbeSpec`
The study's probe spec, whose ``bin_sizes`` holds every key that
``geometry`` needs: ``'r'``, ``'z'``, ``'theta'``, ``'x'``, ``'y'``
for a cylinder; ``'r'``, ``'x'``, ``'y'``, ``'z'`` for a cube.
parser : :class:`~polyphys.manage.parser.ParserBase`
The whole's parser, with ``dcyl`` and ``lcyl`` or ``lcube``.
Returns
-------
dict of (str -> numpy.ndarray)
The edges keyed by direction, each float64 and increasing, with
``n_bins + 1`` entries, in the order the geometry needs them.
Raises
------
ValueError
If ``spec.bin_sizes`` lacks a key the geometry needs, or if a
resolved bin size is not a finite positive number.
Notes
-----
:math:`O(B)` time and space for :math:`B` edges in all.
Examples
--------
>>> from polyphys.tests.synthetic import ChainCyl
>>> from polyphys.spec import ProbeSpec, ProjectSpec
>>> project = ProjectSpec(
... parser=ChainCyl, group='bug', divisor=0.025,
... crowder_attr='phi_bulk_c',
... physical_attrs=('space', 'nmon', 'dcyl', 'dcrowd'),
... species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
... tseries_properties=('gyrTMon',))
>>> spec = ProbeSpec(
... project, {'Mon': 'resid 1', 'Crd': 'resid 0'}, 'Mon', ('gyrT',),
... unwrap=False, histogram_species=('Mon', 'Crd'), block_frames=100,
... bin_sizes={'r': 0.5, 'z': 1.0, 'theta': np.pi / 2, 'x': 0.5,
... 'y': 0.5})
>>> whole = ChainCyl(
... 'N20r2.5lz5ac1nc0dt0.005bdump1adump1ens1', 'whole',
... 'all')
>>> edges = histogram_edges(spec, whole)
>>> list(edges)
['r', 'z', 'theta', 'x', 'y']
>>> edges['r']
array([0. , 0.5, 1. , 1.5, 2. , 2.5])
>>> edges['z'][[0, -1]], edges['theta'].size
(array([-5., 5.]), 5)
"""
geometry = spec.geometry
missing = [key for key in _required_edges(geometry)
if key not in spec.bin_sizes]
if missing:
raise ValueError(
f"{spec.name}: 'bin_sizes' lacks {missing}, which the "
f"{geometry} histograms need.")
sizes = {key: ProbeSpec.resolve(spec.bin_sizes[key], parser)
for key in _required_edges(geometry)}
ranges: dict[DirectionT, tuple[float, float, BinT]]
if geometry == 'cylindrical':
half_box = 0.5 * (float(getattr(parser, 'dcyl')) + _WALL_BEAD)
half_length = 0.5 * float(getattr(parser, 'lcyl'))
ranges = {
'r': (0.0, half_box, 'nonnegative'),
'z': (-half_length, half_length, 'ordinary'),
'theta': (-np.pi, np.pi, 'periodic'),
'x': (-half_box, half_box, 'ordinary'),
'y': (-half_box, half_box, 'ordinary'),
}
else:
half_side = 0.5 * float(getattr(parser, 'lcube'))
ranges = {
'r': (0.0, math.sqrt(3.0) * half_side, 'nonnegative'),
'x': (-half_side, half_side, 'ordinary'),
'y': (-half_side, half_side, 'ordinary'),
'z': (-half_side, half_side, 'ordinary'),
}
return {
key: np.asarray(
measurer.fixedsize_bins(sizes[key], lmin, lmax,
bin_type)['bin_edges'],
dtype=np.float64)
for key, (lmin, lmax, bin_type) in ranges.items()}
[docs]
class SpatialHistograms(_ProbeAnalysis):
"""
The positions of each species binned in every frame: one-dimensional
histograms per frame and two-dimensional maps per block of frames.
.. versionadded:: 0.7.0
Parameters
----------
groups : mapping of :py:obj:`~.EntityT` to
~MDAnalysis.core.groups.AtomGroup
Each species label mapped to its atoms, all in one universe, in the
order ``results`` and :meth:`save` list the species. A group may be
empty, for a species a whole lacks; its histograms are then zero.
edges : mapping of str to numpy.ndarray
The bin edges, increasing, keyed as :func:`histogram_edges` returns
them: the directions of `geometry` and ``'x'``, ``'y'``, ``'z'``.
geometry : :py:obj:`~.GeometryT`
``'cylindrical'``, with the histograms along ``'r'``, ``'z'``, and
``'theta'`` about the ``z`` axis, or ``'cubic'``, with the
histogram along ``'r'`` from the box center.
block_frames : int
The block length :math:`b`, positive: consecutive frames of the
run whose maps are averaged into one stored map.
recenter : :py:data:`~polyphys.spec.RecenterT`, default 'half'
How a frame's positions are moved before binning: ``'half'``
subtracts half the frame's box lengths, ``'none'`` nothing, a
triple its values. The positions in the trajectory are untouched.
verbose : bool, default False
Whether to show a progress bar during
:meth:`~MDAnalysis.analysis.base.AnalysisBase.run`.
Attributes
----------
groups : mapping of :py:obj:`~.EntityT` to
~MDAnalysis.core.groups.AtomGroup
The species, a copy of the mapping given.
edges : mapping of str to numpy.ndarray
The edges, a copy of the mapping given, each float64.
geometry : :py:obj:`~.GeometryT`
The geometry.
block_frames : int
The block length.
recenter : :py:data:`~polyphys.spec.RecenterT`
The recentering, a triple as floats.
results : :class:`~MDAnalysis.analysis.results.Results`
After :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, for each
species ``S`` and direction ``d`` of the geometry, ``dHistTS``, int64
``(n_frames, n_bins)``, the counts of frame ``i`` in row ``i``, and
``dHistS``, int64 ``(n_bins,)``, their sum over the frames; for each
plane ``p`` in ``xy``, ``xz``, ``yz``, ``pHistBlockS``, float64
``(n_blocks, n_a, n_b)``, the mean map of each block, rows along the
plane's first axis, and ``pHistS``, float64 ``(n_a, n_b)``, the counts
summed over the frames; and ``blockFrames``, int64 ``(n_blocks,)``, the
frames in each block.
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 `groups` is empty, has an empty label, or spans two universes; if
`edges` lacks a key the geometry needs or has edges that are not a
one-dimensional increasing array of at least two values; if `geometry`
is unknown; if `block_frames` is not a positive integer; if `recenter`
is neither ``'none'``, ``'half'``, nor a triple of finite numbers; or,
during :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`, if a frame
carries no box, or if a wrapped and recentered position falls outside
the edges of a direction or a Cartesian axis.
Notes
-----
Per frame and species, the positions are copied, wrapped, recentered,
and binned. Wrapping maps each position into the box of the reader's
frame, :math:`[0, L)`, along the directions the geometry makes
periodic, every one in a cube and ``z`` in a cylinder: LAMMPS enforces
the periodic boundaries only when it rebuilds the neighbor lists, so a
dump can place an atom slightly outside the box [1]_, as the HnsCub
dumps do by up to :math:`0.04` monomer diameters. The box of the
reader's frame is MDAnalysis's primary unit cell, :math:`[0, L)`, where
its LAMMPS dump reader puts the box by subtracting the lower bounds; a
universe built in memory must place its positions there too. A position
past a wall is not wrapped. The positions are binned with
:func:`~polyphys.analyze.measurer.radial_cyl_histogram`,
:func:`~polyphys.analyze.measurer.axial_histogram`, and
:func:`~polyphys.analyze.measurer.azimuth_cyl_histogram` in a cylinder,
:func:`~polyphys.analyze.measurer.radial_histogram` in a cube, and
:func:`~polyphys.analyze.measurer.planar_cartesian_histogram` in each
plane, with the ``xz`` map transposed to rows along ``x`` as the
research code stored it. A position outside the edges after wrapping
raises, so every frame's counts sum to the species' particle number:
the research code's ``np.histogram`` dropped such a position silently,
and did not wrap.
Blocks are numbered over the frames of the whole run in the order
:meth:`~MDAnalysis.analysis.base.AnalysisBase.run` visits them, whatever
``start``, ``stop``, ``step``, or ``frames`` select, so that a run split
across workers gives the same blocks as a serial one: ``_setup_frames``
records the run's frame count before the split and ``_compute`` each
worker's offset into it. Each worker accumulates the block sums and frame
counts of its own frames, which ``_get_aggregator`` adds
(``ResultsGroup.ndarray_sum``), and its per-frame rows, which it
concatenates (``ResultsGroup.ndarray_vstack``); ``_conclude`` then divides
each block's sum by its frame count and sums the counts over the frames.
Cost per frame: :math:`O(S N \\log B)` time for :math:`S` species of
:math:`N` particles and :math:`B` bins along a direction, from the
sorted-edge search of ``np.histogram`` and ``np.histogram2d``, and
:math:`O(N)` extra space for the recentered positions. Over a run, each
one-dimensional histogram holds :math:`8 F B` bytes and each map
:math:`8 K B_a B_b` bytes, for :math:`F` frames, :math:`K = \\lceil F /
b \\rceil` blocks, and :math:`B_a \\times B_b` cells: with
:math:`b = 100` and :math:`200 \\times 200` cells, about 1 MB per
block per species for the three planes. Wrapping adds :math:`O(N)`
time per frame and species.
References
----------
.. [1] LAMMPS Developers, "dump command", LAMMPS documentation, note
on periodic boundaries: "the coordinates of an atom written to a dump
file may be slightly outside the simulation box".
https://docs.lammps.org/dump.html
Examples
--------
One particle in a cylinder of radius 2 and length 4, two frames in the
reader's frame, the box from 0 to 4, recentered by a given shift to
(1.5, 0, 1) and (0, 0.5, -1); the frame's counts sum to its one
particle along every direction:
>>> import MDAnalysis as mda
>>> import numpy as np
>>> frames = np.array([[[3.5, 2.0, 3.0]], [[2.0, 2.5, 1.0]]])
>>> universe = mda.Universe.empty(1, trajectory=True)
>>> universe.load_new(frames, format='MEMORY', dimensions=np.tile(
... [4.0, 4.0, 4.0, 90.0, 90.0, 90.0], (2, 1)))
<Universe with 1 atoms>
>>> edges = {'r': np.array([0.0, 1.0, 2.0]),
... 'z': np.array([-2.0, 0.0, 2.0]),
... 'theta': np.linspace(-np.pi, np.pi, 5),
... 'x': np.array([-2.0, 0.0, 2.0]),
... 'y': np.array([-2.0, 0.0, 2.0])}
>>> analysis = SpatialHistograms(
... {'Crd': universe.atoms}, edges, geometry='cylindrical',
... block_frames=2, recenter=(2.0, 2.0, 2.0)).run()
>>> analysis.results['rHistTCrd'], analysis.results['zHistTCrd']
(array([[0, 1],
[1, 0]]), array([[0, 1],
[1, 0]]))
>>> analysis.results['xyHistBlockCrd']
array([[[0., 0.],
[0., 1.]]])
>>> float(analysis.results['xyHistCrd'].sum())
2.0
"""
_analysis_algorithm_is_parallelizable = True
def __init__(
self,
groups: Mapping[EntityT, AtomGroup],
edges: Mapping[str, np.ndarray],
*,
geometry: GeometryT,
block_frames: int,
recenter: RecenterT = 'half',
verbose: bool = False,
) -> None:
groups = dict(groups)
if not groups or any(not (isinstance(label, str) and label)
for label in groups):
raise ValueError(
f"'groups' must map each non-empty species label to its "
f"atoms, not {list(groups)!r}.")
universes = {id(group.universe) for group in groups.values()}
if len(universes) != 1:
raise ValueError("'groups' must all belong to one universe.")
if geometry not in _DIRECTIONS:
raise ValueError(
f"'geometry' must be one of {list(_DIRECTIONS)}, not "
f"{geometry!r}.")
required = _required_edges(geometry)
missing = [key for key in required if key not in edges]
if missing:
raise ValueError(
f"'edges' lacks {missing}, which the {geometry} histograms "
f"need.")
checked: dict[str, np.ndarray] = {}
for key in required:
array = np.asarray(edges[key], dtype=np.float64)
if array.ndim != 1 or array.size < 2 or np.any(
np.diff(array) <= 0):
raise ValueError(
f"The edges along {key!r} must be a one-dimensional "
f"increasing array of at least two values.")
checked[key] = array
if not (isinstance(block_frames, int)
and not isinstance(block_frames, bool) and block_frames > 0):
raise ValueError(
f"'block_frames' must be a positive integer, not "
f"{block_frames!r}.")
universe = next(iter(groups.values())).universe
super().__init__(universe.trajectory, verbose=verbose)
# Plain dicts, not read-only proxies: the multiprocessing backend
# pickles the analysis, and a mappingproxy cannot be pickled.
self.groups: Mapping[EntityT, AtomGroup] = groups
self.edges: Mapping[str, np.ndarray] = checked
self.geometry: GeometryT = geometry
self.block_frames = block_frames
self.recenter = _check_recenter(recenter)
self._directions = _DIRECTIONS[geometry]
self._histograms = _HISTOGRAMS[geometry]
self._run_n_frames = 0
self._run_offset = 0
[docs]
@classmethod
def from_spec(
cls,
universe: Universe,
spec: ProbeSpec,
parser: ParserBase,
*,
verbose: bool = False,
) -> Self:
"""
Build the analysis of a whole from its study's probe spec.
The species are ``spec.histogram_species``, each selected with its
string in ``spec.selections``; the edges are
:func:`histogram_edges`'s; the geometry, block length, and
recentering are the spec's.
.. 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 ``histogram_species``,
``bin_sizes``, and ``block_frames`` set.
parser : :class:`~polyphys.manage.parser.ParserBase`
The whole's parser, for the edges.
verbose : bool, default False
Whether to show a progress bar during
:meth:`~MDAnalysis.analysis.base.AnalysisBase.run`.
Returns
-------
SpatialHistograms
The analysis, not yet run.
Raises
------
ValueError
If the spec names no histogram species, or from
:func:`histogram_edges`.
Examples
--------
>>> import MDAnalysis as mda
>>> import numpy as np
>>> from polyphys.tests.synthetic import ChainCyl
>>> from polyphys.spec import ProbeSpec, ProjectSpec
>>> project = ProjectSpec(
... parser=ChainCyl, group='bug', divisor=0.025,
... crowder_attr='phi_bulk_c',
... physical_attrs=('space', 'nmon', 'dcyl', 'dcrowd'),
... species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
... tseries_properties=('gyrTMon',))
>>> spec = ProbeSpec(
... project, {'Mon': 'resid 1', 'Crd': 'resid 0'}, 'Mon',
... ('gyrT',), unwrap=False, histogram_species=('Mon', 'Crd'),
... block_frames=100, bin_sizes={'r': 0.5, 'z': 1.0,
... 'theta': np.pi / 2, 'x': 0.5, 'y': 0.5})
>>> whole = ChainCyl(
... 'N2r2.5lz5ac1nc1dt0.005bdump1adump1ens1', 'whole',
... 'all')
>>> universe = mda.Universe.empty(
... 3, n_residues=2, atom_resindex=[0, 1, 1], trajectory=True)
>>> universe.add_TopologyAttr('resid', [0, 1])
>>> universe.load_new(np.array([[[1.0, 2.0, 3.0], [2.0, 2.0, 5.0],
... [3.0, 2.0, 5.0]]]), format='MEMORY', dimensions=np.array(
... [[5.0, 5.0, 10.0, 90.0, 90.0, 90.0]]))
<Universe with 3 atoms>
>>> analysis = SpatialHistograms.from_spec(universe, spec, whole)
>>> [group.n_atoms for group in analysis.groups.values()]
[2, 1]
>>> analysis.run().results['rHistCrd']
array([0, 0, 0, 1, 0])
"""
if not spec.histogram_species or spec.block_frames is None:
raise ValueError(
f"{spec.name}: the probe spec names no histogram species.")
groups = {species: universe.select_atoms(spec.selections[species])
for species in spec.histogram_species}
return cls(groups, histogram_edges(spec, parser),
geometry=spec.geometry, block_frames=spec.block_frames,
recenter=spec.recenter, 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
--------
>>> SpatialHistograms.get_supported_backends()
('serial', 'multiprocessing', 'dask')
"""
return _BACKENDS
def _setup_frames(
self, trajectory: Any, start: Any = None, stop: Any = None,
step: Any = None, frames: Any = None,
) -> None:
"""
Record the frame count of the whole run before it is split across
workers, which fixes the number of blocks.
"""
super()._setup_frames(trajectory, start=start, stop=stop, step=step,
frames=frames)
self._run_n_frames = int(self.n_frames)
self._run_offset = 0
def _compute(
self, indexed_frames: np.ndarray, verbose: Any = None, *,
progressbar_kwargs: Any = None,
) -> Any:
"""
Record where this part's frames start in the run, then compute the
part on a copy of this analysis, so that serial parts do not
overwrite each other.
"""
self._run_offset = (int(indexed_frames[0, 0])
if len(indexed_frames) else 0)
return _compute_part(self, indexed_frames, verbose,
progressbar_kwargs=progressbar_kwargs)
def _get_aggregator(self) -> ResultsGroup:
"""
Concatenate each worker's per-frame rows and add its block sums and
frame counts.
"""
lookup: dict[str, Callable[..., Any]] = {
'blockFrames': ResultsGroup.ndarray_sum}
for species in self.groups:
for direction in self._directions:
lookup[f"{direction}HistT{species}"] = (
ResultsGroup.ndarray_vstack)
for plane in _PLANES:
lookup[f"{plane}HistBlock{species}"] = (
ResultsGroup.ndarray_sum)
return ResultsGroup(lookup=lookup)
def _prepare(self) -> None:
"""
Allocate the per-frame rows of this run or worker and the block sums
and frame counts of the whole run.
"""
n_blocks = -(-self._run_n_frames // self.block_frames)
self.results['blockFrames'] = np.zeros(n_blocks, dtype=np.int64)
for species in self.groups:
for direction in self._directions:
self.results[f"{direction}HistT{species}"] = np.zeros(
(self.n_frames, self.edges[direction].size - 1),
dtype=np.int64)
for plane in _PLANES:
self.results[f"{plane}HistBlock{species}"] = np.zeros(
(n_blocks, self.edges[plane[0]].size - 1,
self.edges[plane[1]].size - 1), dtype=np.float64)
def _shift(self) -> np.ndarray:
"""The vector subtracted from this frame's positions."""
if self.recenter == 'none':
return np.zeros(3)
if self.recenter == 'half':
return 0.5 * np.asarray(self._ts.dimensions[:3],
dtype=np.float64)
return np.asarray(self.recenter, dtype=np.float64)
def _wrap(self, positions: np.ndarray) -> np.ndarray:
"""Wrap `positions` into the frame's box, :math:`[0, L)`, along the
geometry's periodic directions, in place."""
if self._ts.dimensions is None:
raise ValueError(
f"Frame {self._ts.frame} carries no box, which wrapping "
f"along the periodic directions needs.")
axes = list(_PERIODIC[self.geometry])
lengths = np.asarray(self._ts.dimensions[:3],
dtype=np.float64)[axes]
positions[:, axes] -= lengths * np.floor(positions[:, axes] / lengths)
return positions
def _single_frame(self) -> None:
"""
Wrap, recenter, and bin every species on the current frame: the
histograms into this frame's rows, the maps into this frame's block.
"""
block = (self._run_offset + self._frame_index) // self.block_frames
self.results['blockFrames'][block] += 1
shift = self._shift()
for species, group in self.groups.items():
positions = self._wrap(
group.positions.astype(np.float64)) - shift
for direction in self._directions:
self.results[f"{direction}HistT{species}"][
self._frame_index] = self._histograms[direction](
positions, self.edges[direction])
for axis, key in enumerate(_CARTESIAN):
edges = self.edges[key]
outside = int(np.count_nonzero(
(positions[:, axis] < edges[0])
| (positions[:, axis] > edges[-1])))
if outside:
raise ValueError(
f"{outside} of {len(positions)} {species} positions "
f"fall outside the {key} edges "
f"[{edges[0]}, {edges[-1]}] in frame "
f"{self._ts.frame}.")
for plane in _PLANES:
self.results[f"{plane}HistBlock{species}"][block] += _planar(
positions, plane, self.edges)
def _conclude(self) -> None:
"""
Turn each block's summed map into its mean and sum the counts over
the frames.
"""
counts = self.results['blockFrames']
filled = counts > 0
for species in self.groups:
for direction in self._directions:
self.results[f"{direction}Hist{species}"] = self.results[
f"{direction}HistT{species}"].sum(axis=0)
for plane in _PLANES:
key = f"{plane}HistBlock{species}"
sums = self.results[key]
self.results[f"{plane}Hist{species}"] = sums.sum(axis=0)
means = np.zeros_like(sums)
means[filled] = sums[filled] / counts[filled, None, None]
self.results[key] = means
[docs]
def save(self, save_to: Pathish, name: str) -> list[Path]:
"""
Save the edges, histograms, and maps under the research code's names.
For each species ``S`` and direction ``d``: ``<name>-dEdgeS.npy``,
``<name>-dHistS.npy`` (summed over the frames), and
``<name>-dHistTS.npy`` (per frame); for each Cartesian axis ``c``:
``<name>-cEdge.npy``; for each plane ``p`` and species:
``<name>-pHistS.npy`` (summed) and ``<name>-pHistBlockS.npy`` (per
block); and ``<name>-blockFrames.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 ``'N200...ens1-all'``.
Returns
-------
list of pathlib.Path
The files written, in the order above.
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(1, trajectory=True)
>>> universe.load_new(np.array([[[1.0, 1.0, 1.0]]]), format='MEMORY',
... dimensions=np.array([[4.0, 4.0, 4.0, 90.0,
... 90.0, 90.0]]))
<Universe with 1 atoms>
>>> edges = {key: np.array([-2.0, 0.0, 2.0]) for key in 'xyz'}
>>> edges['r'] = np.array([0.0, 2.0, 4.0])
>>> analysis = SpatialHistograms(
... {'Mon': universe.atoms}, edges, geometry='cubic',
... block_frames=1).run()
>>> with tempfile.TemporaryDirectory() as tmp:
... paths = analysis.save(tmp, 'N1ens1-all')
... len(paths), paths[0].name, paths[-1].name
(13, 'N1ens1-all-rEdgeMon.npy', 'N1ens1-all-blockFrames.npy')
"""
if 'blockFrames' not in self.results:
raise RuntimeError("Call run() before save().")
folder = Path(save_to)
items: list[tuple[str, np.ndarray]] = []
for species in self.groups:
for direction in self._directions:
items.append((f"{direction}Edge{species}",
self.edges[direction]))
items.append((f"{direction}Hist{species}",
self.results[f"{direction}Hist{species}"]))
items.append((f"{direction}HistT{species}",
self.results[f"{direction}HistT{species}"]))
for key in _CARTESIAN:
items.append((f"{key}Edge", self.edges[key]))
for species in self.groups:
for plane in _PLANES:
items.append((f"{plane}Hist{species}",
self.results[f"{plane}Hist{species}"]))
items.append((f"{plane}HistBlock{species}",
self.results[f"{plane}HistBlock{species}"]))
items.append(('blockFrames', self.results['blockFrames']))
paths = []
for suffix, array in items:
path = folder / f"{name}-{suffix}.npy"
np.save(path, array)
paths.append(path)
return paths