MolClusters 0.7.0__py3-none-any.whl

molclusters/__init__.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: © 2024 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""MolClusters: A Python tool for analyzing cluster formation in molecular dynamics simulations.
+
+This module provides functionality to study and analyze the formation of molecular clusters
+from simulation data. It includes tools for processing and analyzing cluster
+dynamics, enabling researchers to gain insights into molecular behavior of clusters.
+
+Attributes
+----------
+    __version__ (str): The version of the MolClusters package.
+    version (str): The version of the MolClusters package.
+
+Modules
+-------
+    cluster: The `MolGroup` and `Cluster` classes that analyses read.
+    molclusters: Core module defining the main `MolClusters` class.
+    tracker: The `ClusterTracker`, which keeps cluster ids stable over a trajectory.
+    analysis: The analyses run on the tracked clusters, and their `FrameAnalysis` base.
+    output: The files the analyses write.
+
+Exports
+-------
+    MolClusters: The primary class for performing cluster analysis.
+    ClusterTracker: Follows the clusters of a trajectory, without analysing them.
+    Transition: How the clusters of a frame came from those of the frame before.
+    FrameAnalysis: The base class of an analysis, to pass to `MolClusters`.
+    Frame, Run: What an analysis sees of the current frame and of the run.
+    OutputFile: The declaration of a file an analysis writes.
+    Cluster, MolGroup: A tracked cluster, and any group of molecules (e.g. a nucleus).
+    start_logging: Function to set up molclusters logger.
+
+Example
+-------
+    >>> from molclusters import MolClusters
+    >>> analyzer = MolClusters(universe, config)
+    >>> analyzer.run()
+"""
+
+from loguru import logger
+
+logger.disable("molclusters")
+
+from . import cluster as cluster
+from .analysis import Frame, FrameAnalysis, Run
+from .cluster import Cluster, MolGroup
+from .log import start_logging
+from .molclusters import MolClusters
+from .output import OutputFile
+from .tracker import ClusterTracker, Transition
+from .version import __version__, version
+
+__all__ = [
+    "version",
+    "__version__",
+    "start_logging",
+    "MolClusters",
+    "ClusterTracker",
+    "Transition",
+    "FrameAnalysis",
+    "Frame",
+    "Run",
+    "OutputFile",
+    "Cluster",
+    "MolGroup",
+]

molclusters/__main__.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: © 2024 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Entry point for the `molclusters` package.
+
+The module imports and executes the `main` function from the `main` module,
+serving as the starting point for the application when run as a script.
+
+Usage:
+    To execute the `molclusters` application, run this module directly.
+
+Example:
+    molclusters -h
+"""
+
+from .main import main
+
+main()

molclusters/analysis/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: © 2026 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""The analyses run on the tracked clusters, each a `FrameAnalysis`.
+
+Modules
+-------
+    base: `FrameAnalysis`, and the `Run` and `Frame` an analysis sees.
+    builtins: `BUILTINS`, the built-in analyses in the order they run, and what
+      each needs from the config.
+    coordinates: `ClusterCoordinates`, the clusters holding solutes (.gro files).
+    lineage: `Lineage`, where the clusters came from, what became of them and when
+      (cluster_events.csv, cluster_lifetimes.csv).
+    nucleus: `Nucleus`, the nuclei inside the clusters (nucleus_data.csv).
+    report: `JsonReport`, every cluster of every frame (molclusters.jsonl).
+    size: `SizeEvolution`, the number and sizes of the clusters over time (evo.txt).
+    solute: `SoluteSolvent`, the clusters holding solutes and solvents
+      (solute_solvent.csv).
+"""
+
+from .base import Frame, FrameAnalysis, Run
+from .coordinates import ClusterCoordinates
+from .lineage import Lineage
+from .nucleus import Nucleus
+from .report import JsonReport
+from .size import SizeEvolution
+from .solute import SoluteSolvent
+
+__all__ = [
+    "ClusterCoordinates",
+    "Frame",
+    "FrameAnalysis",
+    "JsonReport",
+    "Lineage",
+    "Nucleus",
+    "Run",
+    "SizeEvolution",
+    "SoluteSolvent",
+]

molclusters/analysis/base.py

@@ -0,0 +1,370 @@
+# SPDX-FileCopyrightText: © 2026 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Provides `FrameAnalysis`, the base of the analyses run on the tracked clusters.
+
+Classes:
+--------
+- FrameAnalysis: The base class of an analysis, run frame by frame.
+- Run: What an analysis sees of the run as a whole.
+- Frame: What an analysis sees of the current frame.
+"""
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Generator, Mapping, Sequence
+from contextlib import contextmanager
+from types import MappingProxyType
+from typing import Any
+
+import MDAnalysis as mda
+from loguru import logger
+
+from ..cluster import Cluster
+from ..config import MolClsConfig
+from ..output import OutputFile, RunOutput
+from ..tracker import ClusterTracker, Transition
+
+
+class FrameAnalysis(ABC):
+    """An analysis of the tracked clusters, run frame by frame.
+
+    A run calls `prepare` once, then `analyse` for every frame (the first one
+    included) once the clusters are up to date with it, and finally `finish`.
+    The analyses of a run are called in order, so an analysis sees the results of
+    the ones before it for the same frame.
+
+    Only `analyse` must be implemented. An analysis keeps its results as its own
+    attributes; one that writes files does so through `Run.output` and declares
+    them in `outputs`. The same analysis may be run more than once, so it should
+    start its results over in `prepare`, not only in ``__init__``.
+
+    An analysis logs with loguru's ``logger``, as the rest of the package does;
+    the run tags whatever is logged during its hooks with its class name (the
+    ``analysis`` key of the record's ``extra``), which the log shows. To keep the
+    log readable over long trajectories:
+
+    - `analyse` counts what's worth reporting (e.g. in a `collections.Counter`)
+      instead of logging it, and `finish` logs a summary: one INFO line, or one
+      warning saying how to fix the problem.
+    - Anything logged per frame is DEBUG or TRACE, with loguru's own arguments
+      (``logger.debug("cluster {}: ...", cls.id)``) rather than an f-string: a
+      message filtered out by the log level is then never built.
+    - A warning that could repeat is only logged once.
+
+    An analysis adds its own fields to the JSON report (`JsonReport`, which runs
+    after every other analysis) by overriding `report_frame`, `report_cluster`, or
+    both: what they return goes in each frame's, or each cluster's, record under
+    the analysis' class name, its floats rounded as the report's are.
+
+    Attributes
+    ----------
+    outputs : tuple[OutputFile, ...]
+        The files the analysis writes, to tell which results of an earlier run
+        they overwrite (or leave behind), and to report them at the end.
+        Usually a class attribute; an analysis whose files depend on its options
+        sets it in ``__init__`` instead, since it's read before `prepare`.
+    """
+
+    outputs: tuple[OutputFile, ...] = ()
+
+    def prepare(self, run: "Run") -> None:  # noqa: B027 (optional hook)
+        """Get ready for a run, starting over any results. Does nothing unless overridden.
+
+        Parameters
+        ----------
+        run : Run
+            The run about to start.
+        """
+
+    @abstractmethod
+    def analyse(self, frame: "Frame") -> None:
+        """Analyse the clusters of the current frame.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        """
+
+    def finish(self, run: "Run") -> None:  # noqa: B027 (optional hook)
+        """Wrap up once every frame was analysed. Does nothing unless overridden.
+
+        Parameters
+        ----------
+        run : Run
+            The run that just ended.
+        """
+
+    def report_frame(self, frame: "Frame") -> Mapping[str, Any] | None:
+        """Give what to add to the report's record of the current frame.
+
+        Called by `JsonReport` after every analysis has analysed the frame.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+
+        Returns
+        -------
+        Mapping[str, Any] | None
+            The fields to add under the analysis' class name: JSON types, and numpy
+            scalars or arrays. None adds nothing (the default).
+        """
+        return None
+
+    def report_cluster(
+        self, frame: "Frame", cluster: Cluster
+    ) -> Mapping[str, Any] | None:
+        """Give what to add to the report's record of a cluster of the current frame.
+
+        Called by `JsonReport`, for every cluster of the frame, after every analysis
+        has analysed the frame.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        cluster : Cluster
+            The cluster.
+
+        Returns
+        -------
+        Mapping[str, Any] | None
+            The fields to add under the analysis' class name: JSON types, and numpy
+            scalars or arrays. None adds nothing (the default).
+        """
+        return None
+
+
+class Run:
+    """What an analysis sees of the run as a whole.
+
+    Attributes
+    ----------
+    universe : mda.Universe
+        The Universe being analysed.
+    config : MolClsConfig
+        The analysis configuration.
+    n_frames : int
+        The number of frames of the run.
+    output : RunOutput
+        Where the analyses write their files.
+    durations : list[float]
+        The time spent in each analysis' hooks so far, in seconds, in the order of
+        the analyses.
+    """
+
+    __slots__ = [
+        "universe",
+        "config",
+        "n_frames",
+        "output",
+        "durations",
+        "_analyses",
+        "_visible",
+    ]
+
+    def __init__(
+        self,
+        universe: mda.Universe,
+        config: MolClsConfig,
+        n_frames: int,
+        output: RunOutput,
+        analyses: Sequence[FrameAnalysis],
+    ) -> None:
+        """Initialize the context of a run.
+
+        Parameters
+        ----------
+        universe : mda.Universe
+            The Universe being analysed.
+        config : MolClsConfig
+            The analysis configuration.
+        n_frames : int
+            The number of frames of the run.
+        output : RunOutput
+            Where the analyses write their files.
+        analyses : Sequence[FrameAnalysis]
+            The analyses of the run, in the order they're called.
+        """
+        self.universe = universe
+        self.config = config
+        self.n_frames = n_frames
+        self.output = output
+        self.durations = [0.0] * len(analyses)
+        self._analyses = analyses
+        self._visible = len(analyses)
+
+    def prepare_analyses(self) -> None:
+        """Prepare every analysis of the run, in order (called by the runner)."""
+        for i, analysis in enumerate(self._analyses):
+            self._visible = i
+            with self._hook(i, "prepare"):
+                analysis.prepare(self)
+        self._visible = len(self._analyses)
+
+    def analyse_frame(self, frame: "Frame") -> None:
+        """Run every analysis of the run on `frame`, in order (called by the runner).
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        """
+        for i, analysis in enumerate(self._analyses):
+            with self._hook(i, "analyse", frame.index):
+                analysis.analyse(frame)
+
+    def finish_analyses(self) -> None:
+        """Finish every analysis of the run, in order (called by the runner)."""
+        for i, analysis in enumerate(self._analyses):
+            with self._hook(i, "finish"):
+                analysis.finish(self)
+
+    @property
+    def analyses(self) -> tuple[FrameAnalysis, ...]:
+        """The analyses of the run, in order; while preparing, only those before.
+
+        Returns
+        -------
+        tuple[FrameAnalysis, ...]
+            The analyses whose results `analysis` finds (see there).
+        """
+        return tuple(self._analyses[: self._visible])
+
+    def analysis[T: FrameAnalysis](self, kind: type[T]) -> T | None:
+        """Find the first analysis of the run of type `kind`, for its results.
+
+        While the analyses are being prepared, only those before the one being
+        prepared are found, since only their results for a frame are ready when
+        it analyses the frame.
+
+        Parameters
+        ----------
+        kind : type[T]
+            The analysis class to look for (subclasses match too).
+
+        Returns
+        -------
+        T | None
+            The analysis, or None if the run has none (before this one).
+        """
+        for analysis in self._analyses[: self._visible]:
+            if isinstance(analysis, kind):
+                return analysis
+        return None
+
+    @contextmanager
+    def _hook(
+        self, i: int, hook: str, frame: int | None = None
+    ) -> Generator[None, None, None]:
+        """Call a hook of the `i`-th analysis: tag its log, time it, blame its errors.
+
+        What's logged during the call is tagged with the analysis' class name, and
+        an error it raises is noted with it, so either can be told from the run's
+        own; the time taken is added to `durations`.
+
+        Parameters
+        ----------
+        i : int
+            The index of the analysis being called.
+        hook : str
+            The name of the method being called.
+        frame : int | None
+            The index of the frame being analysed, if any.
+
+        Yields
+        ------
+        None
+            Control, for the call to the analysis.
+        """
+        name = type(self._analyses[i]).__name__
+        start = time.perf_counter()
+        try:
+            with logger.contextualize(analysis=name):
+                yield
+        except Exception as err:
+            where = "" if frame is None else f" on frame {frame}"
+            err.add_note(f"Raised by {name}.{hook}(){where}")
+            raise
+        finally:
+            self.durations[i] += time.perf_counter() - start
+
+
+class Frame:
+    """What an analysis sees of the current frame.
+
+    Attributes
+    ----------
+    index : int
+        The index of the frame in the run (0 for its first frame).
+    time : float
+        The time of the frame, as the trajectory reports it.
+    universe : mda.Universe
+        The Universe, positioned at this frame.
+    output : RunOutput
+        Where the run's analyses write their files (the same as `Run.output`),
+        e.g. to append this frame to a file.
+    """
+
+    __slots__ = ["index", "time", "universe", "output", "_tracker"]
+
+    def __init__(self, index: int, tracker: ClusterTracker, output: RunOutput) -> None:
+        """Initialize the current frame of a run.
+
+        Parameters
+        ----------
+        index : int
+            The index of the frame in the run.
+        tracker : ClusterTracker
+            The tracker, up to date with the frame.
+        output : RunOutput
+            Where the run's analyses write their files.
+        """
+        self.index = index
+        self.time: float = tracker.uni.coord.time
+        self.universe = tracker.uni
+        self.output = output
+        self._tracker = tracker
+
+    @property
+    def clusters(self) -> Mapping[int, Cluster]:
+        """The clusters of the frame, keyed by cluster id (read-only).
+
+        Returns
+        -------
+        Mapping[int, Cluster]
+            A read-only view of the clusters; the clusters must not be modified.
+        """
+        return MappingProxyType(self._tracker.clusters)
+
+    @property
+    def transition(self) -> Transition:
+        """How the frame's clusters came from the previous frame's.
+
+        Returns
+        -------
+        Transition
+            Where each cluster's molecules came from, which clusters are new, and
+            which ended, merged or dissolved (on the run's first frame, every
+            cluster is new).
+        """
+        return self._tracker.transition
+
+    def find(self, mol: int) -> int | None:
+        """Find the id of the cluster a molecule belongs to.
+
+        Parameters
+        ----------
+        mol : int
+            The molecule's resid.
+
+        Returns
+        -------
+        int | None
+            The cluster id, or None if the molecule is in no cluster.
+        """
+        return self._tracker.find(mol)

molclusters/analysis/builtins.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: © 2026 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Provides `BUILTINS`, the built-in analyses, in the order they run.
+
+Classes:
+--------
+- Builtin: A built-in analysis, how the config builds it and what it needs.
+
+Functions:
+----------
+- build_builtins: Build the built-in analyses a config runs.
+
+A built-in runs unless the config's `analyses` turns it off (by class name),
+and only when the config options it needs are set. Adding one takes a line in
+`BUILTINS`; the config checks `analyses` against it. They run in its order, the
+report last (after the analyses given to `MolClusters` too).
+"""
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from ..config import MolClsConfig
+from .base import FrameAnalysis
+from .coordinates import ClusterCoordinates
+from .lineage import Lineage
+from .nucleus import Nucleus
+from .report import JsonReport
+from .size import SizeEvolution
+from .solute import SoluteSolvent
+
+
+@dataclass(frozen=True, slots=True)
+class Builtin:
+    """A built-in analysis, how the config builds it and what it needs.
+
+    Attributes
+    ----------
+    kind : type[FrameAnalysis]
+        The analysis class; its name turns it on or off in the config's `analyses`.
+    build : Callable[[MolClsConfig], FrameAnalysis]
+        Builds the analysis from the config, once the options it needs are set.
+    needs : tuple[str, ...]
+        The config options it needs, without which it doesn't run.
+    last : bool
+        Whether it runs after every other analysis, the ones given to
+        `MolClusters` included: the report, which the others add to.
+    """
+
+    kind: type[FrameAnalysis]
+    build: Callable[[MolClsConfig], FrameAnalysis]
+    needs: tuple[str, ...] = ()
+    last: bool = False
+
+    @property
+    def name(self) -> str:
+        """The analysis' class name, as the config's `analyses` and the log name it.
+
+        Returns
+        -------
+        str
+            E.g. ``"JsonReport"``.
+        """
+        return self.kind.__name__
+
+    def runs(self, config: MolClsConfig) -> bool:
+        """Whether the config runs this analysis.
+
+        Parameters
+        ----------
+        config : MolClsConfig
+            The analysis configuration.
+
+        Returns
+        -------
+        bool
+            True unless `analyses` turns it off or an option it needs isn't set.
+        """
+        return config.analyses.get(self.name, True) and all(
+            getattr(config, option) is not None for option in self.needs
+        )
+
+
+BUILTINS: tuple[Builtin, ...] = (
+    Builtin(SizeEvolution, lambda c: SizeEvolution()),
+    Builtin(Lineage, lambda c: Lineage()),
+    Builtin(
+        SoluteSolvent, lambda c: SoluteSolvent(c.solute, c.solvent), needs=("solute",)
+    ),
+    Builtin(
+        ClusterCoordinates,
+        lambda c: ClusterCoordinates(c.solute, follow=c._follow_solute),
+        needs=("solute",),
+    ),
+    Builtin(Nucleus, lambda c: Nucleus(c.nucleus), needs=("nucleus",)),
+    Builtin(JsonReport, lambda c: JsonReport(c.report_compression), last=True),
+)
+
+
+def build_builtins(
+    config: MolClsConfig, extra: Iterable[FrameAnalysis] = ()
+) -> list[FrameAnalysis]:
+    """Build the built-in analyses a config runs, and order them with `extra`.
+
+    Parameters
+    ----------
+    config : MolClsConfig
+        The analysis configuration, with the topology-dependent defaults filled in.
+    extra : Iterable[FrameAnalysis]
+        Other analyses to run, after the built-ins but those that run `last`.
+
+    Returns
+    -------
+    list[FrameAnalysis]
+        The analyses in the order they run: the built-ins the config runs (see
+        `Builtin.runs`), then `extra`, then the built-ins that run last.
+    """
+    built = [(b.last, b.build(config)) for b in BUILTINS if b.runs(config)]
+    return [
+        *(analysis for last, analysis in built if not last),
+        *extra,
+        *(analysis for last, analysis in built if last),
+    ]