From 58a559a97cb11920a34d8353b1013fc31de08827 Mon Sep 17 00:00:00 2001 From: Richard Gowers Date: Sun, 11 Mar 2018 21:50:52 +0000 Subject: [PATCH] added loading_files docs page added Amber and Gromacs stubs added pdbqt stub added hoomd docs stubs too enthusiastic with hoooomd name WIP of new loading files docs added link to GROParser in loading_gro docs added ibisco loading stub added tinker stub added lammps load stubs fixed up docs table added pdb load stubs added charmm load doc stubs more load doc stubs finished stubs for load docs wrote docs for loading ibisco/yasp updated TOP loading docs finished Amber loading docs rearranged gromacs docs typos for docs reworked PQR docs --- package/MDAnalysis/coordinates/GRO.py | 44 ++---- package/MDAnalysis/coordinates/INPCRD.py | 4 - package/MDAnalysis/coordinates/PQR.py | 71 --------- package/MDAnalysis/coordinates/TRJ.py | 52 +------ package/MDAnalysis/coordinates/TRZ.py | 10 -- package/MDAnalysis/topology/GROParser.py | 1 - package/MDAnalysis/topology/TOPParser.py | 36 ----- package/MDAnalysis/topology/TPRParser.py | 59 +------ .../documentation_pages/loading_files.rst | 140 +++++++++++++++++ .../loading_files/amber.rst | 137 ++++++++++++++++ .../loading_files/apbs.rst | 87 +++++++++++ .../loading_files/autodock.rst | 8 + .../loading_files/charmm.rst | 21 +++ .../loading_files/desmond.rst | 11 ++ .../loading_files/dlpoly.rst | 17 ++ .../loading_files/gamess.rst | 10 ++ .../loading_files/gromacs.rst | 147 ++++++++++++++++++ .../loading_files/hoomd.rst | 19 +++ .../loading_files/ibisco.rst | 35 +++++ .../loading_files/lammps.rst | 22 +++ .../loading_files/protein.rst | 16 ++ .../loading_files/tinker.rst | 21 +++ .../loading_files/tripos.rst | 10 ++ .../documentation_pages/loading_files/xyz.rst | 6 + package/doc/sphinx/source/index.rst | 5 +- 25 files changed, 723 insertions(+), 266 deletions(-) create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/amber.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/autodock.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/charmm.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/desmond.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/dlpoly.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/gamess.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/hoomd.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/ibisco.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/protein.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/tinker.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/tripos.rst create mode 100644 package/doc/sphinx/source/documentation_pages/loading_files/xyz.rst diff --git a/package/MDAnalysis/coordinates/GRO.py b/package/MDAnalysis/coordinates/GRO.py index b02e6c201b0..70e8d981617 100644 --- a/package/MDAnalysis/coordinates/GRO.py +++ b/package/MDAnalysis/coordinates/GRO.py @@ -28,39 +28,6 @@ `GRO format`_ which includes a conversion routine for the box. -Writing GRO files ------------------ - -By default any written GRO files will renumber the atom ids to move sequentially -from 1. This can be disabled, and instead the original atom ids kept, by -using the `reindex=False` keyword argument. This is useful when writing a -subsection of a larger Universe while wanting to preserve the original -identities of atoms. - -For example:: - - >>> u = mda.Universe()` - - >>> u.atoms.write('out.gro', reindex=False) - - # OR - >>> with mda.Writer('out.gro', reindex=False) as w: - ... w.write(u.atoms) - - -Classes -------- - -.. autoclass:: Timestep - :members: - -.. autoclass:: GROReader - :members: - -.. autoclass:: GROWriter - :members: - - Developer notes: ``GROWriter`` format strings --------------------------------------------- @@ -96,6 +63,17 @@ vector representation of the unit cell. The rearrangement into the odd gromacs order is done automatically. +Classes +------- + +.. autoclass:: Timestep + :members: + +.. autoclass:: GROReader + :members: + +.. autoclass:: GROWriter + :members: .. _Gromacs: http://www.gromacs.org .. _GRO: http://manual.gromacs.org/current/online/gro.html diff --git a/package/MDAnalysis/coordinates/INPCRD.py b/package/MDAnalysis/coordinates/INPCRD.py index 91a6c948b4f..e9fd29ed282 100644 --- a/package/MDAnalysis/coordinates/INPCRD.py +++ b/package/MDAnalysis/coordinates/INPCRD.py @@ -24,10 +24,6 @@ """INPCRD structure files in MDAnalysis --- :mod:`MDAnalysis.coordinates.INPCRD` ================================================================================ -Read coordinates in Amber_ coordinate/restart file (suffix "inpcrd"). - -.. _Amber: http://ambermd.org/formats.html#restart - Classes ------- diff --git a/package/MDAnalysis/coordinates/PQR.py b/package/MDAnalysis/coordinates/PQR.py index 886b5e27d52..2b8917995e9 100644 --- a/package/MDAnalysis/coordinates/PQR.py +++ b/package/MDAnalysis/coordinates/PQR.py @@ -25,77 +25,6 @@ PQR file format --- :mod:`MDAnalysis.coordinates.PQR` ===================================================== -Read atoms with charges from a PQR_ file (as written by PDB2PQR_). The -following is adopted from the description of the PQR_ format as used by APBS_: - -*MDAnalysis* reads very loosely-formatted PQR files: all fields are -**whitespace-delimited** rather than the strict column formatting mandated -by the PDB_ format. This more liberal formatting allows coordinates -which are larger/smaller than ±999 Å. - -MDAnalysis reads data on a per-line basis from PQR files using the following format:: - - recordName serial atomName residueName chainID residueNumber X Y Z charge radius - -If this fails it is assumed that the *chainID* was omitted and the shorter -format is read:: - - recordName serial atomName residueName residueNumber X Y Z charge radius - -Anything else will raise a :exc:`ValueError`. - -The whitespace is the most important feature of this format: fields -*must* be separated by at least one space or tab character. The fields -are: - -*recordName* - A string which specifies the type of PQR entry and should either be ATOM or - HETATM. -*serial* - An integer which provides the atom index (but note that MDAnalysis renumbers - atoms so one cannot rely on the *serial*) -*atomName* - A string which provides the atom name. -*residueName* - A string which provides the residue name. -*chainID* - An optional string which provides the chain ID of the atom. -*residueNumber* - An integer which provides the residue index. -*X Y Z* - Three floats which provide the atomic coordiantes. -*charge* - A float which provides the atomic charge (in electrons). -*radius* - A float which provides the atomic radius (in Å). - -Clearly, this format can deviate wildly from PDB_ due to the use of whitespaces -rather than specific column widths and alignments. This deviation can be -particularly significant when large coordinate values are used. - -Output should look like this (although the only real requirement is -*whitespace* separation between *all* entries). The chainID is optional -and can be omitted:: - - ATOM 1 N MET 1 -11.921 26.307 10.410 -0.3000 1.8500 - ATOM 36 NH1 ARG 2 -6.545 25.499 3.854 -0.8000 1.8500 - ATOM 37 HH11 ARG 2 -6.042 25.480 4.723 0.4600 0.2245 - - -.. Warning:: Fields *must be white-space separated* or data are read - incorrectly. PDB formatted files are *not* guaranteed to be - white-space separated so extra care should be taken when quickly - converting PDB files into PQR files using simple scripts. - -For example, PQR files created with PDB2PQR_ and the `--whitespace` -option are guaranteed to conform to the above format:: - - pdb2pqr --ff=charmm --whitespace 4ake.pdb 4ake.pqr - -.. _PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/formats/pqr.html -.. _APBS: https://apbs-pdb2pqr.readthedocs.io/en/latest/apbs/index.html -.. _PDB2PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/pdb2pqr/index.html -.. _PDB: http://www.wwpdb.org/documentation/file-format """ from __future__ import absolute_import from six.moves import zip diff --git a/package/MDAnalysis/coordinates/TRJ.py b/package/MDAnalysis/coordinates/TRJ.py index d995922771c..72bf256b30a 100644 --- a/package/MDAnalysis/coordinates/TRJ.py +++ b/package/MDAnalysis/coordinates/TRJ.py @@ -68,16 +68,6 @@ Binary NetCDF trajectories -------------------------- -The `AMBER netcdf`_ format make use of NetCDF_ (Network Common Data -Form) format. Such binary trajectories are recognized in MDAnalysis by -the '.ncdf' suffix and read by the :class:`NCDFReader`. - -Binary trajectories can also contain velocities and forces, and can record the -exact time -step. In principle, the trajectories can be in different units than the AMBER -defaults of ångström and picoseconds but at the moment MDAnalysis only supports -those and will raise a :exc:`NotImplementedError` if anything else is detected. - .. autoclass:: NCDFReader :members: @@ -90,45 +80,6 @@ ASCII TRAJ trajectories ----------------------- -ASCII AMBER_ TRJ coordinate files (as defined in `AMBER TRJ format`_) -are handled by the :class:`TRJReader`. It is also possible to directly -read *bzip2* or *gzip* compressed files. - -AMBER ASCII trajectories are recognised by the suffix '.trj', -'.mdcrd' or '.crdbox (possibly with an additional '.gz' or '.bz2'). - -.. Note:: - - In the AMBER community, these trajectories are often saved with the - suffix '.crd' but this extension conflicts with the CHARMM CRD - format and MDAnalysis *will not correctly autodetect AMBER ".crd" - trajectories*. Instead, explicitly provide the ``format="TRJ"`` - argument to :class:`~MDAnalysis.core.universe.Universe`:: - - u = MDAnalysis.Universe("top.prmtop", "traj.crd", format="TRJ") - - In this way, the AMBER :class:`TRJReader` is used. - - -.. rubric:: Limitations - -* Periodic boxes are only stored as box lengths A, B, C in an AMBER - trajectory; the reader always assumes that these are orthorhombic - boxes. - -* The trajectory does not contain time information so we simply set - the time step to 1 ps (or the user could provide it as kwarg *dt*) - -* **No direct access of frames is implemented, only iteration through - the trajectory.** - -* Trajectories with fewer than 4 atoms probably fail to be read (BUG). - -* If the trajectory contains exactly *one* atom then it is always - assumed to be non-periodic (for technical reasons). - -* Velocities are currently *not supported* as ASCII trajectories. - .. autoclass:: TRJReader :members: @@ -145,8 +96,7 @@ .. The formats page was archived as .. http://www.webcitation.org/query?url=http%3A%2F%2Fambermd.org%2Fnetcdf%2Fnctraj.xhtml&date=2018-02-11 .. Use the archived version if the original disappears. [orbeckst] -.. _AMBER netcdf: http://ambermd.org/netcdf/nctraj.xhtml -.. _NetCDF: http://www.unidata.ucar.edu/software/netcdf + .. _Issue Tracker: https://github.com/MDAnalysis/mdanalysis/issues .. _MDAnalysis mailinglist: https://groups.google.com/group/mdnalysis-discussion diff --git a/package/MDAnalysis/coordinates/TRZ.py b/package/MDAnalysis/coordinates/TRZ.py index f23c9db1f88..b562a1f486a 100644 --- a/package/MDAnalysis/coordinates/TRZ.py +++ b/package/MDAnalysis/coordinates/TRZ.py @@ -24,16 +24,6 @@ """TRZ trajectory I/O --- :mod:`MDAnalysis.coordinates.TRZ` ============================================================ -Classes to read `IBIsCO`_ / `YASP`_ TRZ binary trajectories, including -coordinates, velocities and more (see attributes of the :class:`Timestep`). - -Data are read and written in binary representation but because this depends on -the machine hardware architecture, MDAnalysis *always* reads and writes TRZ -trajectories in *little-endian* byte order. - -.. _IBIsCO: http://www.theo.chemie.tu-darmstadt.de/ibisco/IBISCO.html -.. _YASP: http://www.theo.chemie.tu-darmstadt.de/group/services/yaspdoc/yaspdoc.html - Classes ------- diff --git a/package/MDAnalysis/topology/GROParser.py b/package/MDAnalysis/topology/GROParser.py index 7d2a29741aa..21346b3ceae 100644 --- a/package/MDAnalysis/topology/GROParser.py +++ b/package/MDAnalysis/topology/GROParser.py @@ -40,7 +40,6 @@ .. autoclass:: GROParser :members: - :inherited-members: """ from __future__ import absolute_import diff --git a/package/MDAnalysis/topology/TOPParser.py b/package/MDAnalysis/topology/TOPParser.py index 2717f6219b5..4857fd7c32c 100644 --- a/package/MDAnalysis/topology/TOPParser.py +++ b/package/MDAnalysis/topology/TOPParser.py @@ -24,42 +24,6 @@ AMBER PRMTOP topology parser ============================ -Reads an AMBER top file to build the system. - -Amber keywords are turned into the following attributes: - -+-----------------+----------------------+ -| AMBER flag | MDAnalysis attribute | -+-----------------+----------------------+ -| ATOM_NAME | names | -+-----------------+----------------------+ -| CHARGE | charges | -+-----------------+----------------------+ -| ATOMIC_NUMBER | elements | -+-----------------+----------------------+ -| MASS | masses | -+-----------------+----------------------+ -| ATOM_TYPE_INDEX | type_indices | -+-----------------+----------------------+ -| AMBER_ATOM_TYPE | types | -+-----------------+----------------------+ -| RESIDUE_LABEL | resnames | -+-----------------+----------------------+ -| RESIDUE_POINTER | residues | -+-----------------+----------------------+ - -TODO: - Add reading of bonds etc - -.. Note:: - - The Amber charge is converted to electron charges as used in - MDAnalysis and other packages. To get back Amber charges, multiply - by 18.2223. - -.. _`PARM parameter/topology file specification`: - http://ambermd.org/formats.html#topology - Classes ------- diff --git a/package/MDAnalysis/topology/TPRParser.py b/package/MDAnalysis/topology/TPRParser.py index aaa11978c1e..d0d1c2731cd 100644 --- a/package/MDAnalysis/topology/TPRParser.py +++ b/package/MDAnalysis/topology/TPRParser.py @@ -28,69 +28,12 @@ """Gromacs portable run input TPR format parser ============================================ -The :mod:`~MDAnalysis.topology.TPRParser` module allows reading of a -Gromacs_ portable run input file (a `TPR file`_). Because -the file format of the TPR file is changing rapidly, not all versions -are currently supported. The known working versions and the -approximate Gromacs release numbers are listed in the table -:ref:`TPR format versions `. - -.. _`TPR-format-table`: - -.. table:: TPR format versions and generations read by :func:`MDAnalysis.topology.TPRParser.parse`. - - ========== ============== ==================== ===== - TPX format TPX generation Gromacs release read - ========== ============== ==================== ===== - ?? ?? 3.3, 3.3.1 no - - 58 17 4.0, 4.0.2, 4.0.3, yes - 4.0.4, 4.0.5, 4.0.6, - 4.0.7 - - 73 23 4.5.0, 4.5.1, 4.5.2, yes - 4.5.3, 4.5.4, 4.5.5 - - 83 24 4.6, 4.6.1 yes - - 100 26 5.0, 5.0.1, 5.0.2, yes - 5.0.3,5.0.4, 5.0.5 - - 103 26 5.1 yes - - 110 26 2016 yes - ========== ============== ==================== ===== - -For further discussion and notes see `Issue 2`_. Please *open a new issue* in -the `Issue Tracker`_ when a new or different TPR file format version should be -supported. - -Bonded interactions available in Gromacs are described in table 5.5 of the -`Gromacs manual`_. The following ones are used to build the topology (see -`Issue 463`_): - -* bonds: regular bonds (type 1), G96 bonds (type 2), Morse (type 3), - cubic bonds (type 4), connections (type 5), harmonic potentials (type 6), - FENE bonds (type 7), restraint potentials (type 10), - tabulated potential with exclusion/connection (type 8), - tabulated potential without exclusion/connection (type 9), constraints with - exclusion/connection (type 1), constraints without exclusion/connection (type - 2) -* angles: regular angles (type 1), G96 angles (type 2), cross bond-bond - (type3), cross-bond-angle (type 4), Urey-Bradley (type 5), quartic angles - (type 6), restricted bending potential (type 10), tabulated angles (type 8) -* dihedrals: proper dihedrals (type 1 and type 9), Ryckaert-Bellemans dihedrals - (type 3), Fourier dihedrals (type 5), restricted dihedrals (type 10), - combined bending-torsion potentials (type 11), tabulated dihedral (type 8) -* impropers: improper dihedrals (type 2), periodic improper dihedrals (type 4) - - Classes ------- .. autoclass:: TPRParser :members: - :inherited-members: + See Also -------- diff --git a/package/doc/sphinx/source/documentation_pages/loading_files.rst b/package/doc/sphinx/source/documentation_pages/loading_files.rst new file mode 100644 index 00000000000..854a254cb52 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files.rst @@ -0,0 +1,140 @@ +################## +Loading your data +################## + + +Basic Usage +=========== + + +MDAnalysis aims to read any and all molecular simulation data, +from whatever files you provide to it. +This is done via the `Universe` object, +which accepts paths to files as its arguments. +Usually two files are required to create a `Universe` object: +A topology file, which provides information about the names and types of atoms, +and a trajectory file, which gives the positions of atoms over time. + + +This generally corresponds to the file required to set up the simulation acting as the topology, +while the results file of the simulation provides the trajectory. +For example to load results from a CHARMM simulation, +we provide a path to the PSF file to act as a topology, +and a path to the DCD results to act as the trajectory +:: + + import MDAnalysis as mda + + u = mda.Universe('adk.psf', 'adk_dims.dcd') + + +.. note:: If a file which also provides coordinates is used as a topology, no trajectory + information is read from this file. Ie the first frame will come from the trajectory + unless the `all_coordinates` keyword is set to ``True``. + + +Single file Universes +--------------------- + +Occasionally a file may contain both topology and trajectory information, +in such cases it is sufficient to provide only a single filename to Universe +:: + + import MDAnalysis as mda + + u = mda.Universe('myfile.pdb') + + +Concatenating trajectories +-------------------------- + +It is also possible to read multiple consecutive trajectories, +(for example if a simulation was restarted), +by passing a list of trajectory filenames. +In this example, frames from `traj1.trr` and `traj2.trr` will be concatenated when iterating through the trajectory. +:: + + import MDAnalysis as mda + + u = mda.Universe('topol.tpr', ['traj1.trr', 'traj2.trr']) + + +Supported formats and further details +===================================== + + + + +This table lists all currently supported file formats in MDAnalysis, +whether they can act as either Topology or Trajectory files, +as well as links to the relevant documentation pages. +In general MDAnalysis will try and extract all available data from a +given file, for full details of what is extracted from each file format +consult the relevant documentation page. + + +Generally the format of a file is automatically detected from the extension, +for example a file called `system.xyz` is recognised as an XYZ file. +This can be overriden by supplying the `topology_format` and `format` keyword +arguments to Universe. +A full list of valid values for these keywords are given in the below table. + + +.. note:: It is possible to pass tarballed/zipped versions of files. The + format detection will work around this. + + +.. _Supported formats: + +.. csv-table:: Table of supported formats + :header: "Source", "Name", "Format", "Topology", "Trajectory", "I/O" + + ":ref:`Amber `", ":ref:`PARM parameter/topology `", "TOP, PRMTOP, PARM7", "Yes", "Yes", "r" + "", ":ref:`Ascii trajectory `", "TRJ, MDCRD", "No", "Yes", "r" + "", ":ref:`Ascii restart `", "INPCRD, RESTRT", "No", "Yes", "r" + "", ":ref:`NetCFD trajectory `", "NCDF, NC", "Minimal", "Yes", "r/w" + ":ref:`Poisson Boltzmann `", ":ref:`PQR files `", "PQR", "Yes", Yes", "r" + ":ref:`Autodock `", ":ref:`Autodock PDBQT files `", "PDBQT", "Yes", "Yes", "r" + ":ref:`Charmm `", ":ref:`PSF files `", "PSF", "Yes", "No", "r" + "", ":ref:`Binary DCD files `", "DCD", "Minimal", "Yes", "r/w" + "", ":ref:`Ascii trajectory `", "CRD", "Minimal", "Yes", "r" + ":ref:`Desmond MD `", ":ref:`DMS trajectory `", "DMS", "Yes", "Yes", "r" + ":ref:`DL Poly `", ":ref:`Ascii History `", "HISTORY", "Yes", "Yes", "r" + "", ":ref:`Ascii config `", "CONFIG", "Yes", "Yes", "r" + ":ref:`GAMESS `", ":ref:`GAMESS `", "GMS, LOG, OUT", "Yes", "Yes", "r" + ":ref:`Gromacs `", ":ref:`Gromos `", "GRO", "Yes", "Yes", "r/w" + "", ":ref:`TPR file `", "TPR", "Yes", "No", "r" + "", ":ref:`TRR trajectory `", "TRR", "Minimal", "Yes", "r/w" + "", ":ref:`XTC trajectory `", "XTC", "Minimal", "Yes", "r/w" + ":ref:`Hoomd `", ":ref:`XML Topology `", "XML", "Yes", "Yes", "r" + "", ":ref:`Global simulation data? `", "GSD", "No", Yes", "r" + ":ref:`IBIsCO and YASP trajectories `", ":ref:`Binary trajectory `", "TRZ", "Minimal", "Yes", "r/w" + ":ref:`Lammps `", ":ref:`Data file `", "DATA", "Yes", "Yes", "r" + "", ":ref:`Binary DCD `", "DCD", "Minimal", "Yes", "r/w" + ":ref:`Protein Databank `", ":ref:`PDB `", "PDB, ENT, XPDB", "Yes", Yes", "r/w" + "", ":ref:`Macromolecular transmission format `", "MMTF", "Yes", "Yes", "r" + ":ref:`Tinker `", ":ref:`Extended XYZ `", "TXYZ", "Yes", "Yes", "r" + ":ref:`Tripos `", ":ref:`MOL2 `", "MOL2", "Yes", "Yes", "r/w" + ":ref:`XYZ files `", ":ref:`Ascii XYZ files `", "XYZ", "Yes", "Yes", "r/w" + +.. toctree:: + :maxdepth: 2 + :hidden: + + ./loading_files/amber + ./loading_files/apbs + ./loading_files/autodock + ./loading_files/charmm + ./loading_files/desmond + ./loading_files/dlpoly + ./loading_files/gamess + ./loading_files/gromacs + ./loading_files/hoomd + ./loading_files/ibisco + ./loading_files/lammps + ./loading_files/protein + ./loading_files/tinker + ./loading_files/tripos + ./loading_files/xyz + + diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst b/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst new file mode 100644 index 00000000000..df2061400c1 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst @@ -0,0 +1,137 @@ +.. _loading_amber: + +################################### +Loading Amber files with MDAnalysis +################################### + +MDAnalysis can read PRMTOP files as topologies and +NCDF and ascii coordinate and restart files as trajectories from +`Amber MD`_ simulations. +Typically using NCDF as the trajectory format will give the best performance +as all other trajectory formats are ascii based. + +.. _Amber MD: http://ambermd.org + +.. _load_amber_top: + +Loading Amber PRMTOP files +-------------------------- + +MDAnalysis reads `TOP format`_ files with an extension of ``TOP``, +``PRMTOP`` or ``PARM7``. +The below table shows the relationship between Amber flags and the attribute +created in MDAnalysis: +The ``type_indices`` attribute is unique to Amber formats and is +an *integer* representation of the atom type, rather than the +typical string representation found throughout MDAnalysis. + +.. table:: Mapping of Amber flags to MDAnalysis attributes + + +-----------------+----------------------+ + | AMBER flag | MDAnalysis attribute | + +=================+======================+ + | ATOM_NAME | names | + +-----------------+----------------------+ + | CHARGE | charges | + +-----------------+----------------------+ + | ATOMIC_NUMBER | elements | + +-----------------+----------------------+ + | MASS | masses | + +-----------------+----------------------+ + | ATOM_TYPE_INDEX | type_indices | + +-----------------+----------------------+ + | AMBER_ATOM_TYPE | types | + +-----------------+----------------------+ + | RESIDUE_LABEL | resnames | + +-----------------+----------------------+ + | RESIDUE_POINTER | residues | + +-----------------+----------------------+ + +.. note:: + + The Amber charge is converted to electron charges as used in + MDAnalysis and other packages. To get back Amber charges, multiply + by 18.2223. + +For implementation details, see +:mod:`MDAnalysis.topology.TOPParser`. + +.. _`TOP format`: http://ambermd.org/formats.html#topo.cntrl + +.. _load_amber_ncdf: + +Loading Amber NCDF files +------------------------ + +The `AMBER netcdf`_ format make use of NetCDF_ (Network Common Data +Form) format. Such binary trajectories are recognized in MDAnalysis by +the '.ncdf' or '.nc' suffix. + +Binary trajectories can also contain velocities and forces, and can record the +exact time +step. In principle, the trajectories can be in different units than the AMBER +defaults of ångström and picoseconds but at the moment MDAnalysis only supports +those and will raise a :exc:`NotImplementedError` if anything else is detected. + +For implementation details see :class:`MDAnalysis.coordinates.TRJ.NCDFReader`. + +.. _AMBER netcdf: http://ambermd.org/netcdf/nctraj.xhtml +.. _NetCDF: http://www.unidata.ucar.edu/software/netcdf + + +.. _load_amber_trj: + +Loading TRJ files +----------------- + +ASCII `AMBER TRJ coordinate files`_ +are handled by the :class:`TRJReader`. It is also possible to directly +read *bzip2* or *gzip* compressed files. + +AMBER ASCII trajectories are recognised by the suffix '.trj', +'.mdcrd' or '.crdbox (possibly with an additional '.gz' or '.bz2'). + +.. Note:: + + In the AMBER community, these trajectories are often saved with the + suffix '.crd' but this extension conflicts with the CHARMM CRD + format and MDAnalysis *will not correctly autodetect AMBER ".crd" + trajectories*. Instead, explicitly provide the ``format="TRJ"`` + argument to :class:`~MDAnalysis.core.universe.Universe`:: + + u = MDAnalysis.Universe("top.prmtop", "traj.crd", format="TRJ") + + In this way, the format is correct set. + +.. rubric:: Limitations + +* Periodic boxes are only stored as box lengths A, B, C in an AMBER + trajectory; the reader always assumes that these are orthorhombic + boxes. + +* The trajectory does not contain time information so we simply set + the time step to 1 ps (or the user could provide it as kwarg *dt*) + +* Trajectories with fewer than 4 atoms probably fail to be read (BUG). + +* If the trajectory contains exactly *one* atom then it is always + assumed to be non-periodic (for technical reasons). + +* Velocities are currently *not supported* as ASCII trajectories. + +For implementation details see +:class:`MDAnalysis.coordinates.TRJ.TRJReader`. + +.. _AMBER TRJ coordinate files: http://ambermd.org/formats.html#trajectory + +.. _load_amber_restart: + +Loading Amber restart files +--------------------------- + +A single frame of positions can be read from `Amber restart files`_, +which require a file suffix of ``.inpcrd`` or ``.restrt``. +See :mod:`MDAnalysis.coordinates.INPCRD` for implementation details. + +.. _Amber restart files: http://ambermd.org/formats.html#restart + diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst new file mode 100644 index 00000000000..2572dbac02d --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst @@ -0,0 +1,87 @@ +.. _load_apbs: + +############################################# +Loading Poisson Boltzmann files in MDAnalysis +############################################# + +MDAnalysis is able to read and write PQR files produced by +Poisson Boltzmann. + +.. _load_pqr: + +Loading PQR files +----------------- + +Read atoms with charges from a PQR_ file (as written by PDB2PQR_). The +following is adopted from the description of the PQR_ format as used by APBS_: + +*MDAnalysis* reads very loosely-formatted PQR files: all fields are +**whitespace-delimited** rather than the strict column formatting mandated +by the PDB_ format. This more liberal formatting allows coordinates +which are larger/smaller than ±999 Å. + +MDAnalysis reads data on a per-line basis from PQR files using the following format:: + + recordName serial atomName residueName chainID residueNumber X Y Z charge radius + +If this fails it is assumed that the *chainID* was omitted and the shorter +format is read:: + + recordName serial atomName residueName residueNumber X Y Z charge radius + +Anything else will raise a :exc:`ValueError`. + +The whitespace is the most important feature of this format: fields +*must* be separated by at least one space or tab character. The fields +are: + +*recordName* + A string which specifies the type of PQR entry and should either be ATOM or + HETATM. +*serial* + An integer which provides the atom index (but note that MDAnalysis renumbers + atoms so one cannot rely on the *serial*) +*atomName* + A string which provides the atom name. +*residueName* + A string which provides the residue name. +*chainID* + An optional string which provides the chain ID of the atom. +*residueNumber* + An integer which provides the residue index. +*X Y Z* + Three floats which provide the atomic coordiantes. +*charge* + A float which provides the atomic charge (in electrons). +*radius* + A float which provides the atomic radius (in Å). + +Clearly, this format can deviate wildly from PDB_ due to the use of whitespaces +rather than specific column widths and alignments. This deviation can be +particularly significant when large coordinate values are used. + +Output should look like this (although the only real requirement is +*whitespace* separation between *all* entries). The chainID is optional +and can be omitted:: + + ATOM 1 N MET 1 -11.921 26.307 10.410 -0.3000 1.8500 + ATOM 36 NH1 ARG 2 -6.545 25.499 3.854 -0.8000 1.8500 + ATOM 37 HH11 ARG 2 -6.042 25.480 4.723 0.4600 0.2245 + + +.. Warning:: Fields *must be white-space separated* or data are read + incorrectly. PDB formatted files are *not* guaranteed to be + white-space separated so extra care should be taken when quickly + converting PDB files into PQR files using simple scripts. + +For example, PQR files created with PDB2PQR_ and the `--whitespace` +option are guaranteed to conform to the above format:: + + pdb2pqr --ff=charmm --whitespace 4ake.pdb 4ake.pqr + +.. seealso:: For implementation details, see :mod:`MDAnalysis.coordinates.PQR` + +.. _PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/formats/pqr.html +.. _APBS: https://apbs-pdb2pqr.readthedocs.io/en/latest/apbs/index.html +.. _PDB2PQR: https://apbs-pdb2pqr.readthedocs.io/en/latest/pdb2pqr/index.html +.. _PDB: http://www.wwpdb.org/documentation/file-format diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/autodock.rst b/package/doc/sphinx/source/documentation_pages/loading_files/autodock.rst new file mode 100644 index 00000000000..6cc3f632e5a --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/autodock.rst @@ -0,0 +1,8 @@ +.. _load_pdbqt: + +###################################### +Loading Autodock files with MDAnalysis +###################################### + +All about pdbqt files + diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/charmm.rst b/package/doc/sphinx/source/documentation_pages/loading_files/charmm.rst new file mode 100644 index 00000000000..d20416147f4 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/charmm.rst @@ -0,0 +1,21 @@ +.. _load_charmm: + +#################################### +Loading CHARMM files with MDAnalysis +#################################### + +.. _load_psf: + +Loading PSF files +----------------- + + +.. _load_dcd: + +Loading DCD files +----------------- + +.. _load_crd: + +Loading CRD files +----------------- diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/desmond.rst b/package/doc/sphinx/source/documentation_pages/loading_files/desmond.rst new file mode 100644 index 00000000000..ec3f7ecee9f --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/desmond.rst @@ -0,0 +1,11 @@ +.. _load_desmond: + +######################################## +Loading Desmond MD files with MDAnalysis +######################################## + + +.. _load_dms: + +Loading DMS files +----------------- diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/dlpoly.rst b/package/doc/sphinx/source/documentation_pages/loading_files/dlpoly.rst new file mode 100644 index 00000000000..1c30f16d6f2 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/dlpoly.rst @@ -0,0 +1,17 @@ +.. _load_dlpoly: + +##################################### +Loading DL Poly files with MDAnalysis +##################################### + + +.. _load_history: + +Loading HISTORY files +--------------------- + + +.. _load_config: + +Loading CONFIG files +-------------------- diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/gamess.rst b/package/doc/sphinx/source/documentation_pages/loading_files/gamess.rst new file mode 100644 index 00000000000..8de47737be0 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/gamess.rst @@ -0,0 +1,10 @@ +.. _load_gamess: + +#################################### +Loading GAMESS files with MDAnalysis +#################################### + +.. _load_gms: + +Loading GMS files +----------------- diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst b/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst new file mode 100644 index 00000000000..1ee7a4818c4 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst @@ -0,0 +1,147 @@ +.. _loading_gromacs: + +################################### +Loading Gromacs files in MDAnalysis +################################### + +MDAnalysis is able to read most files used by Gromacs with the exception +of the TNG format which is currently in development. +The TPR file provides a wide variety of topology attributes +and should be used where possible, +however it is also possible to use either a GRO or similar ASCII file. +For the trajectory either an XTC or TRR file can be used, +with the latter also providing velocities and forces if these were saved. + +.. seealso:: + `Loading PDB files ` + `Loading XYZ flies ` + + +.. _load_tpr: + +TPR files +--------- + +The :mod:`~MDAnalysis.topology.TPRParser` module allows reading of a +Gromacs_ portable run input file (a `TPR file`_). Because +the file format of the TPR file is changing rapidly, not all versions +are currently supported. The known working versions and the +approximate Gromacs release numbers are listed in the table +:ref:`TPR format versions `. + +.. _`TPR-format-table`: + +.. table:: TPR format versions and generations read by :func:`MDAnalysis.topology.TPRParser.parse`. + + ========== ============== ==================== ===== + TPX format TPX generation Gromacs release read + ========== ============== ==================== ===== + ?? ?? 3.3, 3.3.1 no + + 58 17 4.0, 4.0.2, 4.0.3, yes + 4.0.4, 4.0.5, 4.0.6, + 4.0.7 + + 73 23 4.5.0, 4.5.1, 4.5.2, yes + 4.5.3, 4.5.4, 4.5.5 + + 83 24 4.6, 4.6.1 yes + + 100 26 5.0, 5.0.1, 5.0.2, yes + 5.0.3,5.0.4, 5.0.5 + + 103 26 5.1 yes + + 110 26 2016 yes + ========== ============== ==================== ===== + +For further discussion and notes see `Issue 2`_. Please *open a new issue* in +the `Issue Tracker`_ when a new or different TPR file format version should be +supported. + +Bonded interactions available in Gromacs are described in table 5.5 of the +`Gromacs manual`_. The following ones are used to build the topology (see +`Issue 463`_): + +* bonds: regular bonds (type 1), G96 bonds (type 2), Morse (type 3), + cubic bonds (type 4), connections (type 5), harmonic potentials (type 6), + FENE bonds (type 7), restraint potentials (type 10), + tabulated potential with exclusion/connection (type 8), + tabulated potential without exclusion/connection (type 9), constraints with + exclusion/connection (type 1), constraints without exclusion/connection (type + 2) +* angles: regular angles (type 1), G96 angles (type 2), cross bond-bond + (type3), cross-bond-angle (type 4), Urey-Bradley (type 5), quartic angles + (type 6), restricted bending potential (type 10), tabulated angles (type 8) +* dihedrals: proper dihedrals (type 1 and type 9), Ryckaert-Bellemans dihedrals + (type 3), Fourier dihedrals (type 5), restricted dihedrals (type 10), + combined bending-torsion potentials (type 11), tabulated dihedral (type 8) +* impropers: improper dihedrals (type 2), periodic improper dihedrals (type 4) + +.. _load_gro: + + +Reading GRO files +----------------- + +Stuff about the GRO format specifically + +When used as a topology file in a Universe, MDAnalysis will read +``names``, ``ids``, ``resids`` and ``resnames``, +and guess ``masses`` and ``types`` based on the names of atoms. +The ``segid`` for of all atoms is set to "``SYSTEM``". + +For implementation details see +:mod:`MDAnalysis.topology.GROParser`. + + +Writing GRO files +^^^^^^^^^^^^^^^^^ + +MDAnalysis can also write GRO files, for example using the +:meth:`~MDAnalysis.core.groups.AtomGroup.write` method. +It will attempt to use the ``name``, ``resname`` and ``resid`` attribute +from atoms if available, otherwise default values of "``X``", "``UNK``" +and "``1``" respectively will be used. +If the provided atoms have velocities these will also be written, +otherwise only the positions will be written. +The precision is limited to three decimal places. + +By default any written GRO files will renumber the atom ids to move sequentially +from 1. This can be disabled, and instead the original atom ids kept, by +using the ``reindex=False`` keyword argument. This is useful when writing a +subsection of a larger Universe while wanting to preserve the original +identities of atoms. + +For example:: + + >>> u = mda.Universe()` + + >>> u.atoms.write('out.gro', reindex=False) + + # OR + >>> with mda.Writer('out.gro', reindex=False) as w: + ... w.write(u.atoms) + + + + +.. Links +.. _Gromacs: http://www.gromacs.org +.. _`Gromacs manual`: http://manual.gromacs.org/documentation/5.1/manual-5.1.pdf +.. _TPR file: http://manual.gromacs.org/current/online/tpr.html +.. _`Issue Tracker`: https://github.com/MDAnalysis/mdanalysis/issues +.. _`Issue 2`: https://github.com/MDAnalysis/mdanalysis/issues/2 +.. _`Issue 463`: https://github.com/MDAnalysis/mdanalysis/pull/463 +.. _TPRReaderDevelopment: https://github.com/MDAnalysis/mdanalysis/wiki/TPRReaderDevelopment + +.. _load_trr: + +TRR and XTC files +----------------- + + +Writing TRR and XTC files +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Anything interesting about writing these files diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/hoomd.rst b/package/doc/sphinx/source/documentation_pages/loading_files/hoomd.rst new file mode 100644 index 00000000000..99c4386ec99 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/hoomd.rst @@ -0,0 +1,19 @@ +.. _load_hoomd: + +################################### +Loading Hoomd files with MDAnalysis +################################### + +.. _load_xml: + +Loading XML topologies with MDAnalysis +-------------------------------------- + +XML topologies in MDA + +.. _load_gsd: + +Loading GSD files with MDAnalysis +--------------------------------- + +GSD files in MDA. diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/ibisco.rst b/package/doc/sphinx/source/documentation_pages/loading_files/ibisco.rst new file mode 100644 index 00000000000..4b616b5da50 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/ibisco.rst @@ -0,0 +1,35 @@ +.. _load_ibisco: + +############################################# +Loading IBIsCO and YASP files with MDAnalysis +############################################# + +MDAnalysis is able to read `IBIsCO`_ / `YASP`_ TRZ binary trajectories, including +the coordinates and velocities as well as: + + - ``pressure`` + - ``pressure_tensor`` + - ``total_energy`` + - ``potential_energy`` + - ``kinetic_energy`` + - ``temperature`` + +Which are stored in the ``Timestep.data`` dictionary. For example to view the kinetic +energy for each timestep:: + + for ts in u.trajectory: + print(ts.data['kinetic_energy']) + +Trajectory data are read and written in binary representation but because this depends on +the machine hardware architecture, MDAnalysis *always* reads and writes TRZ +trajectories in *little-endian* byte order. + +For the implementation details, see :mod:`MDAnalysis.coordinates.TRZ`. + +There is currently no support for reading a topology for this format, however the Reader +is able to determine the number of atoms and provide a minimal topology (ie no names etc, +only indices of atoms). To get a topology, it is required to convert an input into an +XYZ or similar format. + +.. _IBIsCO: http://www.theo.chemie.tu-darmstadt.de/ibisco/IBISCO.html +.. _YASP: http://www.theo.chemie.tu-darmstadt.de/group/services/yaspdoc/yaspdoc.html diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst b/package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst new file mode 100644 index 00000000000..09e5d4d9d2a --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst @@ -0,0 +1,22 @@ +.. _load_lammps: + +#################################### +Loading LAMMPS files with MDAnalysis +#################################### + +.. _load_data: + +Loading Data files +------------------ + +attributes provided etc + +see :mod:`MDAnalysis.topology.LAMMPSParser` + + +.. _load_lammps_dcd: + +Loading DCD files +----------------- + +see also charmm docs? diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/protein.rst b/package/doc/sphinx/source/documentation_pages/loading_files/protein.rst new file mode 100644 index 00000000000..a5371dd08ea --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/protein.rst @@ -0,0 +1,16 @@ +.. _load_databank: + +############################################## +Loading Protein Databank files with MDAnalysis +############################################## + +.. _load_pdb: + +Loading PDB files +----------------- + + +.. _load_mmtf: + +Loading MMTF files +------------------ diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/tinker.rst b/package/doc/sphinx/source/documentation_pages/loading_files/tinker.rst new file mode 100644 index 00000000000..8f6880e1c49 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/tinker.rst @@ -0,0 +1,21 @@ +.. _load_tinker: + +################################## +Loading Tinker files in MDAnalysis +################################## + + + +.. _load_txyz: + + +Reading TXYZ files +------------------ + +topology and traj + +populates atom type, bond, position + +see :mod:`MDAnalysis.topology.TXYZParser` + +see :mod:`MDAnalysis.coordinates.TXYZ` diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/tripos.rst b/package/doc/sphinx/source/documentation_pages/loading_files/tripos.rst new file mode 100644 index 00000000000..2d3b91e876d --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/tripos.rst @@ -0,0 +1,10 @@ +.. _load_tripos: + +#################################### +Loading Tripos files with MDAnalysis +#################################### + +.. _load_mol2: + +Loading MOL2 files +------------------ diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/xyz.rst b/package/doc/sphinx/source/documentation_pages/loading_files/xyz.rst new file mode 100644 index 00000000000..7d8bae94965 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/loading_files/xyz.rst @@ -0,0 +1,6 @@ +.. _load_xyz: + +################################# +Loading XYZ files with MDAnalysis +################################# + diff --git a/package/doc/sphinx/source/index.rst b/package/doc/sphinx/source/index.rst index bb3441bb698..694179d0b2b 100644 --- a/package/doc/sphinx/source/index.rst +++ b/package/doc/sphinx/source/index.rst @@ -16,8 +16,8 @@ MDAnalysis documentation toolkit to analyze molecular dynamics trajectories generated by CHARMM_, Gromacs_, Amber_, NAMD_, LAMMPS_, `DL_POLY`_ and other packages; it also reads other formats (e.g., PDB_ files and `XYZ -format`_ trajectories; see :ref:`Supported coordinate formats` and -:ref:`Supported topology formats` for the full lists). It can write +format`_ trajectories; see :ref:`Supported formats` for the full +lists). It can write most of these formats, too, together with atom selections for use in Gromacs_, CHARMM_, VMD_ and PyMol_ (see :ref:`Selection exporters`). @@ -165,6 +165,7 @@ Thank you! :hidden: ./documentation_pages/overview + ./documentation_pages/loading_files ./documentation_pages/topology ./documentation_pages/selections ./documentation_pages/analysis_modules