Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updated CHEMFILES docs #3128

Merged
merged 4 commits into from
Mar 13, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions package/MDAnalysis/coordinates/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,10 @@ class can choose an appropriate reader automatically.
| H5MD | h5md | r | H5MD_ file format for coordinates |
| | | | :mod:`MDAnalysis.coordinates.H5MD` |
+---------------+-----------+-------+------------------------------------------------------+
| `chemfiles`_ | CHEMFILES | r/w | interface to `chemfiles`_, see the `list of chemfiles|
| library | | | file formats`_ and |
| | | | :mod:`MDAnalysis.coordinates.chemfiles` |
+---------------+-----------+-------+------------------------------------------------------+

.. [#a] This format can also be used to provide basic *topology*
information (i.e. the list of atoms); it is possible to create a
Expand All @@ -268,6 +272,8 @@ class can choose an appropriate reader automatically.

.. _`netcdf4-python`: https://github.com/Unidata/netcdf4-python
.. _`H5MD`: https://nongnu.org/h5md/index.html
.. _`chemfiles`: https://chemfiles.org/
.. _`list of chemfiles file formats`: https://chemfiles.org/chemfiles/latest/formats.html
orbeckst marked this conversation as resolved.
Show resolved Hide resolved

.. _Trajectory API:

Expand Down
68 changes: 55 additions & 13 deletions package/MDAnalysis/coordinates/chemfiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,64 @@
# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
#
"""
Reading trajectory with Chemfiles --- :mod:`MDAnalysis.coordinates.chemfiles`
=============================================================================
Reading trajectories with *chemfiles* --- :mod:`MDAnalysis.coordinates.chemfiles`
=================================================================================

Classes to read and write files using the `chemfiles`_ library. This library
provides C++ implementation of multiple formats readers and writers, the full
list if available `here <formats>`_.
MDAnalysis interoperates with the `chemfiles`_ library. The *chemfiles* C++ library
supports an expanding set of file formats, some of which are not natively supported by
MDAnalysis. Using the *CHEMFILES* reader you can use `chemfiles`_ for the low-level
file reading. Check the list of `chemfile-supported file formats <formats>`_.

.. _chemfiles: https://chemfiles.org
.. _formats: http://chemfiles.org/chemfiles/latest/formats.html
.. _formats: https://chemfiles.org/chemfiles/0.9.3/formats.html#list-of-supported-formats
.. NOTE: MDAnalysis currently restricts chemfiles to 0.9 <= version < 0.10. Update the link
.. above to the latest documentation once this restriction is lifted.
.. https://chemfiles.org/chemfiles/latest/formats.html#list-of-supported-formats

Using the CHEMFILES reader
--------------------------

When reading, set the ``format="CHEMFILES"`` keyword argument and I/O is delegated to
`chemfiles`_. For example::

>>> import MDAnalysis as mda
>>> from MDAnalysis.tests import datafiles as data
>>> u = mda.Universe(data.TPR, data.TRR, format="CHEMFILES")
>>> print(u.trajectory)
<ChemfilesReader ~/anaconda3/envs/mda3/lib/python3.8/site-packages/MDAnalysisTests/data/adk_oplsaa.trr with 10 frames of 47681 atoms>

You can then use the :class:`~MDAnalysis.core.universe.Universe` as usual while chemfiles
is handling the I/O transparently in the background.

`chemfiles`_ can also *write* a number of formats for which there are no Writers in
MDAnalysis. For example, to write a mol2 file::

>>> u = mda.Universe(data.mol2_ligand)
>>> with mda.Writer("ligand.mol2", format="CHEMFILES") as W:
... W.write(u.atoms)




Classes
-------

Classes to read and write files using the `chemfiles`_ library. This library
provides C++ implementation of multiple formats readers and writers.

.. autoclass:: ChemfilesReader

.. autoclass:: ChemfilesWriter

.. autoclass:: ChemfilesPicklable

Helper functions
----------------

.. autodata:: MIN_CHEMFILES_VERSION
.. autodata:: MAX_CHEMFILES_VERSION
.. autofunction:: check_chemfiles_version

"""
from distutils.version import LooseVersion
import warnings
Expand All @@ -60,14 +100,20 @@ class MockTrajectory:
HAS_CHEMFILES = True


#: Lowest version of chemfiles that is supported
#: by MDAnalysis.
MIN_CHEMFILES_VERSION = LooseVersion("0.9")
#: Lowest version of chemfiles that is *not supported*
#: by MDAnalysis.
MAX_CHEMFILES_VERSION = LooseVersion("0.10")


def check_chemfiles_version():
"""Check an appropriate Chemfiles is available
"""Check if an appropriate *chemfiles* is available

Returns True if a usable chemfiles version is available
Returns ``True`` if a usable chemfiles version is available,
with :data:`MIN_CHEMFILES_VERSION` <= version <
:data:`MAX_CHEMFILES_VERSION`

.. versionadded:: 1.0.0
"""
Expand Down Expand Up @@ -108,13 +154,11 @@ def __init__(self, filename, chemfiles_format="", **kwargs):
chemfiles_format : str (optional)
if *filename* was a string, use the given format name instead of
guessing from the extension. The `list of supported formats
<formats>`_ and the associated names is available in chemfiles
<formats>`_ and the associated names is available in the chemfiles
documentation.
**kwargs : dict
General reader arguments.


.. _formats: http://chemfiles.org/chemfiles/latest/formats.html
"""
if not check_chemfiles_version():
raise RuntimeError("Please install Chemfiles > {}"
Expand Down Expand Up @@ -252,8 +296,6 @@ def __init__(self, filename, n_atoms=0, mode="w", chemfiles_format="", topology=
**kwargs : dict
General writer arguments.


.. _formats: http://chemfiles.org/chemfiles/latest/formats.html
"""
if not check_chemfiles_version():
raise RuntimeError("Please install Chemfiles > {}"
Expand Down