Source code for MDAnalysis.coordinates.H5MD

# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
#
# MDAnalysis --- https://www.mdanalysis.org
# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
# (see the file AUTHORS for the full list of names)
#
# Released under the GNU Public Licence, v2 or any higher version
#
# Please cite your use of MDAnalysis in published work:
#
# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
# doi: 10.25080/majora-629e541a-00e
#
# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
#
"""
H5MD trajectories --- :mod:`MDAnalysis.coordinates.H5MD`
========================================================

The `H5MD`_ trajectory file format is based upon the general, high performance
`HDF5`_ file format.
HDF5 files are self documenting and can be accessed with the `h5py`_ library.
HDF5 can make use of parallel file system features through the MPI-IO
interface of the HDF5 library to improve parallel reads and writes.

The HDF5 library and `h5py`_ must be installed; otherwise, H5MD files
cannot be read by MDAnalysis. If `h5py`_ is not installed, a
:exc:`RuntimeError` is raised.

Units
-----

H5MD files are very flexible and can store data in a wide range of physical
units. The :class:`H5MDReader` will attempt to match the units in order to
convert all data to the standard MDAnalysis units (see
:mod:`MDAnalysis.units`).

Units are read from the attributes of the position, velocity, force, and time
datasets provided by the H5MD file. The unit string is translated from `H5MD
notation`_ to `MDAnalysis notation`_. If MDAnalysis does not recognize the unit
(likely because that unit string is not defined in :mod:`MDAnalysis.units`)
provided, a :exc:`RuntimeError` is raised.  If no units are provided,
MDAnalysis stores a value of ``None`` for each unit.  If the H5MD file does not
contain units and ``convert_units=True``, MDAnalysis will raise a
:exc:`ValueError`. To load a universe from an H5MD file with no units defined,
set ``convert_units=False``.

:class:`H5MDWriter` detects the native units of the parent trajectory and
writes the trajectory with those units, unless one of `timeunit`,
`lengthunit`, `velocityunit`, `forceunit` arugments are supplied. In
this case, the writer will write the corresponding dataset with the selected
unit only if it is recognized by `MDAnalysis units`_.


Example: Loading an H5MD simulation
-----------------------------------

To load an H5MD simulation from an H5MD trajectory data file (using the
:class:`~MDAnalysis.coordinates.H5MD.H5MDReader`), pass the topology
and trajectory files to :class:`~MDAnalysis.core.universe.Universe`::

    import MDAnalysis as mda
    u = mda.Universe("topology.tpr", "trajectory.h5md")

It is also possible to pass an open :class:`h5py.File` file stream
into the reader::

    import MDAnalysis as mda
    with h5py.File("trajectory.h5md", 'r') as f:
         u = mda.Universe("topology.tpr", f)


.. Note:: Directly using a `h5py.File` does not work yet.
   See issue `#2884 <https://github.com/MDAnalysis/mdanalysis/issues/2884>`_.


Example: Writing an H5MD file
-----------------------------

To write to an H5MD file from a trajectory loaded with MDAnalysis, do:

.. code-block:: python

    import MDAnalysis as mda
    u = mda.Universe("topology.tpr", "trajectory.h5md")
    with mda.Writer("output.h5md", n_atoms=u.trajectory.n_atoms) as W:
        for ts in u.trajectory:
            W.write(u)

To write an H5MD file with contiguous datasets, you must specify the
number of frames to be written and set ``chunks=False``:

.. code-block:: python

    with mda.Writer("output_contigous.h5md", n_atoms=u.trajectory.n_atoms,
                    n_frames=3, chunks=False) as W:
        for ts in u.trajectory[:3]:
            W.write(u)

The writer also supports writing directly from an :class:`~MDAnalysis.core.groups.AtomGroup`::

    ag = u.select_atoms("protein and name CA")
    ag.write("alpha_carbons.h5md", frames='all')


Example: Opening an H5MD file in parallel
-----------------------------------------

The parallel features of HDF5 can be accessed through h5py
(see `parallel h5py docs`_ for more detail) by using the `mpi4py`_ Python
package with a Parallel build of HDF5. To load a an H5MD simulation with
parallel HDF5, pass `driver` and `comm` arguments to
:class:`~MDAnalysis.core.universe.Universe`::

    import MDAnalysis as mda
    from mpi4py import MPI
    u = mda.Universe("topology.tpr", "trajectory.h5md",
                     driver="mpio", comm=MPI.COMM_WORLD)


.. Note::
   :mod:`h5py` must be built with parallel features enabled on top of a parallel
   HDF5 build, and HDF5 and :mod:`mpi4py` must be built with a working MPI
   implementation. See instructions below.

Building parallel h5py and HDF5 on Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Building a working parallel HDF5/h5py/mpi4py environment can be
challenging and is often specific to your local computing resources,
e.g., the supercomputer that you're running on typically already has
its preferred MPI installation. As a starting point we provide
instructions that worked in a specific, fairly generic environment.

These instructions successfully built parallel HDF5/h5py
with *OpenMPI 4.0.4*, *HDF5 1.10.6*, *h5py 2.9.0*, and *mpi4py 3.0.3*
on *Ubuntu 16.0.6*. You may have to play around with different combinations of
versions of h5py/HDF5 to get a working parallel build.

    1. `Build MPI from sources`_
    2. `Build HDF5 from sources`_ with parallel settings enabled:

       .. code-block:: bash

          ./configure --enable-parallel --enable-shared
          make
          make install

    3. `Install mpi4py`_, making sure to point `mpicc` to where you've
       installed your MPI implemenation:

       .. code-block:: bash

          env MPICC=/path/to/mpicc pip install mpi4py

    4. `Build h5py from sources`_, making sure to enable mpi and to point
       to your parallel build of HDF5:

       .. code-block:: bash

          export HDF5_PATH=path-to-parallel-hdf5
          python setup.py clean --all
          python setup.py configure -r --hdf5-version=X.Y.Z --mpi --hdf5=$HDF5_PATH
          export gcc=gcc
          CC=mpicc HDF5_DIR=$HDF5_PATH python setup.py build
          python setup.py install

If you have questions or want to share how you managed to build
parallel hdf5/h5py/mpi4py please let everyone know on the
`MDAnalysis forums`_.

.. _`H5MD`: https://nongnu.org/h5md/index.html
.. _`HDF5`: https://www.hdfgroup.org/solutions/hdf5/
.. _`H5PY`: http://docs.h5py.org/
.. _`parallel h5py docs`: https://docs.h5py.org/en/stable/mpi.html
.. _`mpi4py`: https://mpi4py.readthedocs.io/en/stable/index.html
.. _`Build MPI from sources`: https://mpi4py.readthedocs.io/en/stable/appendix.html#building-mpi-from-sources
.. _`Build HDF5 from sources`: https://support.hdfgroup.org/ftp/HDF5/current/src/unpacked/release_docs/INSTALL_parallel
.. _`Install mpi4py`: https://mpi4py.readthedocs.io/en/stable/install.html#requirements
.. _`Build h5py from sources`: https://docs.h5py.org/en/stable/mpi.html#building-against-parallel-hdf5
.. _`H5MD notation`: https://nongnu.org/h5md/modules/units.html
.. _`MDAnalysis notation`: https://userguide.mdanalysis.org/units.html
.. _`MDAnalysis units`: https://userguide.mdanalysis.org/units.html
.. _`MDAnalysis forums`: https://www.mdanalysis.org/#participating


Classes
-------

.. autoclass:: H5MDReader
   :members:
   :inherited-members:

   .. automethod:: H5MDReader._reopen

.. autoclass:: H5MDWriter
   :members:
   :inherited-members:

.. autoclass:: H5PYPicklable
   :members:

"""

import numpy as np
import MDAnalysis as mda
from . import base, core
from ..exceptions import NoDataError
from ..due import due, Doi
try:
    import h5py
except ImportError:
    HAS_H5PY = False

    # Allow building documentation even if h5py is not installed
    import types

    class MockH5pyFile:
        pass
    h5py = types.ModuleType("h5py")
    h5py.File = MockH5pyFile

else:
    HAS_H5PY = True


[docs]class H5MDReader(base.ReaderBase): r"""Reader for the H5MD format. See `h5md documentation <https://nongnu.org/h5md/h5md.html>`_ for a detailed overview of the H5MD file format. The reader attempts to convert units in the trajectory file to the standard MDAnalysis units (:mod:`MDAnalysis.units`) if `convert_units` is set to ``True``. Additional data in the *observables* group of the H5MD file are loaded into the :attr:`Timestep.data <MDAnalysis.coordinates.base.Timestep.data>` dictionary. Only 3D-periodic boxes or no periodicity are supported; for no periodicity, :attr:`Timestep.dimensions <MDAnalysis.coordinates.base.Timestep.dimensions>` will return ``None``. Although H5MD can store varying numbers of particles per time step as produced by, e.g., GCMC simulations, MDAnalysis can currently only process a fixed number of particles per step. If the number of particles changes a :exc:`ValueError` is raised. The :class:`H5MDReader` reads .h5md files with the following HDF5 hierarchy: .. code-block:: text Notation: (name) is an HDF5 group that the reader recognizes {name} is an HDF5 group with arbitrary name [variable] is an HDF5 dataset <dtype> is dataset datatype +-- is an attribute of a group or dataset H5MD root \-- (h5md) +-- version <int> \-- author +-- name <str>, author's name +-- email <str>, optional email address \-- creator +-- name <str>, file that created .h5md file +-- version \-- (particles) \-- {group1} \-- (box) +-- dimension : <int>, number of spatial dimensions +-- boundary : <str>, boundary conditions of unit cell \-- (edges) \-- [step] <int>, gives frame \-- [value] <float>, gives box dimensions +-- unit <str> \-- (position) \-- [step] <int>, gives frame \-- [time] <float>, gives time +-- unit <str> \-- [value] <float>, gives numpy arrary of positions with shape (n_atoms, 3) +-- unit <str> \-- (velocity) \-- [step] <int>, gives frame \-- [time] <float>, gives time +-- unit <str> \-- [value] <float>, gives numpy arrary of velocities with shape (n_atoms, 3) +-- unit <str> \-- (force) \-- [step] <int>, gives frame \-- [time] <float>, gives time +-- unit <str> \-- [value] <float>, gives numpy arrary of forces with shape (n_atoms, 3) +-- unit <str> \-- (observables) \-- (lambda) \-- [step] <int>, gives frame \-- [time] <float>, gives time \-- [value] <float> \-- (step) \-- [step] <int>, gives frame \-- [time] <float>, gives time \-- [value] <int>, gives integration step .. note:: The reader does not currently read mass or charge data. .. note:: If the `driver` and `comm` arguments were used to open the hdf5 file (specifically, ``driver="mpio"``) then the :meth:`_reopen` method does *not* close and open the file like most readers because the information about the MPI communicator would be lost; instead it rewinds the trajectory back to the first timestep. .. versionadded:: 2.0.0 """ format = 'H5MD' # units is defined as instance-level variable and set from the # H5MD file in __init__() below # This dictionary is used to translate H5MD units to MDAnalysis units. # (https://nongnu.org/h5md/modules/units.html) _unit_translation = { 'time': { 'ps': 'ps', 'fs': 'fs', 'ns': 'ns', 'second': 's', 'sec': 's', 's': 's', 'AKMA': 'AKMA', }, 'length': { 'Angstrom': 'Angstrom', 'angstrom': 'Angstrom', 'A': 'Angstrom', 'nm': 'nm', 'pm': 'pm', 'fm': 'fm', }, 'velocity': { 'Angstrom ps-1': 'Angstrom/ps', 'A ps-1': 'Angstrom/ps', 'Angstrom fs-1': 'Angstrom/fs', 'A fs-1': 'Angstrom/fs', 'Angstrom AKMA-1': 'Angstrom/AKMA', 'A AKMA-1': 'Angstrom/AKMA', 'nm ps-1': 'nm/ps', 'nm ns-1': 'nm/ns', 'pm ps-1': 'pm/ps', 'm s-1': 'm/s' }, 'force': { 'kJ mol-1 Angstrom-1': 'kJ/(mol*Angstrom)', 'kJ mol-1 nm-1': 'kJ/(mol*nm)', 'Newton': 'Newton', 'N': 'N', 'J m-1': 'J/m', 'kcal mol-1 Angstrom-1': 'kcal/(mol*Angstrom)', 'kcal mol-1 A-1': 'kcal/(mol*Angstrom)' } } @due.dcite(Doi("10.25080/majora-1b6fd038-005"), description="MDAnalysis trajectory reader/writer of the H5MD" "format", path=__name__) @due.dcite(Doi("10.1016/j.cpc.2014.01.018"), description="Specifications of the H5MD standard", path=__name__, version='1.1') def __init__(self, filename, convert_units=True, driver=None, comm=None, **kwargs): """ Parameters ---------- filename : str or :class:`h5py.File` trajectory filename or open h5py file convert_units : bool (optional) convert units to MDAnalysis units driver : str (optional) H5PY file driver used to open H5MD file comm : :class:`MPI.Comm` (optional) MPI communicator used to open H5MD file Must be passed with `'mpio'` file driver **kwargs : dict General reader arguments. Raises ------ RuntimeError when `H5PY`_ is not installed RuntimeError when a unit is not recognized by MDAnalysis ValueError when ``n_atoms`` changes values between timesteps ValueError when ``convert_units=True`` but the H5MD file contains no units ValueError when dimension of unitcell is not 3 ValueError when an MPI communicator object is passed to the reader but ``driver != 'mpio'`` NoDataError when the H5MD file has no 'position', 'velocity', or 'force' group """ if not HAS_H5PY: raise RuntimeError("Please install h5py") super(H5MDReader, self).__init__(filename, **kwargs) self.filename = filename self.convert_units = convert_units # if comm is provided, driver must be 'mpio' and file will be # opened with parallel h5py/hdf5 enabled self._driver = driver self._comm = comm if (self._comm is not None) and (self._driver != 'mpio'): raise ValueError("If MPI communicator object is used to open" " h5md file, ``driver='mpio'`` must be passed.") self.open_trajectory() if self._particle_group['box'].attrs['dimension'] != 3: raise ValueError("MDAnalysis only supports 3-dimensional" " simulation boxes") # _has dictionary used for checking whether h5md file has # 'position', 'velocity', or 'force' groups in the file self._has = {name: name in self._particle_group for name in ('position', 'velocity', 'force')} # Gets some info about what settings the datasets were created with # from first available group for name, value in self._has.items(): if value: dset = self._particle_group[f'{name}/value'] self.n_atoms = dset.shape[1] self.compression = dset.compression self.compression_opts = dset.compression_opts break else: raise NoDataError("Provide at least a position, velocity" " or force group in the h5md file.") self.ts = self._Timestep(self.n_atoms, positions=self.has_positions, velocities=self.has_velocities, forces=self.has_forces, **self._ts_kwargs) self.units = {'time': None, 'length': None, 'velocity': None, 'force': None} self._set_translated_units() # fills units dictionary self._read_next_timestep() def _set_translated_units(self): """converts units from H5MD to MDAnalysis notation and fills units dictionary""" # need this dictionary to associate 'position': 'length' _group_unit_dict = {'time': 'time', 'position': 'length', 'velocity': 'velocity', 'force': 'force' } for group, unit in _group_unit_dict.items(): self._translate_h5md_units(group, unit) self._check_units(group, unit) def _translate_h5md_units(self, group, unit): """stores the translated unit string into the units dictionary""" errmsg = "{} unit '{}' is not recognized by H5MDReader. Please raise" " an issue in https://github.com/MDAnalysis/mdanalysis/issues" # doing time unit separately because time has to fish for # first available parent group - either position, velocity, or force if unit == 'time': for name, value in self._has.items(): if value: if 'unit' in self._particle_group[name]['time'].attrs: try: self.units['time'] = self._unit_translation[ 'time'][self._particle_group[name][ 'time'].attrs['unit']] break except KeyError: raise RuntimeError(errmsg.format( unit, self._particle_group[ name]['time'].attrs['unit']) ) from None else: if self._has[group]: if 'unit' in self._particle_group[group]['value'].attrs: try: self.units[unit] = self._unit_translation[unit][ self._particle_group[group]['value'].attrs['unit']] except KeyError: raise RuntimeError(errmsg.format( unit, self._particle_group[group][ 'value'].attrs['unit']) ) from None # if position group is not provided, can still get 'length' unit # from unitcell box if (not self._has['position']) and ('edges' in self._particle_group['box']): if 'unit' in self._particle_group['box/edges/value'].attrs: try: self.units['length'] = self._unit_translation[ 'length'][self._particle_group[ 'box/edges/value' ].attrs['unit']] except KeyError: raise RuntimeError(errmsg.format(unit, self._particle_group[ 'box/edges/value'].attrs[ 'unit'])) from None def _check_units(self, group, unit): """Raises error if no units are provided from H5MD file and convert_units=True""" if not self.convert_units: return errmsg = "H5MD file must have readable units if ``convert_units`` is" " set to ``True``. MDAnalysis sets ``convert_units=True`` by default." " Set ``convert_units=False`` to load Universe without units." if unit == 'time': if self.units['time'] is None: raise ValueError(errmsg) else: if self._has[group]: if self.units[unit] is None: raise ValueError(errmsg) @staticmethod def _format_hint(thing): """Can this Reader read *thing*""" # nb, filename strings can still get passed through if # format='H5MD' is used return HAS_H5PY and isinstance(thing, h5py.File)
[docs] def open_trajectory(self): """opens the trajectory file using h5py library""" self._frame = -1 if isinstance(self.filename, h5py.File): self._file = self.filename self._driver = self._file.driver else: if self._comm is not None: # can only pass comm argument to h5py.File if driver='mpio' assert self._driver == 'mpio' self._file = H5PYPicklable(name=self.filename, # pragma: no cover mode='r', driver=self._driver, comm=self._comm) else: self._file = H5PYPicklable(name=self.filename, mode='r', driver=self._driver) # pulls first key out of 'particles' # allows for arbitrary name of group1 in 'particles' self._particle_group = self._file['particles'][ list(self._file['particles'])[0]]
@property def n_frames(self): """number of frames in trajectory""" for name, value in self._has.items(): if value: return self._particle_group[name]['value'].shape[0] def _read_frame(self, frame): """reads data from h5md file and copies to current timestep""" try: for name, value in self._has.items(): if value: _ = self._particle_group[name]['step'][frame] break else: raise NoDataError("Provide at least a position, velocity" " or force group in the h5md file.") except (ValueError, IndexError): raise IOError from None self._frame = frame ts = self.ts particle_group = self._particle_group ts.frame = frame # fills data dictionary from 'observables' group # Note: dt is not read into data as it is not decided whether # Timestep should have a dt attribute (see Issue #2825) self._copy_to_data() # Sets frame box dimensions # Note: H5MD files must contain 'box' group in each 'particles' group if 'edges' in particle_group['box']: ts.dimensions = core.triclinic_box(*particle_group['box/edges/value'][frame, :]) else: ts.dimensions = None # set the timestep positions, velocities, and forces with # current frame dataset if self._has['position']: self._read_dataset_into_ts('position', ts.positions) if self._has['velocity']: self._read_dataset_into_ts('velocity', ts.velocities) if self._has['force']: self._read_dataset_into_ts('force', ts.forces) if self.convert_units: self._convert_units() return ts def _copy_to_data(self): """assigns values to keys in data dictionary""" if 'observables' in self._file: for key in self._file['observables'].keys(): self.ts.data[key] = self._file['observables'][key][ 'value'][self._frame] # pulls 'time' and 'step' out of first available parent group for name, value in self._has.items(): if value: if 'time' in self._particle_group[name]: self.ts.time = self._particle_group[name][ 'time'][self._frame] break for name, value in self._has.items(): if value: if 'step' in self._particle_group[name]: self.ts.data['step'] = self._particle_group[name][ 'step'][self._frame] break def _read_dataset_into_ts(self, dataset, attribute): """reads position, velocity, or force dataset array at current frame into corresponding ts attribute""" n_atoms_now = self._particle_group[f'{dataset}/value'][ self._frame].shape[0] if n_atoms_now != self.n_atoms: raise ValueError(f"Frame {self._frame} of the {dataset} dataset" f" has {n_atoms_now} atoms but the initial frame" " of either the postion, velocity, or force" f" dataset had {self.n_atoms} atoms." " MDAnalysis is unable to deal" " with variable topology!") self._particle_group[f'{dataset}/value'].read_direct( attribute, source_sel=np.s_[self._frame, :]) def _convert_units(self): """converts time, position, velocity, and force values if they are not given in MDAnalysis standard units See https://userguide.mdanalysis.org/1.0.0/units.html """ self.ts.time = self.convert_time_from_native(self.ts.time) if 'edges' in self._particle_group['box'] and self.ts.dimensions is not None: self.convert_pos_from_native(self.ts.dimensions[:3]) if self._has['position']: self.convert_pos_from_native(self.ts.positions) if self._has['velocity']: self.convert_velocities_from_native(self.ts.velocities) if self._has['force']: self.convert_forces_from_native(self.ts.forces) def _read_next_timestep(self): """read next frame in trajectory""" return self._read_frame(self._frame + 1)
[docs] def close(self): """close reader""" self._file.close()
[docs] def _reopen(self): """reopen trajectory Note ---- If the `driver` and `comm` arguments were used to open the hdf5 file (specifically, ``driver="mpio"``) then this method does *not* close and open the file like most readers because the information about the MPI communicator would be lost; instead it rewinds the trajectory back to the first timstep. """ if self._driver == "mpio": # pragma: no cover self._read_frame(-1) return self.close() self.open_trajectory()
[docs] def Writer(self, filename, n_atoms=None, **kwargs): """Return writer for trajectory format Note ---- The chunk shape of the input file will not be copied to the output file, as :class:`H5MDWriter` uses a chunk shape of ``(1, n_atoms, 3)`` by default. To use a custom chunk shape, you must specify the `chunks` argument. If you would like to copy an existing chunk format from a dataset (positions, velocities, or forces), do the following:: chunks = u.trajectory._particle_group['position/value'].chunks Note that the writer will set the same layout for all particle groups. See Also -------- :class:`H5MDWriter` Output class for the H5MD format .. versionadded:: 2.0.0 """ if n_atoms is None: n_atoms = self.n_atoms kwargs.setdefault('driver', self._driver) kwargs.setdefault('compression', self.compression) kwargs.setdefault('compression_opts', self.compression_opts) kwargs.setdefault('positions', self.has_positions) kwargs.setdefault('velocities', self.has_velocities) kwargs.setdefault('forces', self.has_forces) return H5MDWriter(filename, n_atoms, **kwargs)
@property def has_positions(self): """``True`` if 'position' group is in trajectory.""" return self._has['position'] @has_positions.setter def has_positions(self, value: bool): self._has['position'] = value @property def has_velocities(self): """``True`` if 'velocity' group is in trajectory.""" return self._has['velocity'] @has_velocities.setter def has_velocities(self, value: bool): self._has['velocity'] = value @property def has_forces(self): """``True`` if 'force' group is in trajectory.""" return self._has['force'] @has_forces.setter def has_forces(self, value: bool): self._has['force'] = value def __getstate__(self): state = self.__dict__.copy() del state['_particle_group'] return state def __setstate__(self, state): self.__dict__ = state self._particle_group = self._file['particles'][ list(self._file['particles'])[0]] self[self.ts.frame]
[docs]class H5MDWriter(base.WriterBase): """Writer for `H5MD`_ format (version 1.1). H5MD trajectories are automatically recognised by the file extension ".h5md". All data from the input :class:`~MDAnalysis.coordinates.base.Timestep` is written by default. For detailed information on how :class:`H5MDWriter` handles units, compression, and chunking, see the Notes section below. Note ---- Parellel writing with the use of a MPI communicator and the ``'mpio'`` HDF5 driver is currently not supported. Note ---- :exc:`NoDataError` is raised if no positions, velocities, or forces are found in the input trajectory. While the H5MD standard allows for this case, :class:`H5MDReader` cannot currently read files without at least one of these three groups. Note ---- Writing H5MD files with fancy trajectory slicing where the Timestep does not increase monotonically such as ``u.trajectory[[2,1,0]]`` or ``u.trajectory[[0,1,2,0,1,2]]`` raises a :exc:`ValueError` as this violates the rules of the step dataset in the H5MD standard. Parameters ---------- filename : str or :class:`h5py.File` trajectory filename or open h5py file n_atoms : int number of atoms in trajectory n_frames : int (optional) number of frames to be written in trajectory driver : str (optional) H5PY file driver used to open H5MD file. See `H5PY drivers`_ for list of available drivers. convert_units : bool (optional) Convert units from MDAnalysis to desired units chunks : tuple (optional) Custom chunk layout to be applied to the position, velocity, and force datasets. By default, these datasets are chunked in ``(1, n_atoms, 3)`` blocks compression : str or int (optional) HDF5 dataset compression setting to be applied to position, velocity, and force datasets. Allowed settings are 'gzip', 'szip', 'lzf'. If an integer in range(10), this indicates gzip compression level. Otherwise, an integer indicates the number of a dynamically loaded compression filter. compression_opts : int or tup (optional) Compression settings. This is an integer for gzip, 2-tuple for szip, etc. If specifying a dynamically loaded compression filter number, this must be a tuple of values. For gzip, 1 indicates the lowest level of compression and 9 indicates maximum compression. positions : bool (optional) Write positions into the trajectory [``True``] velocities : bool (optional) Write velocities into the trajectory [``True``] forces : bool (optional) Write forces into the trajectory [``True``] timeunit : str (optional) Option to convert values in the 'time' dataset to a custom unit, must be recognizable by MDAnalysis lengthunit : str (optional) Option to convert values in the 'position/value' dataset to a custom unit, must be recognizable by MDAnalysis velocityunit : str (optional) Option to convert values in the 'velocity/value' dataset to a custom unit, must be recognizable by MDAnalysis forceunit : str (optional) Option to convert values in the 'force/value' dataset to a custom unit, must be recognizable by MDAnalysis author : str (optional) Name of the author of the file author_email : str (optional) Email of the author of the file creator : str (optional) Software that wrote the file [``MDAnalysis``] creator_version : str (optional) Version of software that wrote the file [:attr:`MDAnalysis.__version__`] Raises ------ RuntimeError when `H5PY`_ is not installed ValueError when `n_atoms` is 0 ValueError when ``chunks=False`` but the user did not specify `n_frames` ValueError when `positions`, `velocities`, and `forces` are all set to ``False`` TypeError when the input object is not a :class:`Universe` or :class:`AtomGroup` IOError when `n_atoms` of the :class:`Universe` or :class:`AtomGroup` being written does not match `n_atoms` passed as an argument to the writer ValueError when any of the optional `timeunit`, `lengthunit`, `velocityunit`, or `forceunit` keyword arguments are not recognized by MDAnalysis Notes ----- By default, the writer will write all available data (positions, velocities, and forces) if detected in the input :class:`~MDAnalysis.coordinates.base.Timestep`. In addition, the settings for `compression` and `compression_opts` will be read from the first available group of positions, velocities, or forces and used as the default value. To write a file without any one of these datsets, set `positions`, `velocities`, or `forces` to ``False``. .. rubric:: Units The H5MD format is very flexible with regards to units, as there is no standard defined unit for the format. For this reason, :class:`H5MDWriter` does not enforce any units. The units of the written trajectory can be set explicitly with the keyword arguments `lengthunit`, `velocityunit`, and `forceunit`. If units are not explicitly specified, they are set to the native units of the trajectory that is the source of the coordinates. For example, if one converts a DCD trajectory, then positions are written in ångstrom and time in AKMA units. A GROMACS XTC will be written in nm and ps. The units are stored in the metadata of the H5MD file so when MDAnalysis loads the H5MD trajectory, the units will be automatically set correctly. .. rubric:: Compression HDF5 natively supports various compression modes. To write the trajectory with compressed datasets, set ``compression='gzip'``, ``compression='lzf'`` , etc. See `H5PY compression options`_ for all supported modes of compression. An additional argument, `compression_opts`, can be used to fine tune the level of compression. For example, for GZIP compression, `compression_opts` can be set to 1 for minimum compression and 9 for maximum compression. .. rubric:: HDF5 Chunking HDF5 datasets can be *chunked*, meaning the dataset can be split into equal sized pieces and stored in different, noncontiguous places on disk. If HDF5 tries to read an element from a chunked dataset, the *entire* dataset must be read, therefore an ill-thought-out chunking scheme can drastically effect file I/O performance. In the case of all MDAnalysis writers, in general, the number of frames being written is not known apriori by the writer, therefore the HDF5 must be extendable. However, the allocation of diskspace is defined when the dataset is created, therefore extendable HDF5 datasets *must* be chunked so as to allow dynamic storage on disk of any incoming data to the writer. In such cases where chunking isn't explicity defined by the user, H5PY automatically selects a chunk shape via an algorithm that attempts to make mostly square chunks between 1 KiB - 1 MiB, however this can lead to suboptimal I/O performance. :class:`H5MDWriter` uses a default chunk shape of ``(1, n_atoms, 3)``so as to mimic the typical access pattern of a trajectory by MDAnalysis. In our tests ([Jakupovic2021]_), this chunk shape led to a speedup on the order of 10x versus H5PY's auto-chunked shape. Users can set a custom chunk shape with the `chunks` argument. Additionaly, the datasets in a file can be written with a contiguous layout by setting ``chunks=False``, however this must be accompanied by setting `n_frames` equal to the number of frames being written, as HDF5 must know how much space to allocate on disk when creating the dataset. .. _`H5PY compression options`: https://docs.h5py.org/en/stable/high/dataset.html#filter-pipeline .. _`H5PY drivers`: https://docs.h5py.org/en/stable/high/file.html#file-drivers .. versionadded:: 2.0.0 """ format = 'H5MD' multiframe = True #: These variables are not written from :attr:`Timestep.data` #: dictionary to the observables group in the H5MD file data_blacklist = ['step', 'time', 'dt'] #: currently written version of the file format H5MD_VERSION = (1, 1) # This dictionary is used to translate MDAnalysis units to H5MD units. # (https://nongnu.org/h5md/modules/units.html) _unit_translation_dict = { 'time': { 'ps': 'ps', 'fs': 'fs', 'ns': 'ns', 'second': 's', 'sec': 's', 's': 's', 'AKMA': 'AKMA'}, 'length': { 'Angstrom': 'Angstrom', 'angstrom': 'Angstrom', 'A': 'Angstrom', 'nm': 'nm', 'pm': 'pm', 'fm': 'fm'}, 'velocity': { 'Angstrom/ps': 'Angstrom ps-1', 'A/ps': 'Angstrom ps-1', 'Angstrom/fs': 'Angstrom fs-1', 'A/fs': 'Angstrom fs-1', 'Angstrom/AKMA': 'Angstrom AKMA-1', 'A/AKMA': 'Angstrom AKMA-1', 'nm/ps': 'nm ps-1', 'nm/ns': 'nm ns-1', 'pm/ps': 'pm ps-1', 'm/s': 'm s-1'}, 'force': { 'kJ/(mol*Angstrom)': 'kJ mol-1 Angstrom-1', 'kJ/(mol*nm)': 'kJ mol-1 nm-1', 'Newton': 'Newton', 'N': 'N', 'J/m': 'J m-1', 'kcal/(mol*Angstrom)': 'kcal mol-1 Angstrom-1', 'kcal/(mol*A)': 'kcal mol-1 Angstrom-1'}} @due.dcite(Doi("10.25080/majora-1b6fd038-005"), description="MDAnalysis trajectory reader/writer of the H5MD" "format", path=__name__) @due.dcite(Doi("10.1016/j.cpc.2014.01.018"), description="Specifications of the H5MD standard", path=__name__, version='1.1') def __init__(self, filename, n_atoms, n_frames=None, driver=None, convert_units=True, chunks=None, compression=None, compression_opts=None, positions=True, velocities=True, forces=True, timeunit=None, lengthunit=None, velocityunit=None, forceunit=None, author='N/A', author_email=None, creator='MDAnalysis', creator_version=mda.__version__, **kwargs): if not HAS_H5PY: raise RuntimeError("H5MDWriter: Please install h5py") self.filename = filename if n_atoms == 0: raise ValueError("H5MDWriter: no atoms in output trajectory") self._driver = driver if self._driver == 'mpio': raise ValueError("H5MDWriter: parallel writing with MPI I/O " "is not currently supported.") self.n_atoms = n_atoms self.n_frames = n_frames self.chunks = (1, n_atoms, 3) if chunks is None else chunks if self.chunks is False and self.n_frames is None: raise ValueError("H5MDWriter must know how many frames will be " "written if ``chunks=False``.") self.contiguous = self.chunks is False and self.n_frames is not None self.compression = compression self.compression_opts = compression_opts self.convert_units = convert_units self.h5md_file = None # The writer defaults to writing all data from the parent Timestep if # it exists. If these are True, the writer will check each # Timestep.has_* value and fill the self._has dictionary accordingly # in _initialize_hdf5_datasets() self._write_positions = positions self._write_velocities = velocities self._write_forces = forces if not any([self._write_positions, self._write_velocities, self._write_velocities]): raise ValueError("At least one of positions, velocities, or " "forces must be set to ``True``.") self._new_units = {'time': timeunit, 'length': lengthunit, 'velocity': velocityunit, 'force': forceunit} # Pull out various keywords to store metadata in 'h5md' group self.author = author self.author_email = author_email self.creator = creator self.creator_version = creator_version def _write_next_frame(self, ag): """Write information associated with ``ag`` at current frame into trajectory Parameters ---------- ag : AtomGroup or Universe """ try: # Atomgroup? ts = ag.ts except AttributeError: try: # Universe? ts = ag.trajectory.ts except AttributeError: errmsg = "Input obj is neither an AtomGroup or Universe" raise TypeError(errmsg) from None if ts.n_atoms != self.n_atoms: raise IOError("H5MDWriter: Timestep does not have" " the correct number of atoms") # This should only be called once when first timestep is read. if self.h5md_file is None: self._determine_units(ag) self._open_file() self._initialize_hdf5_datasets(ts) return self._write_next_timestep(ts) def _determine_units(self, ag): """determine which units the file will be written with By default, it fills the :attr:`self.units` dictionary by copying the units dictionary of the parent file. Because H5MD files have no standard unit restrictions, users may pass a kwarg in ``(timeunit, lengthunit, velocityunit, forceunit)`` to the writer so long as MDAnalysis has a conversion factor for it (:exc:`ValueError` raised if it does not). These custom unit arguments must be in `MDAnalysis notation`_. If custom units are supplied from the user, :attr`self.units[unit]` is replaced with the corresponding `unit` argument. """ self.units = ag.universe.trajectory.units.copy() # set user input units for key, value in self._new_units.items(): if value is not None: if value not in self._unit_translation_dict[key]: raise ValueError(f"{value} is not a unit recognized by" " MDAnalysis. Allowed units are:" f" {self._unit_translation_dict.keys()}" " For more information on units, see" " `MDAnalysis units`_.") else: self.units[key] = self._new_units[key] if self.convert_units: # check if all units are None if not any(self.units.values()): raise ValueError("The trajectory has no units, but " "`convert_units` is set to ``True`` by " "default in MDAnalysis. To write the file " "with no units, set ``convert_units=False``.") def _open_file(self): """Opens file with `H5PY`_ library and fills in metadata from kwargs. :attr:`self.h5md_file` becomes file handle that links to root level. """ self.h5md_file = h5py.File(name=self.filename, mode='w', driver=self._driver) # fill in H5MD metadata from kwargs self.h5md_file.require_group('h5md') self.h5md_file['h5md'].attrs['version'] = np.array(self.H5MD_VERSION) self.h5md_file['h5md'].require_group('author') self.h5md_file['h5md/author'].attrs['name'] = self.author if self.author_email is not None: self.h5md_file['h5md/author'].attrs['email'] = self.author_email self.h5md_file['h5md'].require_group('creator') self.h5md_file['h5md/creator'].attrs['name'] = self.creator self.h5md_file['h5md/creator'].attrs['version'] = self.creator_version def _initialize_hdf5_datasets(self, ts): """initializes all datasets that will be written to by :meth:`_write_next_timestep` Note ---- :exc:`NoDataError` is raised if no positions, velocities, or forces are found in the input trajectory. While the H5MD standard allows for this case, :class:`H5MDReader` cannot currently read files without at least one of these three groups. A future change to both the reader and writer will allow this case. """ # for keeping track of where to write in the dataset self._counter = 0 # ask the parent file if it has positions, velocities, and forces # if prompted by the writer with the self._write_* attributes self._has = {group: getattr(ts, f'has_{attr}') if getattr(self, f'_write_{attr}') else False for group, attr in zip( ('position', 'velocity', 'force'), ('positions', 'velocities', 'forces'))} # initialize trajectory group self.h5md_file.require_group('particles').require_group('trajectory') self._traj = self.h5md_file['particles/trajectory'] self.data_keys = [ key for key in ts.data.keys() if key not in self.data_blacklist] if self.data_keys: self._obsv = self.h5md_file.require_group('observables') # box group is required for every group in 'particles' self._traj.require_group('box') self._traj['box'].attrs['dimension'] = 3 if ts.dimensions is not None and np.all(ts.dimensions > 0): self._traj['box'].attrs['boundary'] = 3*['periodic'] self._traj['box'].require_group('edges') self._edges = self._traj.require_dataset('box/edges/value', shape=(0, 3, 3), maxshape=(None, 3, 3), dtype=np.float32) self._step = self._traj.require_dataset('box/edges/step', shape=(0,), maxshape=(None,), dtype=np.int32) self._time = self._traj.require_dataset('box/edges/time', shape=(0,), maxshape=(None,), dtype=np.float32) self._set_attr_unit(self._edges, 'length') self._set_attr_unit(self._time, 'time') else: # if no box, boundary attr must be "none" according to H5MD self._traj['box'].attrs['boundary'] = 3*['none'] self._create_step_and_time_datasets() if self.has_positions: self._create_trajectory_dataset('position') self._pos = self._traj['position/value'] self._set_attr_unit(self._pos, 'length') if self.has_velocities: self._create_trajectory_dataset('velocity') self._vel = self._traj['velocity/value'] self._set_attr_unit(self._vel, 'velocity') if self.has_forces: self._create_trajectory_dataset('force') self._force = self._traj['force/value'] self._set_attr_unit(self._force, 'force') # intialize observable datasets from ts.data dictionary that # are NOT in self.data_blacklist if self.data_keys: for key in self.data_keys: self._create_observables_dataset(key, ts.data[key]) def _create_step_and_time_datasets(self): """helper function to initialize a dataset for step and time Hunts down first available location to create the step and time datasets. This should only be called if the trajectory has no dimension, otherwise the 'box/edges' group creates step and time datasets since 'box' is the only required group in 'particles'. :attr:`self._step` and :attr`self._time` serve as links to the created datasets that other datasets can also point to for their step and time. This serves two purposes: 1. Avoid redundant writing of multiple datasets that share the same step and time data. 2. In HDF5, each chunked dataset has a cache (default 1 MiB), so only 1 read is required to access step and time data for all datasets that share the same step and time. """ for group, value in self._has.items(): if value: self._step = self._traj.require_dataset(f'{group}/step', shape=(0,), maxshape=(None,), dtype=np.int32) self._time = self._traj.require_dataset(f'{group}/time', shape=(0,), maxshape=(None,), dtype=np.float32) self._set_attr_unit(self._time, 'time') break def _create_trajectory_dataset(self, group): """helper function to initialize a dataset for position, velocity, and force""" if self.n_frames is None: shape = (0, self.n_atoms, 3) maxshape = (None, self.n_atoms, 3) else: shape = (self.n_frames, self.n_atoms, 3) maxshape = None chunks = None if self.contiguous else self.chunks self._traj.require_group(group) self._traj.require_dataset(f'{group}/value', shape=shape, maxshape=maxshape, dtype=np.float32, chunks=chunks, compression=self.compression, compression_opts=self.compression_opts) if 'step' not in self._traj[group]: self._traj[f'{group}/step'] = self._step if 'time' not in self._traj[group]: self._traj[f'{group}/time'] = self._time def _create_observables_dataset(self, group, data): """helper function to initialize a dataset for each observable""" self._obsv.require_group(group) # guarantee ints and floats have a shape () data = np.asarray(data) self._obsv.require_dataset(f'{group}/value', shape=(0,) + data.shape, maxshape=(None,) + data.shape, dtype=data.dtype) if 'step' not in self._obsv[group]: self._obsv[f'{group}/step'] = self._step if 'time' not in self._obsv[group]: self._obsv[f'{group}/time'] = self._time def _set_attr_unit(self, dset, unit): """helper function to set a 'unit' attribute for an HDF5 dataset""" if self.units[unit] is None: return dset.attrs['unit'] = self._unit_translation_dict[unit][self.units[unit]] def _write_next_timestep(self, ts): """Write coordinates and unitcell information to H5MD file. Do not call this method directly; instead use :meth:`write` because some essential setup is done there before writing the first frame. The first dimension of each dataset is extended by +1 and then the data is written to the new slot. Note ---- Writing H5MD files with fancy trajectory slicing where the Timestep does not increase monotonically such as ``u.trajectory[[2,1,0]]`` or ``u.trajectory[[0,1,2,0,1,2]]`` raises a :exc:`ValueError` as this violates the rules of the step dataset in the H5MD standard. """ i = self._counter # H5MD step refers to the integration step at which the data were # sampled, therefore ts.data['step'] is the most appropriate value # to use. However, step is also necessary in H5MD to allow # temporal matching of the data, so ts.frame is used as an alternative self._step.resize(self._step.shape[0]+1, axis=0) try: self._step[i] = ts.data['step'] except(KeyError): self._step[i] = ts.frame if len(self._step) > 1 and self._step[i] < self._step[i-1]: raise ValueError("The H5MD standard dictates that the step " "dataset must increase monotonically in value.") # the dataset.resize() method should work with any chunk shape self._time.resize(self._time.shape[0]+1, axis=0) self._time[i] = ts.time if 'edges' in self._traj['box']: self._edges.resize(self._edges.shape[0]+1, axis=0) self._edges.write_direct(ts.triclinic_dimensions, dest_sel=np.s_[i, :]) # These datasets are not resized if n_frames was provided as an # argument, as they were initialized with their full size. if self.has_positions: if self.n_frames is None: self._pos.resize(self._pos.shape[0]+1, axis=0) self._pos.write_direct(ts.positions, dest_sel=np.s_[i, :]) if self.has_velocities: if self.n_frames is None: self._vel.resize(self._vel.shape[0]+1, axis=0) self._vel.write_direct(ts.velocities, dest_sel=np.s_[i, :]) if self.has_forces: if self.n_frames is None: self._force.resize(self._force.shape[0]+1, axis=0) self._force.write_direct(ts.forces, dest_sel=np.s_[i, :]) if self.data_keys: for key in self.data_keys: obs = self._obsv[f'{key}/value'] obs.resize(obs.shape[0]+1, axis=0) obs[i] = ts.data[key] if self.convert_units: self._convert_dataset_with_units(i) self._counter += 1 def _convert_dataset_with_units(self, i): """convert values in the dataset arrays with self.units dictionary""" # Note: simply doing convert_pos_to_native(self._pos[-1]) does not # actually change the values in the dataset, so assignment required if self.units['time'] is not None: self._time[i] = self.convert_time_to_native(self._time[i]) if self.units['length'] is not None: if self._has['position']: self._pos[i] = self.convert_pos_to_native(self._pos[i]) if 'edges' in self._traj['box']: self._edges[i] = self.convert_pos_to_native(self._edges[i]) if self._has['velocity']: if self.units['velocity'] is not None: self._vel[i] = self.convert_velocities_to_native(self._vel[i]) if self._has['force']: if self.units['force'] is not None: self._force[i] = self.convert_forces_to_native(self._force[i]) @property def has_positions(self): """``True`` if writer is writing positions from Timestep.""" return self._has['position'] @property def has_velocities(self): """``True`` if writer is writing velocities from Timestep.""" return self._has['velocity'] @property def has_forces(self): """``True`` if writer is writing forces from Timestep.""" return self._has['force']
[docs]class H5PYPicklable(h5py.File): """H5PY file object (read-only) that can be pickled. This class provides a file-like object (as returned by :class:`h5py.File`) that, unlike standard Python file objects, can be pickled. Only read mode is supported. When the file is pickled, filename, mode, driver, and comm of :class:`h5py.File` in the file are saved. On unpickling, the file is opened by filename, mode, driver. This means that for a successful unpickle, the original file still has to be accessible with its filename. Parameters ---------- filename : str or file-like a filename given a text or byte string. driver : str (optional) H5PY file driver used to open H5MD file Example ------- :: f = H5PYPicklable('filename', 'r') print(f['particles/trajectory/position/value'][0]) f.close() can also be used as context manager:: with H5PYPicklable('filename', 'r'): print(f['particles/trajectory/position/value'][0]) Note ---- Pickling of an `h5py.File` opened with `driver="mpio"` and an MPI communicator is currently not supported See Also --------- :class:`MDAnalysis.lib.picklable_file_io.FileIOPicklable` :class:`MDAnalysis.lib.picklable_file_io.BufferIOPicklable` :class:`MDAnalysis.lib.picklable_file_io.TextIOPicklable` :class:`MDAnalysis.lib.picklable_file_io.GzipPicklable` :class:`MDAnalysis.lib.picklable_file_io.BZ2Picklable` .. versionadded:: 2.0.0 """ def __getstate__(self): driver = self.driver # Current issues: Need a way to retrieve MPI communicator object # from self and pickle MPI.Comm object. Parallel driver is excluded # from test because h5py calls for an MPI configuration when driver is # 'mpio', so this will need to be patched in the test function. if driver == 'mpio': # pragma: no cover raise TypeError("Parallel pickling of `h5py.File` with" # pragma: no cover " 'mpio' driver is currently not supported.") return {'name': self.filename, 'mode': self.mode, 'driver': driver} def __setstate__(self, state): self.__init__(name=state['name'], mode=state['mode'], driver=state['driver']) def __getnewargs__(self): """Override the h5py getnewargs to skip its error message""" return ()