polyphys 1.0.0__py3-none-any.whl

polyphys/probe/pairs.py

@@ -0,0 +1,555 @@
+"""
+==========================================================
+: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')
+
+
+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)
+
+    @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)
+
+    @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))
+
+    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

polyphys/simulate/__init__.py

@@ -0,0 +1,48 @@
+"""
+The `simulate` subpackage works with the files of the simulation engine,
+LAMMPS: it reads logs and dumps, reads and writes data files, and builds the
+start configurations a run begins from, sharing the box and the error types
+of :mod:`polyphys.simulate.core`.
+"""
+from polyphys.simulate import core
+from polyphys.simulate import log
+from polyphys.simulate import dump
+from polyphys.simulate import data
+from polyphys.simulate import build
+from polyphys.simulate.build import (
+    ConformationError,
+    ConformationReport,
+    chain_angles,
+    chain_bonds,
+    chain_data,
+    check_conformation,
+    helix,
+    plectoneme_ring,
+    resample_curve,
+)
+from polyphys.simulate.core import Box, LammpsFormatError
+from polyphys.simulate.data import (
+    BrokenDataError,
+    DataFile,
+    read_data,
+    with_frame,
+    write_data,
+)
+from polyphys.simulate.dump import (
+    BrokenDumpError,
+    DumpFrame,
+    iter_dump,
+    read_dump_frame,
+)
+from polyphys.simulate.log import BrokenLogError, LogFile, parse_log, read_log
+
+__all__ = [
+    "core", "log", "dump", "data", "build",
+    "Box", "LammpsFormatError",
+    "BrokenLogError", "LogFile", "parse_log", "read_log",
+    "BrokenDumpError", "DumpFrame", "iter_dump", "read_dump_frame",
+    "BrokenDataError", "DataFile", "read_data", "with_frame", "write_data",
+    "ConformationError", "ConformationReport", "chain_angles", "chain_bonds",
+    "chain_data", "check_conformation", "helix", "plectoneme_ring",
+    "resample_curve",
+]