imdclient 0.1.3__py3-none-any.whl → 0.2.0b0__py3-none-any.whl

imdclient/backends.py

@@ -1,352 +0,0 @@
-# Copy of backends from MDA 2.8.0
-"""Analysis backends --- :mod:`MDAnalysis.analysis.backends`
-============================================================
-
-.. versionadded:: 2.8.0
-
-
-The :mod:`backends` module provides :class:`BackendBase` base class to
-implement custom execution backends for
-:meth:`MDAnalysis.analysis.base.AnalysisBase.run` and its
-subclasses.
-
-.. SeeAlso:: :ref:`parallel-analysis`
-
-.. _backends:
-
-Backends
---------
-
-Three built-in backend classes are provided:
-
-* *serial*: :class:`BackendSerial`, that is equivalent to using no
-  parallelization and is the default
-
-* *multiprocessing*: :class:`BackendMultiprocessing` that supports
-  parallelization via standard Python :mod:`multiprocessing` module
-  and uses default :mod:`pickle` serialization
-
-* *dask*: :class:`BackendDask`, that uses the same process-based
-  parallelization as :class:`BackendMultiprocessing`, but different
-  serialization algorithm via `dask <https://dask.org/>`_ (see `dask
-  serialization algorithms
-  <https://distributed.dask.org/en/latest/serialization.html>`_ for details)
-
-Classes
--------
-
-"""
-import warnings
-from typing import Callable
-import importlib.util
-
-
-def is_installed(modulename: str):
-    """Checks if module is installed
-
-    Parameters
-    ----------
-    modulename : str
-        name of the module to be tested
-
-
-    .. versionadded:: 2.8.0
-    """
-    return importlib.util.find_spec(modulename) is not None
-
-
-class BackendBase:
-    """Base class for backend implementation.
-
-    Initializes an instance and performs checks for its validity, such as
-    ``n_workers`` and possibly other ones.
-
-    Parameters
-    ----------
-    n_workers : int
-        number of workers (usually, processes) over which the work is split
-
-    Examples
-    --------
-    .. code-block:: python
-
-        from MDAnalysis.analysis.backends import BackendBase
-
-        class ThreadsBackend(BackendBase):
-            def apply(self, func, computations):
-                from multiprocessing.dummy import Pool
-
-                with Pool(processes=self.n_workers) as pool:
-                    results = pool.map(func, computations)
-                return results
-
-        import MDAnalysis as mda
-        from MDAnalysis.tests.datafiles import PSF, DCD
-        from MDAnalysis.analysis.rms import RMSD
-
-        u = mda.Universe(PSF, DCD)
-        ref = mda.Universe(PSF, DCD)
-
-        R = RMSD(u, ref)
-
-        n_workers = 2
-        backend = ThreadsBackend(n_workers=n_workers)
-        R.run(backend=backend, unsupported_backend=True)
-
-    .. warning::
-        Using `ThreadsBackend` above will lead to erroneous results, since it
-        is an educational example. Do not use it for real analysis.
-
-
-    .. versionadded:: 2.8.0
-
-    """
-
-    def __init__(self, n_workers: int):
-        self.n_workers = n_workers
-        self._validate()
-
-    def _get_checks(self):
-        """Get dictionary with ``condition: error_message`` pairs that ensure the
-        validity of the backend instance
-
-        Returns
-        -------
-        dict
-            dictionary with ``condition: error_message`` pairs that will get
-            checked during ``_validate()`` run
-        """
-        return {
-            isinstance(self.n_workers, int)
-            and self.n_workers
-            > 0: f"n_workers should be positive integer, got {self.n_workers=}",
-        }
-
-    def _get_warnings(self):
-        """Get dictionary with ``condition: warning_message`` pairs that ensure
-        the good usage of the backend instance
-
-        Returns
-        -------
-        dict
-            dictionary with ``condition: warning_message`` pairs that will get
-            checked during ``_validate()`` run
-        """
-        return dict()
-
-    def _validate(self):
-        """Check correctness (e.g. ``dask`` is installed if using ``backend='dask'``)
-        and good usage (e.g. ``n_workers=1`` if backend is serial) of the backend
-
-        Raises
-        ------
-        ValueError
-            if one of the conditions in :meth:`_get_checks` is ``True``
-        """
-        for check, msg in self._get_checks().items():
-            if not check:
-                raise ValueError(msg)
-        for check, msg in self._get_warnings().items():
-            if not check:
-                warnings.warn(msg)
-
-    def apply(self, func: Callable, computations: list) -> list:
-        """map function `func` to all tasks in the `computations` list
-
-        Main method that will get called when using an instance of
-        ``BackendBase``.  It is equivalent to running ``[func(item) for item in
-        computations]`` while using the parallel backend capabilities.
-
-        Parameters
-        ----------
-        func : Callable
-            function to be called on each of the tasks in computations list
-        computations : list
-            computation tasks to apply function to
-
-        Returns
-        -------
-        list
-            list of results of the function
-
-        """
-        raise NotImplementedError
-
-
-class BackendSerial(BackendBase):
-    """A built-in backend that does serial execution of the function, without any
-    parallelization.
-
-    Parameters
-    ----------
-    n_workers : int
-        Is ignored in this class, and if ``n_workers`` > 1, a warning will be
-        given.
-
-
-    .. versionadded:: 2.8.0
-    """
-
-    def _get_warnings(self):
-        """Get dictionary with ``condition: warning_message`` pairs that ensure
-        the good usage of the backend instance. Here, it checks if the number
-        of workers is not 1, otherwise gives warning.
-
-        Returns
-        -------
-        dict
-            dictionary with ``condition: warning_message`` pairs that will get
-            checked during ``_validate()`` run
-        """
-        return {
-            self.n_workers
-            == 1: "n_workers is ignored when executing with backend='serial'"
-        }
-
-    def apply(self, func: Callable, computations: list) -> list:
-        """
-        Serially applies `func` to each task object in ``computations``.
-
-        Parameters
-        ----------
-        func : Callable
-            function to be called on each of the tasks in computations list
-        computations : list
-            computation tasks to apply function to
-
-        Returns
-        -------
-        list
-            list of results of the function
-        """
-        return [func(task) for task in computations]
-
-
-class BackendMultiprocessing(BackendBase):
-    """A built-in backend that executes a given function using the
-    :meth:`multiprocessing.Pool.map <multiprocessing.pool.Pool.map>` method.
-
-    Parameters
-    ----------
-    n_workers : int
-        number of processes in :class:`multiprocessing.Pool
-        <multiprocessing.pool.Pool>` to distribute the workload
-        between. Must be a positive integer.
-
-    Examples
-    --------
-
-    .. code-block:: python
-
-        from MDAnalysis.analysis.backends import BackendMultiprocessing
-        import multiprocessing as mp
-
-        backend_obj = BackendMultiprocessing(n_workers=mp.cpu_count())
-
-
-    .. versionadded:: 2.8.0
-
-    """
-
-    def apply(self, func: Callable, computations: list) -> list:
-        """Applies `func` to each object in ``computations`` using `multiprocessing`'s `Pool.map`.
-
-        Parameters
-        ----------
-        func : Callable
-            function to be called on each of the tasks in computations list
-        computations : list
-            computation tasks to apply function to
-
-        Returns
-        -------
-        list
-            list of results of the function
-        """
-        from multiprocessing import Pool
-
-        with Pool(processes=self.n_workers) as pool:
-            results = pool.map(func, computations)
-        return results
-
-
-class BackendDask(BackendBase):
-    """A built-in backend that executes a given function with *dask*.
-
-    Execution is performed with the :func:`dask.compute` function of
-    :class:`dask.delayed.Delayed` object (created with
-    :func:`dask.delayed.delayed`) with ``scheduler='processes'`` and
-    ``chunksize=1`` (this ensures uniform distribution of tasks among
-    processes). Requires the `dask package <https://docs.dask.org/en/stable/>`_
-    to be `installed <https://docs.dask.org/en/stable/install.html>`_.
-
-    Parameters
-    ----------
-    n_workers : int
-        number of processes in to distribute the workload
-        between. Must be a positive integer. Workers are actually
-        :class:`multiprocessing.pool.Pool` processes, but they use a different and
-        more flexible `serialization protocol
-        <https://docs.dask.org/en/stable/phases-of-computation.html#graph-serialization>`_.
-
-    Examples
-    --------
-
-    .. code-block:: python
-
-        from MDAnalysis.analysis.backends import BackendDask
-        import multiprocessing as mp
-
-        backend_obj = BackendDask(n_workers=mp.cpu_count())
-
-
-    .. versionadded:: 2.8.0
-
-    """
-
-    def apply(self, func: Callable, computations: list) -> list:
-        """Applies `func` to each object in ``computations``.
-
-        Parameters
-        ----------
-        func : Callable
-            function to be called on each of the tasks in computations list
-        computations : list
-            computation tasks to apply function to
-
-        Returns
-        -------
-        list
-            list of results of the function
-        """
-        from dask.delayed import delayed
-        import dask
-
-        computations = [delayed(func)(task) for task in computations]
-        results = dask.compute(
-            computations,
-            scheduler="processes",
-            chunksize=1,
-            num_workers=self.n_workers,
-        )[0]
-        return results
-
-    def _get_checks(self):
-        """Get dictionary with ``condition: error_message`` pairs that ensure the
-        validity of the backend instance. Here checks if ``dask`` module is
-        installed in the environment.
-
-        Returns
-        -------
-        dict
-            dictionary with ``condition: error_message`` pairs that will get
-            checked during ``_validate()`` run
-        """
-        base_checks = super()._get_checks()
-        checks = {
-            is_installed("dask"): (
-                "module 'dask' is missing. Please install 'dask': "
-                "https://docs.dask.org/en/stable/install.html"
-            )
-        }
-        return base_checks | checks

imdclient/results.py

@@ -1,332 +0,0 @@
-# Copy of MDAnalysis.analysis.results from 2.8.0
-
-"""Analysis results and their aggregation --- :mod:`MDAnalysis.analysis.results`
-================================================================================
-
-Module introduces two classes, :class:`Results` and :class:`ResultsGroup`,
-used for storing and aggregating data in
-:meth:`MDAnalysis.analysis.base.AnalysisBase.run()`, respectively.
-
-
-Classes
--------
-
-The :class:`Results` class is an extension of a built-in dictionary
-type, that holds all assigned attributes in :attr:`self.data` and 
-allows for access either via dict-like syntax, or via class-like syntax:
-
-.. code-block:: python
-
-    from MDAnalysis.analysis.results import Results
-    r = Results()
-    r.array = [1, 2, 3, 4]
-    assert r['array'] == r.array == [1, 2, 3, 4]
-
-
-The :class:`ResultsGroup` can merge multiple :class:`Results` objects.
-It is mainly used by :class:`MDAnalysis.analysis.base.AnalysisBase` class, 
-that uses :meth:`ResultsGroup.merge()` method to aggregate results from
-multiple workers, initialized during a parallel run:
-
-.. code-block:: python
-
-    from MDAnalysis.analysis.results import Results, ResultsGroup
-    import numpy as np
-    
-    r1, r2 = Results(), Results()
-    r1.masses = [1, 2, 3, 4, 5]
-    r2.masses = [0, 0, 0, 0]
-    r1.vectors = np.arange(10).reshape(5, 2)
-    r2.vectors = np.arange(8).reshape(4, 2)
-
-    group = ResultsGroup(
-        lookup = {
-            'masses': ResultsGroup.flatten_sequence,
-            'vectors': ResultsGroup.ndarray_vstack
-            }
-        )
-
-    r = group.merge([r1, r2])
-    assert r.masses == list((*r1.masses, *r2.masses))
-    assert (r.vectors == np.vstack([r1.vectors, r2.vectors])).all()
-"""
-
-from collections import UserDict
-import numpy as np
-from typing import Callable, Sequence
-
-
-class Results(UserDict):
-    r"""Container object for storing results.
-
-    :class:`Results` are dictionaries that provide two ways by which values
-    can be accessed: by dictionary key ``results["value_key"]`` or by object
-    attribute, ``results.value_key``. :class:`Results` stores all results
-    obtained from an analysis after calling :meth:`~AnalysisBase.run()`.
-
-    The implementation is similar to the :class:`sklearn.utils.Bunch`
-    class in `scikit-learn`_.
-
-    .. _`scikit-learn`: https://scikit-learn.org/
-    .. _`sklearn.utils.Bunch`: https://scikit-learn.org/stable/modules/generated/sklearn.utils.Bunch.html
-
-    Raises
-    ------
-    AttributeError
-        If an assigned attribute has the same name as a default attribute.
-
-    ValueError
-        If a key is not of type ``str`` and therefore is not able to be
-        accessed by attribute.
-
-    Examples
-    --------
-    >>> from MDAnalysis.analysis.base import Results
-    >>> results = Results(a=1, b=2)
-    >>> results['b']
-    2
-    >>> results.b
-    2
-    >>> results.a = 3
-    >>> results['a']
-    3
-    >>> results.c = [1, 2, 3, 4]
-    >>> results['c']
-    [1, 2, 3, 4]
-
-
-    .. versionadded:: 2.0.0
-
-    .. versionchanged:: 2.8.0
-        Moved :class:`Results` to :mod:`MDAnalysis.analysis.results`
-    """
-
-    def _validate_key(self, key):
-        if key in dir(self):
-            raise AttributeError(
-                f"'{key}' is a protected dictionary attribute"
-            )
-        elif isinstance(key, str) and not key.isidentifier():
-            raise ValueError(f"'{key}' is not a valid attribute")
-
-    def __init__(self, *args, **kwargs):
-        kwargs = dict(*args, **kwargs)
-        if "data" in kwargs.keys():
-            raise AttributeError(f"'data' is a protected dictionary attribute")
-        self.__dict__["data"] = {}
-        self.update(kwargs)
-
-    def __setitem__(self, key, item):
-        self._validate_key(key)
-        super().__setitem__(key, item)
-
-    def __setattr__(self, attr, val):
-        if attr == "data":
-            super().__setattr__(attr, val)
-        else:
-            self.__setitem__(attr, val)
-
-    def __getattr__(self, attr):
-        try:
-            return self[attr]
-        except KeyError as err:
-            raise AttributeError(
-                f"'Results' object has no attribute '{attr}'"
-            ) from err
-
-    def __delattr__(self, attr):
-        try:
-            del self[attr]
-        except KeyError as err:
-            raise AttributeError(
-                f"'Results' object has no attribute '{attr}'"
-            ) from err
-
-    def __getstate__(self):
-        return self.data
-
-    def __setstate__(self, state):
-        self.data = state
-
-
-class ResultsGroup:
-    """
-    Management and aggregation of results stored in :class:`Results` instances.
-
-    A :class:`ResultsGroup` is an optional description for :class:`Result` "dictionaries"
-    that are used in analysis classes based on :class:`AnalysisBase`. For each *key* in a
-    :class:`Result` it describes how multiple pieces of the data held under the key are
-    to be aggregated. This approach is necessary when parts of a trajectory are analyzed
-    independently (e.g., in parallel) and then need to me merged (with :meth:`merge`) to
-    obtain a complete data set.
-
-    Parameters
-    ----------
-    lookup : dict[str, Callable], optional
-        aggregation functions lookup dict, by default None
-
-    Examples
-    --------
-
-    .. code-block:: python
-
-        from MDAnalysis.analysis.results import ResultsGroup, Results
-        group = ResultsGroup(lookup={'mass': ResultsGroup.float_mean})
-        obj1 = Results(mass=1)
-        obj2 = Results(mass=3)
-        assert {'mass': 2.0} == group.merge([obj1, obj2])
-
-
-    .. code-block:: python
-
-        # you can also set `None` for those attributes that you want to skip
-        lookup = {'mass': ResultsGroup.float_mean, 'trajectory': None}
-        group = ResultsGroup(lookup)
-        objects = [Results(mass=1, skip=None), Results(mass=3, skip=object)]
-        assert group.merge(objects, require_all_aggregators=False) == {'mass': 2.0}
-
-    .. versionadded:: 2.8.0
-    """
-
-    def __init__(self, lookup: dict[str, Callable] = None):
-        self._lookup = lookup
-
-    def merge(
-        self, objects: Sequence[Results], require_all_aggregators: bool = True
-    ) -> Results:
-        """Merge multiple Results into a single Results instance.
-
-        Merge multiple :class:`Results` instances into a single one, using the
-        `lookup` dictionary to determine the appropriate aggregator functions for
-        each named results attribute. If the resulting object only contains a single
-        element, it just returns it without using any aggregators.
-
-        Parameters
-        ----------
-        objects : Sequence[Results]
-            Multiple :class:`Results` instances with the same data attributes.
-        require_all_aggregators : bool, optional
-            if True, raise an exception when no aggregation function for a
-            particular argument is found. Allows to skip aggregation for the
-            parameters that aren't needed in the final object --
-            see :class:`ResultsGroup`.
-
-        Returns
-        -------
-        Results
-            merged :class:`Results`
-
-        Raises
-        ------
-        ValueError
-            if no aggregation function for a key is found and ``require_all_aggregators=True``
-        """
-        if len(objects) == 1:
-            merged_results = objects[0]
-            return merged_results
-
-        merged_results = Results()
-        for key in objects[0].keys():
-            agg_function = self._lookup.get(key, None)
-            if agg_function is not None:
-                results_of_t = [obj[key] for obj in objects]
-                merged_results[key] = agg_function(results_of_t)
-            elif require_all_aggregators:
-                raise ValueError(f"No aggregation function for {key=}")
-        return merged_results
-
-    @staticmethod
-    def flatten_sequence(arrs: list[list]):
-        """Flatten a list of lists into a list
-
-        Parameters
-        ----------
-        arrs : list[list]
-            list of lists
-
-        Returns
-        -------
-        list
-            flattened list
-        """
-        return [item for sublist in arrs for item in sublist]
-
-    @staticmethod
-    def ndarray_sum(arrs: list[np.ndarray]):
-        """sums an ndarray along ``axis=0``
-
-        Parameters
-        ----------
-        arrs : list[np.ndarray]
-            list of input arrays. Must have the same shape.
-
-        Returns
-        -------
-        np.ndarray
-            sum of input arrays
-        """
-        return np.array(arrs).sum(axis=0)
-
-    @staticmethod
-    def ndarray_mean(arrs: list[np.ndarray]):
-        """calculates mean of input ndarrays along ``axis=0``
-
-        Parameters
-        ----------
-        arrs : list[np.ndarray]
-            list of input arrays. Must have the same shape.
-
-        Returns
-        -------
-        np.ndarray
-            mean of input arrays
-        """
-        return np.array(arrs).mean(axis=0)
-
-    @staticmethod
-    def float_mean(floats: list[float]):
-        """calculates mean of input float values
-
-        Parameters
-        ----------
-        floats : list[float]
-            list of float values
-
-        Returns
-        -------
-        float
-            mean value
-        """
-        return np.array(floats).mean()
-
-    @staticmethod
-    def ndarray_hstack(arrs: list[np.ndarray]):
-        """Performs horizontal stack of input arrays
-
-        Parameters
-        ----------
-        arrs : list[np.ndarray]
-            input numpy arrays
-
-        Returns
-        -------
-        np.ndarray
-            result of stacking
-        """
-        return np.hstack(arrs)
-
-    @staticmethod
-    def ndarray_vstack(arrs: list[np.ndarray]):
-        """Performs vertical stack of input arrays
-
-        Parameters
-        ----------
-        arrs : list[np.ndarray]
-            input numpy arrays
-
-        Returns
-        -------
-        np.ndarray
-            result of stacking
-        """
-        return np.vstack(arrs)