asyncmd 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

asyncmd/gromacs/utils.py

@@ -12,6 +12,11 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with asyncmd. If not, see <https://www.gnu.org/licenses/>.
+"""
+This file implements gromacs-specific variants of the utility functions related to MD usage.
+
+The general variants of these functions can be found in asyncmd.utils.
+"""
 import os
 import logging
 import aiofiles.os
@@ -48,30 +53,42 @@ def nstout_from_mdp(mdp: MDP, traj_type: str = "TRR") -> int:
         Raised when the given MDP would result in no output for the given
         trajectory format `traj_type`.
     """
+    def get_value_from_mdp(k):
+        try:
+            v = mdp[k]
+        except KeyError:
+            # not set, defaults to 0
+            v = float("inf")
+        else:
+            # need to check for 0 (== no output!) in case somone puts the
+            # defaults (or reads an mdout.mdp where gmx lists all the defaults)
+            if not v:
+                v = float("inf")
+        return v
+
     if traj_type.upper() == "TRR":
-        keys = ["nstxout", "nstvout", "nstfout"]
+        keys = ["nstxout"]
     elif traj_type.upper() == "XTC":
         keys = ["nstxout-compressed", "nstxtcout"]
     else:
         raise ValueError("traj_type must be one of 'TRR' or 'XTC'.")
-
     vals = []
     for k in keys:
-        try:
-            # need to check for 0 (== no output!) in case somone puts the
-            # defaults (or reads an mdout.mdp where gmx lists all the defaults)
-            v = mdp[k]
-            if v == 0:
-                v = float("inf")
-            vals += [v]
-        except KeyError:
-            # not set, defaults to 0, so we ignore it
-            pass
-
-    nstout = min(vals, default=None)
-    if (nstout is None) or (nstout == float("inf")):
+        vals += [get_value_from_mdp(k=k)]
+    if (nstout := min(vals)) == float("inf"):
         raise ValueError(f"The MDP you passed results in no {traj_type} "
-                         +"trajectory output.")
+                         + "trajectory output.")
+    if traj_type.upper == "TRR":
+        # additional checks that nstvout and nstfout are multiples of nstxout
+        # (if they are defined)
+        additional_keys = ["nstvout", "nstfout"]
+        for k in additional_keys:
+            if (v := get_value_from_mdp(k=k)) != float("inf"):
+                if v % nstout:
+                    logger.warning("%s trajectory output is not a multiple of "
+                                   "the nstxout frequency (%s=%d, nstxout=%d).",
+                                   k, k, v, nstout)
+
     return nstout
 
 
@@ -128,7 +145,7 @@ async def get_all_file_parts(folder: str, deffnm: str, file_ending: str) -> "lis
     """
     def partnum_suffix(num):
         # construct gromacs num part suffix from simulation_part
-        num_suffix = ".part{:04d}".format(num)
+        num_suffix = f".part{num:04d}"
         return num_suffix
 
     if not file_ending.startswith("."):

asyncmd/mdconfig.py

@@ -12,160 +12,51 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with asyncmd. If not, see <https://www.gnu.org/licenses/>.
+"""
+This module contains abstract base classes to use for MD config file parsing.
+
+It contains the MDConfig class, which only serves to define the interface and
+the LineBasedMDConfig class, which implements useful methods to parse MD configuration
+files in which options never span over multiple lines, i.e. in which every line
+contains only one (or multiple) options.
+"""
 import os
 import abc
-import typing
 import shutil
 import logging
 import collections
 
+from .tools import TypedFlagChangeList
 
-logger = logging.getLogger(__name__)
-
-
-class FlagChangeList(collections.abc.MutableSequence):
-    """A list that knows if it has been changed after initializing."""
-
-    def __init__(self, data: list) -> None:
-        """
-        Initialize a `FlagChangeList`.
-
-        Parameters
-        ----------
-        data : list
-            The data this `FlagChangeList` will hold.
-
-        Raises
-        ------
-        TypeError
-            Raised when data is not a :class:`list`.
-        """
-        if not isinstance(data, list):
-            raise TypeError("FlagChangeList must be initialized with a list.")
-        self._data = data
-        self._changed = False
-
-    @property
-    def changed(self) -> bool:
-        """
-        Whether this `FlagChangeList` has been modified since creation.
-
-        Returns
-        -------
-        bool
-        """
-        return self._changed
-
-    def __repr__(self) -> str:
-        return self._data.__repr__()
-
-    def __getitem__(self, index: int) -> typing.Any:
-        return self._data.__getitem__(index)
-
-    def __len__(self) -> int:
-        return self._data.__len__()
-
-    def __setitem__(self, index: int, value) -> None:
-        self._data.__setitem__(index, value)
-        self._changed = True
-
-    def __delitem__(self, index: int) -> None:
-        self._data.__delitem__(index)
-        self._changed = True
 
-    def insert(self, index: int, value: typing.Any):
-        """
-        Insert `value` at position given by `index`.
-
-        Parameters
-        ----------
-        index : int
-            The index of the new value in the `FlagChangeList`.
-        value : typing.Any
-            The value to insert into this `FlagChangeList`.
-        """
-        self._data.insert(index, value)
-        self._changed = True
-
-
-class TypedFlagChangeList(FlagChangeList):
-    """
-    A :class:`FlagChangeList` with an ensured type for individual list items.
-    """
-
-    def __init__(self, data: typing.Iterable, dtype) -> None:
-        """
-        Initialize a `TypedFlagChangeList`.
-
-        Parameters
-        ----------
-        data : Iterable
-            (Initial) data for this `TypedFlagChangeList`.
-        dtype : Callable datatype
-            The datatype for all entries in this `TypedFlagChangeList`. Will be
-            called on every value seperately and is expected to convert to the
-            desired datatype.
-        """
-        self._dtype = dtype  # set first to use in _convert_type method
-        if getattr(data, '__len__', None) is None:
-            # convienience for singular options,
-            # if it has no len attribute we assume it is the only item
-            data = [data]
-        elif isinstance(data, str):
-            # strings have a length but we still do not want to split them into
-            # single letters, so just put a list around
-            data = [data]
-        typed_data = [self._convert_type(v, index=i)
-                      for i, v in enumerate(data)]
-        super().__init__(data=typed_data)
-
-    def _convert_type(self, value, index=None):
-        # here we ignore index, but passing it should in principal make it
-        # possible to use different dtypes for different indices
-        return self._dtype(value)
-
-    def __setitem__(self, index: int, value) -> None:
-        typed_value = self._convert_type(value, index=index)
-        self._data.__setitem__(index, typed_value)
-        self._changed = True
-
-    def insert(self, index: int, value) -> None:
-        """
-        Insert `value` at position given by `index`.
-
-        Parameters
-        ----------
-        index : int
-            The index of the new value in the `TypedFlagChangeList`.
-        value : typing.Any
-            The value to insert into this `TypedFlagChangeList`.
-        """
-        typed_value = self._convert_type(value, index=index)
-        self._data.insert(index, typed_value)
-        self._changed = True
+logger = logging.getLogger(__name__)
 
 
-# NOTE: only to define the interface
 class MDConfig(collections.abc.MutableMapping):
+    """Abstract base class only to define the interface."""
+
     @abc.abstractmethod
     def parse(self):
-        # should read original file and populate self with key, value pairs
+        """Should read original file and populate self with key, value pairs."""
         raise NotImplementedError
 
     @abc.abstractmethod
     def write(self, outfile):
-        # write out current config stored in self to outfile
+        """Should write out current config stored in self to outfile."""
         raise NotImplementedError
 
 
 class LineBasedMDConfig(MDConfig):
-    # abstract base class for line based parsing and writing,
-    # subclasses must implement `_parse_line()` method and should set the
-    # appropriate separator characters for their line format
-    # We assume that every line/option can be parsed and written on its own!
-    # We assume the order of the options in the written file is not relevant!
-    # We represent every line/option with a key (str), list of values pair
-    # values can have a specific type (e.g. int or float) or default to str.
+    """
+    Abstract base class for line based parsing and writing.
+
+    Subclasses must implement `_parse_line()` method and should set the
+    appropriate separator characters for their line format.
+    We assume that every line/option can be parsed and written on its own!
+    We assume the order of the options in the written file is not relevant!
+    We represent every line/option with a key (str), list of values pair.
+    Values can have a specific type (e.g. int or float) or default to str.
+    """
     # NOTE: Initially written for gmx, but we already had e.g. namd in mind and
     # tried to make this as general as possible
 
@@ -177,11 +68,11 @@ class LineBasedMDConfig(MDConfig):
     # use these to specify config parameters that are of type int or float
     # parsed lines with dict key matching will then be converted
     # any lines not matching will be left in their default str type
-    _FLOAT_PARAMS = []  # can have multiple values per config option
-    _FLOAT_SINGLETON_PARAMS = []  # must have one value per config option
-    _INT_PARAMS = []  # multiple int per option
-    _INT_SINGLETON_PARAMS = []  # one int per option
-    _STR_SINGLETON_PARAMS = []  # strings with only one value per option
+    _FLOAT_PARAMS: list[str] = []  # can have multiple values per config option
+    _FLOAT_SINGLETON_PARAMS: list[str] = []  # must have one value per config option
+    _INT_PARAMS: list[str] = []  # multiple int per option
+    _INT_SINGLETON_PARAMS: list[str] = []  # one int per option
+    _STR_SINGLETON_PARAMS: list[str] = []  # strings with only one value per option
     # NOTE on SPECIAL_PARAM_DISPATCH
     # can be used to set custom type convert functions on a per parameter basis
     # the key must match the key in the dict for in the parsed line,
@@ -192,7 +83,7 @@ class LineBasedMDConfig(MDConfig):
     # new values into the expected FlagChangeList format
     # [note that it is probably easiest to subclass TypedFlagChangeList and
     #  overwrite only the '_check_type()' method]
-    _SPECIAL_PARAM_DISPATCH = {}
+    _SPECIAL_PARAM_DISPATCH: dict[str, collections.abc.Callable] = {}
 
     def __init__(self, original_file: str) -> None:
         """
@@ -203,7 +94,7 @@ class LineBasedMDConfig(MDConfig):
         original_file : str
             Path to original config file (absolute or relative).
         """
-        self._config = {}
+        self._config: dict[str, TypedFlagChangeList | int | float | str] = {}
         self._changed = False
         self._type_dispatch = self._construct_type_dispatch()
         # property to set/check file and parse to config dictionary all in one
@@ -218,8 +109,7 @@ class LineBasedMDConfig(MDConfig):
             # singleton vals, i.e. "val" instead of ["val"]
             if isinstance(val, str) or getattr(val, '__len__', None) is None:
                 return dtype(val)
-            else:
-                return dtype(val[0])
+            return dtype(val[0])
 
         # construct type conversion dispatch
         type_dispatch = collections.defaultdict(
@@ -310,14 +200,14 @@ class LineBasedMDConfig(MDConfig):
     def __len__(self) -> int:
         return self._config.__len__()
 
-    def __repr__(self) -> str:
+    def __repr__(self) -> str:  # pragma: no cover
         return str({"changed": self._changed,
                     "original_file": self.original_file,
                     "content": self._config.__repr__(),
                     }
                    )
 
-    def __str__(self) -> str:
+    def __str__(self) -> str:  # pragma: no cover
         repr_str = (f"{type(self)} has been changed since parsing: "
                     + f"{self._changed}\n"
                     )
@@ -362,15 +252,14 @@ class LineBasedMDConfig(MDConfig):
         # NOTE: we default to False, i.e. we expect that anything that
         #       does not have a self.changed attribute is not a container
         #       and we (the dictionary) would know that it changed
-        return self._changed or any([getattr(v, "changed", False)
-                                     for v in self._config.values()]
-                                    )
+        return self._changed or any(getattr(v, "changed", False)
+                                    for v in self._config.values())
 
     def parse(self):
         """Parse the current ``self.original_file`` to update own state."""
-        with open(self.original_file, "r") as f:
+        with open(self.original_file, "r", encoding="locale") as f:
             # NOTE: we split at newlines on all platforms by iterating over the
-            #       file, i.e. python takes care of the differnt platforms and
+            #       file, i.e. python takes care of the different platforms and
             #       newline chars for us :)
             parsed = {}
             for line in f:
@@ -384,7 +273,7 @@ class LineBasedMDConfig(MDConfig):
                         # as it should be
                         pass
                     else:
-                        # warn that we will only keep the last occurenc of key
+                        # warn that we will only keep the last occurrence of key
                         logger.warning("Parsed duplicate configuration option "
                                        "(%s). Last values encountered take "
                                        "precedence.", key)
@@ -421,20 +310,21 @@ class LineBasedMDConfig(MDConfig):
             lines = []
             for key, value in self._config.items():
                 line = f"{key}{self._KEY_VALUE_SEPARATOR}"
-                try:
-                    if len(value) >= 0:
-                        if isinstance(value, str):
-                            # it is a string singleton option
-                            line += f"{value}"
-                        else:
-                            line += self._INTER_VALUE_CHAR.join(str(v)
-                                                                for v in value
-                                                                )
-                except TypeError:
-                    # not a Sequence/Iterable or string,
-                    # i.e. (probably) one of the float/int singleton options
+                if isinstance(value, (str, float, int)):
+                    # it is a string/float/int singleton option
                     line += f"{value}"
+                else:
+                    # not a singleton, so lets try to iterate over it
+                    try:
+                        line += self._INTER_VALUE_CHAR.join(str(v)
+                                                            for v in value
+                                                            )
+                    except TypeError:
+                        # Note: need this except to catch user-added types
+                        #       (via special param dispatch), that are not
+                        #       str/float/int singletons but also not iterable
+                        line += f"{value}"
                 lines += [line]
             # concatenate the lines and write out at once
-            with open(outfile, "w") as f:
+            with open(outfile, "w", encoding="locale") as f:
                 f.write("\n".join(lines))

asyncmd/mdengine.py

@@ -12,18 +12,21 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with asyncmd. If not, see <https://www.gnu.org/licenses/>.
+"""
+This module contains the abstract base class defining the interface for all MDEngines.
+
+It also defines the commonly used exceptions for MDEngines.
+"""
 import abc
 from .trajectory.trajectory import Trajectory
 
 
 class EngineError(Exception):
     """Exception raised when something goes wrong with the (MD)-Engine."""
-    pass
 
 
 class EngineCrashedError(EngineError):
     """Exception raised when the (MD)-Engine crashes during a run."""
-    pass
 
 
 class MDEngine(abc.ABC):
@@ -33,68 +36,146 @@ class MDEngine(abc.ABC):
     @abc.abstractmethod
     async def apply_constraints(self, conf_in: Trajectory,
                                 conf_out_name: str) -> Trajectory:
-        # apply constraints to given conf_in, write conf_out_name and return it
+        """
+        Apply constraints to given conf_in, write conf_out_name and return it.
+
+        Parameters
+        ----------
+        conf_in : Trajectory
+        conf_out_name : str
+
+        Returns
+        -------
+        Trajectory
+        """
         raise NotImplementedError
 
     @abc.abstractmethod
-    # TODO: think about the most general interface!
-    # NOTE: We assume that we do not change the system for/in one engine,
-    #       i.e. .top, .ndx, mdp-object, ...?! should go into __init__
     async def prepare(self, starting_configuration: Trajectory, workdir: str,
                       deffnm: str) -> None:
+        """
+        Prepare the engine to run a MD from starting_configuration.
+
+        NOTE: We assume that we do not change the system for/in one engine,
+        i.e. .top, .ndx, mdp-object, ...?! should go into __init__.
+
+        Parameters
+        ----------
+        starting_configuration : Trajectory
+            The initial configuration.
+        workdir : str
+            The directory in which the MD will be performed.
+        deffnm : str
+            The standard filename to use for this MD run.
+        """
         raise NotImplementedError
 
     @abc.abstractmethod
-    # TODO: should this be a classmethod?
     #@classmethod
     async def prepare_from_files(self, workdir: str, deffnm: str) -> None:
-        # this should prepare the engine to continue a previously stopped simulation
-        # starting with the last trajectory part in workdir that is compatible with deffnm
+        """
+        Prepare the engine to continue a previously stopped simulation starting
+        with the last trajectory part in workdir that is compatible with deffnm.
+
+        NOTE: This can not be a classmethod (reliably) because we set top/ndx/
+        mdconfig/etc in '__init__'.
+
+        Parameters
+        ----------
+        workdir : str
+            The directory in which the MD will be/ was previously performed.
+        deffnm : str
+            The standard filename to use for this MD run.
+        """
         raise NotImplementedError
 
     @abc.abstractmethod
-    async def run_walltime(self, walltime: float) -> Trajectory:
-        # run for specified walltime
-        # NOTE: must be possible to run this multiple times after preparing once!
+    async def run_walltime(self, walltime: float, max_steps: int | None = None,
+                           ) -> Trajectory | None:
+        """
+        Run for specified walltime.
+
+        NOTE: Must be possible to run this multiple times after preparing once!
+
+        It is optional (but recommended if possible) for engines to respect the
+        ``max_steps`` argument. I.e. terminating upon reaching max_steps is
+        optional and no code should rely on it. See the :meth:`run_steps` if a
+        fixed number of integration steps is required.
+
+        Return None if no integration is needed because max_steps integration
+        steps have already been performed.
+
+        Parameters
+        ----------
+        walltime : float
+            Walltime in hours.
+        max_steps : int | None, optional
+            If not None, (optionally) terminate when max_steps integration steps
+            in total are reached, also if this is before walltime is reached.
+            By default None.
+
+        Returns
+        -------
+        Trajectory | None
+        """
         raise NotImplementedError
 
     @abc.abstractmethod
     async def run_steps(self, nsteps: int,
-                        steps_per_part: bool = False) -> Trajectory:
-        # run for specified number of steps
-        # NOTE: not sure if we need it, but could be useful
-        # NOTE: make sure we can run multiple times after preparing once!
+                        steps_per_part: bool = False) -> Trajectory | None:
+        """
+        Run for a specified number of integration steps.
+
+        Return None if no integration is needed because nsteps integration steps
+        have already been performed.
+
+        NOTE: Make sure we can run multiple times after preparing once!
+
+        Parameters
+        ----------
+        nsteps : int
+        steps_per_part : bool, optional
+            Count nsteps for this part/run or in total, by default False
+
+        Returns
+        -------
+        Trajectory | None
+        """
         raise NotImplementedError
 
-    @abc.abstractproperty
-    def current_trajectory(self) -> Trajectory:
-        # return current trajectory: Trajectory or None
-        # if we retun a Trajectory it is either what we are working on atm
+    @property
+    @abc.abstractmethod
+    def current_trajectory(self) -> Trajectory | None:
+        """
+        Return current trajectory: Trajectory or None.
+        """
+        # if we return a Trajectory it is either what we are working on atm
         # or the trajectory we finished last
         raise NotImplementedError
 
-    @abc.abstractproperty
+    @property
+    @abc.abstractmethod
     def output_traj_type(self) -> str:
-        # return a string with the ending (without ".") of the trajectory
-        # type this engine uses
-        # NOTE: this should not be implemented as a property in subclasses
-        #       as it must be available at the classlevel too
-        #       so cls.output_traj_type must also be the string
-        #       If you want/need to check the values (i.e. you would like to
-        #       execute code like in a property) have a look at the descriptor
-        #       implementation in gromacs/mdengine.py which checks for allowed
-        #       values (at least when set on an instance) but is accesible from
-        #       the class level too, e.g. like a 'classproperty' (which is not
-        #        a thing in python)
-        raise NotImplementedError
+        """
+        Return a string with the ending (without ".") of the trajectory type this
+        engine uses.
 
-    # TODO/FIXME: remove this function?
-    # NOTE: I think we wont really need/use this anyway since the run_ funcs
-    #       are all awaitable
-    @abc.abstractproperty
-    def running(self) -> bool:
+        NOTE: This should not be implemented as a property in subclasses as it
+        must be available at the classlevel too, i.e. cls.output_traj_type must
+        also return the string.
+        So this should just be overwritten with a string with the correct value,
+        or if your engine supports multiple output_traj_types you should have a
+        look at the descriptor implementation in asyncmd/tools.py (and, e.g.,
+        used in asyncmd/gromacs/mdengine.py), which checks for allowed values
+        (at least when set on an instance) but is accessible from the class
+        level too, i.e. like a 'classproperty' (which is not a thing in python).
+        """
         raise NotImplementedError
 
-    @abc.abstractproperty
+    @property
+    @abc.abstractmethod
     def steps_done(self) -> int:
+        """
+        Return the number of integration steps this engine has performed in total.
+        """
         raise NotImplementedError