Source code for polyphys.analyze.measurer

"""
==========================================================
:mod:`polyphys.analyze.measurer`
==========================================================


The :mod:`polyphys.analyze.measurer` module measures one frame of positions:
distances, sizes, and spans of a group of particles, the statistics of
independent samples, the volumes of a bead cut by planes or by a sphere, and
fixed-width bins and histograms of one frame.

Contents
========

Core geometric and structural measurements:
:func:`apply_pbc_orthogonal`, :func:`pair_distance`, :func:`end_to_end`,
:func:`transverse_size`, :func:`max_distance`, and :func:`fsd`.

Summary statistics:
:func:`simple_stats` and :func:`sem`.

Advanced geometric calculations:
:func:`sphere_sphere_intersection` and :func:`spherical_segment`.

Binning and histogram processing:
:func:`create_bin_edge_and_hist`, :func:`fixedsize_bins`,
:func:`radial_histogram`, :func:`radial_cyl_histogram`,
:func:`axial_histogram`, :func:`azimuth_cyl_histogram`, and
:func:`planar_cartesian_histogram`.

Number-density and volume-fraction conversions live in
:mod:`polyphys.manage.utils`.

References
==========
For Feret's statistical diameter:

- Wang Y, Teraoka I, Hansen FY, Peters GH, Hassager O. "A Theoretical Study of
  the Separation Principle in Size Exclusion Chromatography." Macromolecules
  2010, 43, 3, 1651-1659. https://doi.org/10.1021/ma902377g

For spherical segment calculations:

- Weisstein, Eric W. "Spherical Segment." From MathWorld--A Wolfram Web
  Resource. https://mathworld.wolfram.com/SphericalSegment.html

For sphere-sphere intersection:

- Weisstein, Eric W. "Sphere-Sphere Intersection." From MathWorld--A Wolfram
  Web Resource. https://mathworld.wolfram.com/Sphere-SphereIntersection.html
"""

from typing import Dict, Tuple, Optional, Union, Any, List, cast
import numpy as np

from ..manage.types import AxisT, EntityT, PropertyT, BinT
from ..manage.utils import invalid_keyword

__all__ = [
    'apply_pbc_orthogonal',
    'axial_histogram',
    'azimuth_cyl_histogram',
    'create_bin_edge_and_hist',
    'end_to_end',
    'fixedsize_bins',
    'fsd',
    'max_distance',
    'pair_distance',
    'planar_cartesian_histogram',
    'radial_cyl_histogram',
    'radial_histogram',
    'sem',
    'simple_stats',
    'sphere_sphere_intersection',
    'spherical_segment',
    'transverse_size',
]

# Relative tolerance for deciding whether a range holds a whole number of
# bins, used by :func:`create_bin_edge_and_hist` and :func:`fixedsize_bins`.
# The ratio ``(lmax - lmin) / bin_size`` is computed in float64, so a range
# that is exactly a whole number of bins can come out a few ulps above or
# below that integer (``2.1 / 0.3`` is ``7.000000000000001``). A plain
# ``ceil`` then adds a bin, and a plain comparison can leave the edges a few
# 1e-15 inside the range. The tolerance has to sit between two scales:
#
# - the accumulated round-off in the ratio, a few times the float64 epsilon
#   (2.2e-16), so below about 1e-15 relative;
# - the smallest deviation a user can intend, which is set by the precision of
#   the inputs: box sizes and bead diameters are read from filenames with at
#   most seven significant digits, so about 1e-7 relative.
#
# Any value between those classifies every realistic input correctly. 1e-9
# keeps six orders of magnitude from the round-off side and two from the
# intent side; the margins are unequal on purpose, because the two errors are
# not equally bad. Calling a true multiple a non-multiple adds a bin and, for
# 'ordinary' bins, shifts the whole grid by half a bin; calling an intended
# non-multiple a multiple moves the edges by less than
# ``1e-9 * (lmax - lmin)``.
_BIN_COUNT_RTOL = 1e-9


def _count_bins(length: float, bin_size: float) -> Tuple[int, float]:
    """
    Return the number of bins of width `bin_size` that cover `length`, and
    the excess length they add.

    When ``length / bin_size`` is a whole number up to the relative tolerance
    ``_BIN_COUNT_RTOL``, the count is that whole number and the excess is
    exactly ``0.0``; otherwise the count is the ceiling of the ratio and the
    excess ``n_bins * bin_size - length`` is strictly positive, by a margin
    far above float64 round-off.

    Parameters
    ----------
    length : float
        Length of the range to cover, positive.
    bin_size : float
        Width of each bin, positive.

    Returns
    -------
    Tuple[int, float]
        ``(n_bins, excess)``.

    Examples
    --------
    >>> _count_bins(2.1, 0.3)
    (7, 0.0)
    >>> n_bins, excess = _count_bins(2.0, 0.7)
    >>> n_bins, round(excess, 12)
    (3, 0.1)
    """
    ratio = length / bin_size
    n_bins = int(np.rint(ratio))
    if n_bins > 0 and np.isclose(
        ratio, n_bins, rtol=_BIN_COUNT_RTOL, atol=0.0
    ):
        return n_bins, 0.0
    n_bins = int(np.ceil(ratio))
    return n_bins, n_bins * bin_size - length


def _histogram_or_raise(values: np.ndarray, edges: np.ndarray) -> np.ndarray:
    """
    Histogram `values` over `edges`, raising if any value falls outside them.

    `np.histogram` silently drops values below the first edge or above the
    last one. For the spatial profiles this module serves, every position
    belongs to the system, so a dropped position is a defect in the caller's
    edges or an unwrapped coordinate, not data to ignore.

    Parameters
    ----------
    values : np.ndarray
        One-dimensional array of values to bin.
    edges : np.ndarray
        Monotonically increasing bin edges, including the rightmost edge.

    Returns
    -------
    np.ndarray
        Counts per bin, shape ``(len(edges) - 1,)``; their sum is
        ``values.size``.

    Raises
    ------
    ValueError
        If any value lies outside ``[edges[0], edges[-1]]``.

    Examples
    --------
    >>> edges = np.array([0., 1., 2., 3.])
    >>> _histogram_or_raise(np.array([0.5, 2.0, 3.0]), edges)
    array([1, 0, 2])
    >>> _histogram_or_raise(np.array([0.5, 9.0]), edges)
    Traceback (most recent call last):
        ...
    ValueError: 1 of 2 positions fall outside the edges [0.0, 3.0].
    """
    # Declared, not cast: numpy 2.5 stubs type these counts as Any and
    # numpy 2.3 stubs as an ndarray, where a cast is redundant.
    hist: np.ndarray
    hist, _ = np.histogram(values, bins=edges)
    n_missed = values.size - int(hist.sum())
    if n_missed:
        raise ValueError(
            f"{n_missed} of {values.size} positions fall outside the edges "
            f"[{edges[0]}, {edges[-1]}]."
        )
    return hist


[docs] def apply_pbc_orthogonal( pbc_lengths: np.ndarray, pbc_lengths_inverse: np.ndarray, pbc: Dict[AxisT, float], ) -> Tuple[np.ndarray, np.ndarray]: """ Write the box length and its inverse of each axis in `pbc` into the given arrays. The arrays are modified in place and also returned; an axis not in `pbc` keeps its value. Parameters ---------- pbc_lengths : numpy.ndarray The box length along each axis, shape ``(n_dim,)``, typically ``(3,)``, in the length unit of the positions; modified in place. pbc_lengths_inverse : numpy.ndarray The inverse box length along each axis, the same shape; modified in place. pbc : Dict[:py:obj:`~.AxisT`, float] Axis indices (0=x, 1=y, 2=z) mapped to their box lengths, positive. Returns ------- pbc_lengths : numpy.ndarray `pbc_lengths`, updated. pbc_lengths_inverse : numpy.ndarray `pbc_lengths_inverse`, updated. Raises ------ ZeroDivisionError If any specified length is zero, which would result in division by zero. ValueError If any specified length is negative, which is physically invalid for box dimensions. Examples -------- >>> pbc_lengths = np.zeros(3) >>> pbc_lengths_inverse = np.zeros(3) >>> pbc = {0: 10.0, 2: 20.0} >>> apply_pbc_orthogonal(pbc_lengths, pbc_lengths_inverse, pbc) (array([10., 0., 20.]), array([0.1 , 0. , 0.05])) """ for ax, length in pbc.items(): if length == 0.0: raise ZeroDivisionError(f"Length for axis {ax} cannot be zero.") if length < 0.0: raise ValueError( f"Length for axis {ax} must be positive; got {length}." ) pbc_lengths[ax] = length pbc_lengths_inverse[ax] = 1 / length return pbc_lengths, pbc_lengths_inverse
[docs] def pair_distance( positions: np.ndarray, pbc: Optional[Dict[AxisT, float]] = None ) -> np.ndarray: """ Compute the displacement vector from the first particle to the second, optionally under the minimum image convention. Parameters ---------- positions : numpy.ndarray The positions of the two particles, shape ``(2, n_dim)``; the order sets the sign of the result. Integer positions are converted to ``float64``. pbc : Optional[Dict[:py:obj:`~.AxisT`, float]], default None Dictionary with axis indices (0=x, 1=y, 2=z) as keys and box lengths as values. If provided, periodic boundary conditions (PBC) are applied along each axis with a finite length; an ``inf`` length leaves its axis non-periodic, as in :func:`polyphys.analyze.clusters.pair_distances`; see :mod:`polyphys.manage.types`. Returns ------- np.ndarray The signed displacement ``positions[1] - positions[0]`` along each axis, shape ``(n_dim,)``, ``float64``, in the length unit of `positions`; with `pbc`, each periodic component is folded into ``[-L/2, L/2]``. Raises ------ ValueError If `positions` does not contain exactly two sets of coordinates. Notes ----- The result is the component-wise displacement, not its Euclidean norm. Examples -------- >>> positions = np.array([[1.0, 2.0, 3.0], [4.0, 2.0, 3.0]]) >>> pair_distance(positions) array([3., 0., 0.]) >>> pbc = {0: 8.0} >>> positions = np.array([[1.0, 2.0, 3.0], [9.5, 2.0, 3.0]]) >>> pair_distance(positions, pbc) array([0.5, 0. , 0. ]) """ positions = np.asarray(positions, dtype=np.float64) n_atoms, n_dims = positions.shape if n_atoms != 2: raise ValueError("'pair_distance' only works for two atoms.") # Calculation in the center of geometry (cog) of the atom group. delta = positions[1] - positions[0] if pbc is not None: # Prepare length and inverse-length arrays pbc_lengths, pbc_lengths_inverse = apply_pbc_orthogonal( np.zeros(n_dims), np.zeros(n_dims), pbc ) # Apply the minimum image convention along the finite lengths; an # infinite length is not periodic, and inf * 0 would give NaN. periodic = np.isfinite(pbc_lengths) delta[periodic] -= pbc_lengths[periodic] * np.round( delta[periodic] * pbc_lengths_inverse[periodic] ) # cast: numpy's stubs return Any; at runtime this is an ndarray. return cast(np.ndarray, delta)
[docs] def end_to_end(positions: np.ndarray) -> Union[np.floating, np.ndarray]: """ Compute the end-to-end distance of a chain, the distance between its first and its last bead. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atomic positions, in backbone order from the first monomer to the last. Returns ------- numpy.floating The end-to-end distance, in the length unit of `positions`. Raises ------ ValueError If `positions` contains fewer than two atoms. Notes ----- The positions are centered on their center of geometry first; the distance does not depend on that translation. Examples -------- >>> positions = np.array([[0.0, 0.0, 0.0], ... [1.0, 0.0, 0.0], ... [2.0, 0.0, 0.0]]) >>> end_to_end(positions) np.float64(2.0) >>> positions = np.array([[1.0, 1.0, 1.0], ... [2.0, 2.0, 2.0], ... [3.0, 3.0, 3.0]]) >>> end_to_end(positions) np.float64(3.4641016151377544) """ # calculation in the center of geometry of the atom group. if positions.shape[0] < 2: raise ValueError("`positions` must contain at least two atoms.") centered_positions = positions - np.mean(positions, axis=0) # cast: numpy 2.5 stubs return Any; at runtime this is a NumPy floating # scalar, so the cast restates the annotation and changes nothing. return cast( Union[np.floating, np.ndarray], np.linalg.norm(centered_positions[-1] - centered_positions[0]), )
[docs] def transverse_size(positions: np.ndarray, axis: AxisT) -> float: """ Compute the transverse size of a group of atoms, twice their mean distance from their center in the plane perpendicular to `axis`. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atomic positions, in any order. axis : :py:obj:`~.AxisT` The axis (0 for x, 1 for y, and 2 for z) perpendicular to the plane in which the size is measured. Returns ------- float Twice the mean distance of the atoms from their center of geometry in the plane perpendicular to `axis`, a diameter, in the length unit of `positions`. Raises ------ IndexError If `axis` is out of bounds for `positions`. Notes ----- The distance is calculated in a reference frame centered at the center of geometry of atoms in the plane perpendicular to a given axis. Examples -------- >>> positions = np.array([[1, 0, 0], [1, 2, 2]]) >>> transverse_size(positions, axis=0) np.float64(2.8284271247461903) >>> transverse_size(positions, axis=1) np.float64(2.0) """ trans_axes = {0: [1, 2], 1: [0, 2], 2: [0, 1]} if axis >= positions.shape[1]: raise IndexError( f"Axis {axis} is out of bounds for positions array" f" with shape {positions.shape}." ) trans_pos = positions[:, trans_axes[axis]] - np.mean( positions[:, trans_axes[axis]], axis=0 ) # Times by 2, so we have the diameter not radius: # cast: numpy's stubs return Any. The value is a NumPy floating scalar # (np.float32 for float32 input), not always a float; the cast only # restates the existing annotation and changes nothing at runtime. return cast(float, 2 * np.mean(np.linalg.norm(trans_pos, axis=1)))
[docs] def max_distance(positions: np.ndarray) -> np.ndarray: """ Compute the extent of the positions along each Cartesian axis. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. Returns ------- np.ndarray The largest coordinate minus the smallest along each axis, shape ``(n_dim,)``, in the length unit of `positions`. Raises ------ ValueError If `positions` is empty. Notes ----- The positions are centered on their center of geometry first; the extent does not depend on that translation. Examples -------- >>> positions = np.array([[0, 0, 0], [4, 2, 6], [2, 3, 0]]) >>> max_distance(positions) array([4., 3., 6.]) """ # calculation in the center of geometry of the atom group. centered_positions = positions - np.mean(positions, axis=0) # cast: numpy's stubs return Any; at runtime this is an ndarray. return cast(np.ndarray, np.ptp(centered_positions, axis=0))
[docs] def fsd(positions: np.ndarray, axis: AxisT) -> float: """ Compute the span of the positions along the selected axis. The span is the largest coordinate minus the smallest along `axis`, for one configuration; nothing is averaged over frames or orientations. The name ``fsd`` is kept from Feret's statistical diameter, the caliper distance along a fixed direction. Parameters ---------- positions : np.ndarray Array of shape ``(n_atoms, n_dim)`` of atom positions, in any order; the span does not depend on it. axis : :py:obj:`~.AxisT` Axis index (0=x, 1=y, 2=z) along which to compute the span; see :mod:`polyphys.manage.types`. Returns ------- float The span along `axis`, in the units of `positions`. Raises ------ IndexError If `axis` is out of bounds for `positions`. References ---------- Wang Y, Teraoka I, Hansen FY, Peters GH, Hassager O. "A Theoretical Study of the Separation Principle in Size Exclusion Chromatography." Macromolecules 2010, 43, 3, 1651-1659. https://doi.org/10.1021/ma902377g Examples -------- >>> positions = np.array([[1, 2, 3], [4, 8, 6]]) >>> fsd(positions, axis=1) np.float64(6.0) """ if axis >= positions.shape[1]: raise IndexError( f"Axis {axis} is out of bounds for positions array" f" with shape {positions.shape}." ) # calculation in the center of geometry of the atom group: positions = positions - np.mean(positions, axis=0) # cast: numpy's stubs return Any. The value is a NumPy floating scalar # (np.float32 for float32 input), not always a float; the cast only # restates the existing annotation and changes nothing at runtime. return cast(float, np.ptp(positions[:, axis]))
[docs] def simple_stats( entity: EntityT, data: np.ndarray ) -> Dict[PropertyT, float | np.floating]: """ Compute basic statistics (mean, variance, SEM) for a physical `entity`. Parameters ---------- entity : EntityT The name that prefixes the keys of the result. data : np.ndarray One-dimensional array of independent samples. Returns ------- Dict[PropertyT, float | numpy.floating] The mean, the sample variance with ``ddof=1``, and the SEM, the sample standard deviation with ``ddof=1`` over the square root of the number of samples, keyed ``'<entity>_mean'``, ``'<entity>_var'``, and ``'<entity>_sem'``. Raises ------ ValueError If `data` is empty or holds one sample, whose unbiased variance divides by ``n - 1 = 0``. Examples -------- >>> import numpy as np >>> simple_stats('energy', np.array([1.0, 2.0, 3.0])) # noqa: E501 {'energy_mean': np.float64(2.0), 'energy_var': np.float64(1.0), 'energy_sem': np.float64(0.5773502691896258)} """ if len(data) == 0: raise ValueError('Input array must not be empty.') if len(data) < 2: raise ValueError( 'Input array must hold at least two samples for an unbiased' ' variance.' ) # Unbiased std, var, and sem. return { entity + '_mean': np.mean(data), entity + '_var': np.var(data, ddof=1), entity + '_sem': np.std(data, ddof=1) / np.sqrt(len(data)), }
[docs] def sem(data: np.ndarray) -> float: """ Compute the standard error of the mean (SEM) of independent samples. Parameters ---------- data : np.ndarray One-dimensional array of sample data. Returns ------- float The standard error of the mean, in the unit of `data`. Raises ------ ValueError If `data` is empty or holds one sample, whose sample standard deviation with ``ddof=1`` divides by ``n - 1 = 0``. Notes ----- SEM is calculated using sample standard deviation (ddof=1) and sample size. The estimate assumes independent samples, such as the means of independent replicates. For a time series of correlated frames it understates the error; use :func:`polyphys.analyze.stats.sem_blocked` instead. Examples -------- >>> import numpy as np >>> sem(np.array([1.0, 2.0, 3.0])) np.float64(0.5773502691896258) """ if len(data) == 0: raise ValueError('Input data array must not be empty.') if len(data) < 2: raise ValueError( 'Input data array must hold at least two samples for an unbiased' ' standard deviation.' ) # cast: numpy's stubs return Any. The value is a NumPy floating scalar # (np.float32 for float32 input), not always a float; the cast only # restates the existing annotation and changes nothing at runtime. return cast(float, np.std(data, ddof=1) / len(data) ** 0.5)
[docs] def spherical_segment(r: float, a: float, b: float) -> float: """ Compute the volume of a spherical segment defined by two parallel planes. Parameters ---------- r : float Radius of the sphere. Must be positive. a : float Distance of the first plane from the center of the sphere, along the axis of symmetry. b : float Distance of the second plane from the center of the sphere, along the axis of symmetry. Returns ------- vol : float Volume of the spherical segment. Raises ------ ValueError If `r` is not a positive number. Notes ----- - `a` and `b` can be positive or negative values, as long as they fall within the range `[-r, r]`. - The function will adjust `a` and `b` to `-r` or `r` if they exceed these bounds. - If `a = r` or `b = r`, the spherical segment becomes a spherical cap. - If both `a` and `b` lie outside the range `[-r, r]` and share the same sign, the volume is zero. References ---------- Weisstein, Eric W. "Spherical Segment." From MathWorld--A Wolfram Web Resource. https://mathworld.wolfram.com/SphericalSegment.html Examples -------- >>> spherical_segment(3, 1, 2) 20.94395102393195 >>> spherical_segment(3, -3, 3) 113.09733552923255 """ if r <= 0: raise ValueError(f"The radius 'r' must be positive. Got {r}.") # Ensure the bounds are within [-r, r] lower = max(min(a, b), -r) upper = min(max(a, b), r) # If both bounds are outside [-r, r] with the same sign, the volume is zero if lower * upper >= r**2: return 0.0 # Calculate the volume of the spherical segment vol = np.pi * (r**2 * (upper - lower) - (upper**3 - lower**3) / 3) return vol
[docs] def sphere_sphere_intersection(r1: float, r2: float, d: float) -> float: """ Compute the volume of intersection between two spheres. The sphere with radius `r1` is separated from the sphere with radius `r2` by a distance `d` along the x-axis. Thus, the vector form of the distance between their centers is `(d, 0, 0)` in Cartesian coordinates. Parameters ---------- r1 : float Radius of the first sphere. r2 : float Radius of the second sphere. d : float Distance between the centers of the two spheres along the x-axis. Returns ------- vol : float Volume of the intersection between the two spheres. References ---------- Weisstein, Eric W. "Sphere-Sphere Intersection." From MathWorld--A Wolfram Web Resource. https://mathworld.wolfram.com/Sphere-SphereIntersection.html Examples -------- >>> sphere_sphere_intersection(3, 4, 2) 94.90227807719167 >>> sphere_sphere_intersection(3, 4, 10) 0.0 """ r_max = max(r1, r2) r_min = min(r1, r2) # Volume is zero if one sphere has a radius of zero or no intersection # occurs: if r1 == 0.0 or r2 == 0.0: return 0.0 if d >= r_min + r_max: return 0.0 if d <= r_max - r_min: # The smaller sphere is entirely contained within the larger one return 4 * np.pi * r_min**3 / 3 # Calculate the intersection volume for overlapping spheres vol = ( (np.pi / (12 * d)) * (r_max + r_min - d) ** 2 * ( d**2 + 2 * d * (r_max + r_min) - 3 * (r_min**2 + r_max**2) + 6 * r_min * r_max ) ) return vol
[docs] def create_bin_edge_and_hist( bin_size: float, lmin: float, lmax: float, output: Optional[str] = None ) -> Tuple[np.ndarray, np.ndarray]: """ Create bin edges of a fixed width and a zero-filled histogram. The edges start at `lmin` and step by `bin_size` up to the first edge at or beyond `lmax`, so there are ``n_bins = ceil((lmax - lmin) / bin_size)`` bins of width `bin_size`. When the range is a whole number of bins up to the relative tolerance ``_BIN_COUNT_RTOL`` (1e-9), the last edge is exactly `lmax`; otherwise it exceeds `lmax` by less than one bin. Parameters ---------- bin_size : float Size of each bin. lmin : float Lower bound of the system in the direction of interest. lmax : float Upper bound of the system in the direction of interest. output : Optional[str], default None Filename (including filepath) to which bin edges array is saved. A `.npy` extension will be appended to the filename if it does not already have one. Returns ------- Tuple[np.ndarray, np.ndarray] - bin_edges : Array of bin edges, shape ``(n_bins + 1,)``, equal to ``lmin + bin_size * k`` for ``k = 0, ..., n_bins``. - hist : Zero-initialized histogram of dtype ``np.int64`` and shape ``(n_bins,)``. The 64-bit integer type keeps per-frame counts accumulated in place (``hist += np.histogram(...)[0]``) from overflowing. Raises ------ ValueError If `lmin` is not less than `lmax`. Notes ----- The `.npy` extension is handled internally by `np.save`. The edges come from `np.linspace`, so their number is exactly ``n_bins + 1``; a float-step `np.arange` can return one edge too many when `bin_size` is not exactly representable (for example 0.3). The bin count treats a ratio within 1e-9 of a whole number as that whole number; see ``_BIN_COUNT_RTOL`` for why. Time and space are O(`n_bins`). Examples -------- >>> edges, hist = \ create_bin_edge_and_hist(bin_size=1.0, lmin=0.0, lmax=5.0) >>> edges array([0., 1., 2., 3., 4., 5.]) >>> hist array([0, 0, 0, 0, 0]) A step that is not exactly representable still gives one edge per bin plus one, ending exactly at `lmax`: >>> edges, hist = create_bin_edge_and_hist(0.3, -6.0, 6.0) >>> print(len(edges), len(hist), edges[0], edges[-1]) 41 40 -6.0 6.0 A range that is not a multiple of `bin_size` is covered by one more bin: >>> create_bin_edge_and_hist(0.7, 0.0, 2.0)[0] array([0. , 0.7, 1.4, 2.1]) """ if lmin >= lmax: raise ValueError("'lmin' must be less than 'lmax'.") n_bins, excess = _count_bins(lmax - lmin, bin_size) upper = lmax if excess == 0.0 else lmin + n_bins * bin_size bin_edges = np.linspace(lmin, upper, n_bins + 1) hist = np.zeros(n_bins, dtype=np.int64) if output is not None: np.save(output, bin_edges) return bin_edges, hist
[docs] def fixedsize_bins( bin_size: float, lmin: float, lmax: float, bin_type: BinT = 'ordinary', save_bin_edges: Optional[str] = None, ) -> Dict[str, Any]: """ Generate bin edges and zero-filled histogram arrays with consistent bin width. Every bin type returns ``n_bins + 1`` equally spaced edges of width `bin_size` that cover [`lmin`, `lmax`]. Parameters ---------- bin_size : float Width of each bin. lmin : float Start of the range lmax : float End of the range bin_type : :py:obj:`~.BinT`, default 'ordinary' Type of binning. With ``n_bins = ceil((lmax - lmin) / bin_size)`` bins, the excess length ``n_bins * bin_size - (lmax - lmin)`` is zero when the range is a whole number of bins and is otherwise shared out as follows: - 'ordinary': Extends `lmin` and `lmax` symmetrically, by half the excess each. Examples are Cartesian coordinates and spherical polar coordinate. - 'nonnegative': Extends `lmin` and `lmax` symmetrically if the extended `lmin` stays nonnegative; otherwise `lmin` is set to 0 and `lmax` to ``n_bins * bin_size``. Examples are radial directions in the polar, spherical, and cylindrical coordinate systems. - 'periodic': Periodic binning over one period, ``lmax - lmin``, which must be a whole number of bins; the edges run from `lmin` to `lmax` exactly. Examples are azimuthal directions in cylindrical and spherical coordinate systems. See the Notes for how "a whole number of bins" is decided. See :mod:`polyphys.manage.types`. save_bin_edges : Optional[str], default None Filename (including filepath) to which bin edges array is saved. A `.npy` extension will be appended to the filename if it does not already have one. Returns ------- Dict[str, Any] Dictionary with keys: - 'n_bins' : int Number of bins. - 'bin_edges' : np.ndarray A monotonically increasing array of bin edges, including the rightmost edge. - 'collector' : np.ndarray Zero-initialized array of dtype ``np.int64`` and shape ``(n_bins,)`` for histogram counts. The 64-bit integer type keeps per-frame counts accumulated in place (``collector += np.histogram(...)[0]``) from overflowing. - 'collector_std' : np.ndarray Zero-initialized array of dtype ``np.float64`` and shape ``(n_bins,)`` for standard deviation values or the squared counts they are computed from. - 'range' : Tuple[float, float] Updated range of bins (`lmin`, `lmax`). Raises ------ ValueError If `lmin` is not less than `lmax`. ValueError If `bin_type` is 'nonnegative' and `lmin` is negative: clipping the lower end to zero would leave the range below zero uncovered. ValueError If `bin_type` is 'periodic' and ``lmax - lmin`` is not a multiple of `bin_size`. A last bin running past the period would cover values that never occur, so a density normalized by its width would be biased low. Notes ----- The `.npy` extension is handled internally by `np.save`. The edges come from `np.linspace`, so their number is exactly ``n_bins + 1``, and the first and last edges enclose `lmin` and `lmax` exactly: a position at either end of the range falls inside the bins, and `np.histogram` counts a value equal to the last edge in the last bin. **Deciding whether the range is a whole number of bins.** The ratio ``(lmax - lmin) / bin_size`` is computed in float64, so a range that is exactly a whole number of bins can come out a few ulps above or below that integer: ``2.1 / 0.3`` is ``7.000000000000001``, and ``530 * 0.03`` is a few 1e-15 below ``15.9``. Taking the ceiling of such a ratio adds a bin and, for 'ordinary' bins, shifts every edge by half a bin; comparing it directly can leave the end edges a few 1e-15 inside the range, where a position at exactly `lmin` or `lmax` is lost. The ratio is therefore compared with the nearest integer at the relative tolerance ``_BIN_COUNT_RTOL`` = 1e-9. That tolerance sits between the two scales that matter: the accumulated round-off in the ratio, a few times the float64 epsilon (about 1e-15), and the smallest deviation a user can intend, which the seven significant digits of the box sizes and bead diameters in the simulation filenames put at about 1e-7. It is closer to the intent side on purpose, because the two misclassifications are not equally bad: calling a true multiple a non-multiple adds a bin and shifts the grid, while calling an intended non-multiple a multiple moves the edges by less than ``1e-9 * (lmax - lmin)``. The symmetric extension of the 'ordinary' bins follows MDAnalysis's ``fixedwidth_bins``; the nearest-integer bin count departs from it, for the reasons above. Time and space are O(`n_bins`). References ---------- MDAnalysis ``lib.util.fixedwidth_bins``: https://github.com/MDAnalysis/mdanalysis/blob/ae9ff4b738606ba1e7c18a8a9b99a8a87eb69f74/package/MDAnalysis/lib/util.py#L1350 Examples -------- >>> result = fixedsize_bins(1.0, 0.0, 5.0) >>> result['n_bins'] 5 >>> result['bin_edges'] array([0., 1., 2., 3., 4., 5.]) A range that is a whole number of bins up to round-off is tiled exactly: >>> result = fixedsize_bins(0.3, 0.0, 2.1) >>> edges = result['bin_edges'] >>> print(result['n_bins'], edges[0], edges[-1]) 7 0.0 2.1 A radial range whose lower end would fall below zero is clipped there, and the bins keep their width: >>> result = fixedsize_bins(1.0, 0.1, 2.5, bin_type='nonnegative') >>> result['bin_edges'] array([0., 1., 2., 3.]) Azimuthal bins of 5 degrees span exactly one period: >>> result = fixedsize_bins(np.pi / 36, -np.pi, np.pi, bin_type='periodic') >>> print(result['n_bins'], result['bin_edges'][-1] == np.pi) 72 True """ if lmin >= lmax: raise ValueError("'lmin' must be less than 'lmax'.") _length = lmax - lmin _delta = bin_size n_bins, excess = _count_bins(_length, _delta) dl = 0.5 * excess # the excess length to share between the two ends if bin_type == 'ordinary': # add half of the excess to each end: lmin_adj = lmin - dl lmax_adj = lmax + dl elif bin_type == 'nonnegative': if lmin < 0.0: raise ValueError( "'lmin' must be nonnegative for the 'nonnegative' bin type." ) if lmin - dl < 0.0: # clip the lower end at zero and span n_bins full widths from it lmin_adj = 0.0 lmax_adj = n_bins * _delta else: lmin_adj = lmin - dl lmax_adj = lmax + dl elif bin_type == 'periodic': if excess != 0.0: raise ValueError( f"For the 'periodic' bin type, the period 'lmax - lmin' " f"({_length}) must be a multiple of 'bin_size' ({_delta})." ) lmin_adj, lmax_adj = lmin, lmax else: invalid_keyword(bin_type, ['ordinary', 'nonnegative', 'periodic']) bin_edges = np.linspace(lmin_adj, lmax_adj, n_bins + 1, endpoint=True) collectors = np.zeros(n_bins, dtype=np.int64) collectors_std = np.zeros(n_bins, dtype=np.float64) if save_bin_edges is not None: np.save(save_bin_edges, bin_edges) return { 'n_bins': n_bins, 'bin_edges': bin_edges, 'collector': collectors, 'collector_std': collectors_std, 'range': (lmin_adj, lmax_adj), }
[docs] def radial_histogram( positions: np.ndarray, edges: np.ndarray, ) -> np.ndarray: """ Bin the distances of the positions from the origin, the spherical radial coordinate. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. edges : np.ndarray A monotonically increasing array of bin edges, including the rightmost edge. The last bin includes its right edge. Every position must lie within the outermost edges: a coordinate along a periodic axis must already be wrapped into the box, since this function does not wrap. Returns ------- hist : np.ndarray The counts per bin, shape ``(len(edges) - 1,)``, integer. Raises ------ ValueError If the positions array is not two-dimensional. ValueError If any position falls outside the outermost edges. `np.histogram` would drop it silently; here a dropped position means wrong edges or an unwrapped coordinate, so it is an error. Examples -------- >>> positions= np.array([[1, 0, 0], [0, 1, 0], [0, 0, 2]]) >>> edges = np.array([0, 1, 2, 3]) >>> radial_histogram(positions, edges) array([0, 2, 1]) """ if positions.ndim != 2: raise ValueError( "'positions' must be a 2D array with shape (n_atoms, n_dim)." ) rad_distances = np.linalg.norm(positions, axis=1) return _histogram_or_raise(rad_distances, edges)
[docs] def radial_cyl_histogram( positions: np.ndarray, edges: np.ndarray, dim: AxisT, ) -> np.ndarray: """ Bin the distances of the positions from the axis along `dim`, the cylindrical radial coordinate. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. edges : np.ndarray A monotonically increasing array of bin edges, including the rightmost edge. The last bin includes its right edge. Every position must lie within the outermost edges: a coordinate along a periodic axis must already be wrapped into the box, since this function does not wrap. dim : :py:obj:`~.AxisT` Axis direction (0=x, 1=y, 2=z); see :mod:`polyphys.manage.types`. Returns ------- hist : np.ndarray The counts per bin, shape ``(len(edges) - 1,)``, integer. Raises ------ ValueError If `dim` is not one of {0, 1, 2}. ValueError If the positions array is not two-dimensional. ValueError If any position falls outside the outermost edges. `np.histogram` would drop it silently; here a dropped position means wrong edges or an unwrapped coordinate, so it is an error. Examples -------- >>> import numpy as np >>> positions = np.array([[1, 0, 0], [0, 2, 0], [0, 0, 3], [0, 3, 4]]) >>> edges = np.array([0, 1, 2, 3, 4]) >>> radial_cyl_histogram(positions, edges, dim=1) array([1, 1, 0, 2]) """ if dim not in {0, 1, 2}: raise ValueError("'dim' must be one of {0, 1, 2}.") if positions.ndim != 2: raise ValueError( "'positions' must be a 2D array with shape (n_atoms, n_dim)." ) trans_axes = np.roll(np.arange(3), -dim)[1:] # selecting transverse axes trans_distances = np.linalg.norm(positions[:, trans_axes], axis=1) return _histogram_or_raise(trans_distances, edges)
[docs] def axial_histogram( positions: np.ndarray, edges: np.ndarray, dim: AxisT, ) -> np.ndarray: """ Bin signed coordinates along the selected axis `dim`. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. edges : np.ndarray A monotonically increasing array of bin edges, including the rightmost edge. The last bin includes its right edge. Every position must lie within the outermost edges: a coordinate along a periodic axis must already be wrapped into the box, since this function does not wrap. dim : :py:obj:`~.AxisT` The longitudinal axis (0=x, 1=y, 2=z); see :mod:`polyphys.manage.types`. Returns ------- hist : np.ndarray The counts per bin, shape ``(len(edges) - 1,)``, integer. Raises ------ ValueError If `dim` is not one of {0, 1, 2}. ValueError If the positions array is not two-dimensional. ValueError If any position falls outside the outermost edges. `np.histogram` would drop it silently; here a dropped position means wrong edges or an unwrapped coordinate, so it is an error. Examples -------- >>> positions= np.array([[1, 2, 3], [2, 3, 4], [1, 2, 2]]) >>> edges = np.array([0, 1, 2, 3, 4, 5]) >>> axial_histogram(positions, edges, dim=0) array([0, 2, 1, 0, 0]) """ if dim not in {0, 1, 2}: raise ValueError("'dim' must be one of {0, 1, 2}.") if positions.ndim != 2: raise ValueError( "'positions' must be a 2D array with shape (n_atoms, n_dim)." ) return _histogram_or_raise(positions[:, dim], edges)
[docs] def azimuth_cyl_histogram( positions: np.ndarray, edges: np.ndarray, dim: AxisT, ) -> np.ndarray: """ Bin the azimuthal angles of the positions about the axis along `dim`, in radians. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. edges : np.ndarray A monotonically increasing array of bin edges, in radians, including the rightmost edge; the angles lie in ``[-pi, pi]``, as :obj:`numpy.arctan2` returns them. The last bin includes its right edge. Every position must lie within the outermost edges: a coordinate along a periodic axis must already be wrapped into the box, since this function does not wrap. dim : :py:obj:`~.AxisT` The longitudinal axis (0=x, 1=y, 2=z); see :mod:`polyphys.manage.types`. Returns ------- hist : np.ndarray The counts per bin, shape ``(len(edges) - 1,)``, integer. Raises ------ ValueError If `dim` is not one of {0, 1, 2}. ValueError If the positions array is not two-dimensional. ValueError If any position falls outside the outermost edges. `np.histogram` would drop it silently; here a dropped position means wrong edges or an unwrapped coordinate, so it is an error. Examples -------- >>> positions= np.array([[1, 0, 0], [0, 1, 0], [-1, 0, 0]]) >>> edges = np.linspace(-np.pi, np.pi, 5) >>> azimuth_cyl_histogram(positions, edges, dim=2) array([0, 0, 1, 2]) """ if dim not in {0, 1, 2}: raise ValueError("'dim' must be one of {0, 1, 2}.") if positions.ndim != 2: raise ValueError( "'positions' must be a 2D array with shape (n_atoms, n_dim)." ) transverse_axes = np.roll(np.arange(3), -dim)[1:] azimuthal_angles = np.arctan2( positions[:, transverse_axes[1]], positions[:, transverse_axes[0]] ) return _histogram_or_raise(azimuthal_angles, edges)
[docs] def planar_cartesian_histogram( positions: np.ndarray, edges: List[np.ndarray], dim: AxisT, ) -> np.ndarray: """ Compute a two-dimensional histogram in the plane perpendicular to `dim`, in Cartesian coordinates. Parameters ---------- positions : np.ndarray Array of shape (n_atoms, n_dim) containing atom positions, in any order. edges : List[np.ndarray] Two monotonically increasing arrays of bin edges, one per planar axis, each including its rightmost edge. The last bin along each axis includes its right edge. Every position must lie within the outermost edges along both axes: a coordinate along a periodic axis must already be wrapped into the box, since this function does not wrap. dim : :py:obj:`~.AxisT` Cartesian axis (0=x, 1=y, 2=z). The right-hand rule is used to pass the planar axes to the `np.histogram2d`: When `dim=0` (x), `dim=1` (y) and `dim=2` (z) values are passed respectively. When `dim=1` (y), `dim=2` (z) and `dim=0` (x) values are passed respectively. When `dim=2` (z), `dim=0` (x) and `dim=1` (y) values are passed respectively. See :mod:`polyphys.manage.types`. Returns ------- hist : np.ndarray The counts per cell, shape ``(len(edges[0]) - 1, len(edges[1]) - 1)``, ``float64``, as :func:`numpy.histogram2d` returns them, with rows along the first planar axis. Raises ------ ValueError If `dim` is not one of {0, 1, 2}. ValueError If the positions array is not two-dimensional. ValueError If any position falls outside the outermost edges. `np.histogram` would drop it silently; here a dropped position means wrong edges or an unwrapped coordinate, so it is an error. ValueError If the length of `edges` is not two. Examples -------- >>> positions= np.array([[1, 1, 0], [2, 2, 0], [3, 3, 0]]) >>> edges = [np.array([0, 2, 4]), np.array([0, 2, 4])] >>> planar_cartesian_histogram(positions, edges, dim=2) array([[1., 0.], [0., 2.]]) """ if dim not in {0, 1, 2}: raise ValueError("'dim' must be one of {0, 1, 2}.") if positions.ndim != 2: raise ValueError( "'positions' must be a 2D array with shape (n_atoms, n_dim)." ) if len(edges) != 2: raise ValueError("'edges' must contain two arrays, one for each axis.") t_dims = np.roll(np.arange(3), -dim)[1:] # selecting transverse axes hist, _, _ = np.histogram2d( positions[:, t_dims[0]], positions[:, t_dims[1]], bins=edges, ) n_missed = len(positions) - int(hist.sum()) if n_missed: raise ValueError( f"{n_missed} of {len(positions)} positions fall outside the " f"edges [{edges[0][0]}, {edges[0][-1]}] x " f"[{edges[1][0]}, {edges[1][-1]}]." ) # cast: numpy's stubs return Any; at runtime this is an ndarray. return cast(np.ndarray, hist)