diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst b/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst index df2061400c1..9f32613f107 100644 --- a/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst +++ b/package/doc/sphinx/source/documentation_pages/loading_files/amber.rst @@ -51,7 +51,8 @@ typical string representation found throughout MDAnalysis. The Amber charge is converted to electron charges as used in MDAnalysis and other packages. To get back Amber charges, multiply - by 18.2223. + by 18.2223 (i.e., with + :data:`MDAnalysis.units.chargeUnit_factor['Amber']`). For implementation details, see :mod:`MDAnalysis.topology.TOPParser`. diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst index 2572dbac02d..9018b9bf1c5 100644 --- a/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst +++ b/package/doc/sphinx/source/documentation_pages/loading_files/apbs.rst @@ -1,11 +1,11 @@ .. _load_apbs: -############################################# -Loading Poisson Boltzmann files in MDAnalysis -############################################# +################################################# +Loading Poisson Boltzmann PQR files in MDAnalysis +################################################# -MDAnalysis is able to read and write PQR files produced by -Poisson Boltzmann. +MDAnalysis is able to read and write PQR files produced and read by +typical Poisson Boltzmann solvers such as APBS_. .. _load_pqr: diff --git a/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst b/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst index 455cb7e575b..5f9c25ed8f0 100644 --- a/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst +++ b/package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst @@ -14,7 +14,7 @@ with the latter also providing velocities and forces if these were saved. .. seealso:: `Loading PDB files ` - `Loading XYZ flies ` + `Loading XYZ files ` .. _load_tpr: @@ -22,16 +22,37 @@ with the latter also providing velocities and forces if these were saved. TPR files --------- -MDAnalysis supports reading TPR files created by version 3.3 of Gromacs -onwards. +MDAnalysis supports reading TPR portable topology files created by +version 3.3 of Gromacs onwards; in particular this includes files from +versions 4.x, 5.x, 2016.x, and 2018.x. TPR files are binary files in +XDR format that, despite being binary, are portable between different +computing architectures. + +Full topology information is read, including names, bonds, masses, and +even molecule information. + +For details see :mod:`MDAnalysis.topology.TPRParser`. + .. _load_gro: +GRO files +--------- + +GRO files are ASCII files that contain coordinate (and potentially +velocity) information as well as the unit cell. + +.. Note:: GRO files can also contain trajectories in the form of + multiple coordinate frames but GRO trajectories are + currently not supported. + + Reading GRO files ------------------ +~~~~~~~~~~~~~~~~~ -Stuff about the GRO format specifically +MDAnalysis can use a GRO file both as a topology file and a +coordinate/velocity file. When used as a topology file in a Universe, MDAnalysis will read ``names``, ``ids``, ``resids`` and ``resnames``, @@ -39,20 +60,21 @@ 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`. +:mod:`MDAnalysis.topology.GROParser` and :mod:`MDAnalysis.coordinates.GRO`. + 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. +MDAnalysis can also write single trajectory frames to 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 @@ -87,8 +109,51 @@ For example:: TRR and XTC files ----------------- +Gromacs TRR and XTC files are binary trajectory files. TRR files can +contain positions, velocities and/or forces at full precision as well +as time information, box dimensions, and values of the free energy +perturbation parameter :math:`\lambda` (which is 0 if it is not +used). XTC files only contain positions (together with time and box +information) and are compressed with a lossy algorithm, which reduces +the precision of coordinates to typically 0.001 nm (although this can +be set when running the simulation). MDAnalysis fully supports reading +and writing XTC and TRR trajectories. + +.. SeeAlso:: + MDAnalysis.coordinates.XTC + MDAnalysis.coordinates.TRR + MDAnalysis.lib.formats.libmdaxdr + + +Reading TRR and XTC files +^^^^^^^^^^^^^^^^^^^^^^^^^ + +All information present in the trajectory is read and made available +in the :class:`Timestep`, either as `Timestep.positions`, +`Timestep.velocities`, or `Timestep.forces` (or the corresponding +attributes of AtomGroups). The FEP lambda is stored as an entry in the +:attr:`Timestep.data` dictionary (``Timestep.data['lambda']``). + +Normally, XTC and TRR formats are not random access +formats. MDAnalysis implements an algorithm to jump to any frame in +the trajectory by initially building a list of frames and +offsets. This list is built the first time a trajectory is read and +this frame scanning process may take a while. The list of offsets is +cached and saved to disk as a hidden file that is read the next time +the trajectory file is accessed so that subsequently, loading and +random access in XTC and TRR files is very fast. + + +TODO: + +TRR files may not record positions, velocities, and forces at the same +time point so MDAnalysis DOES WHAT? + + Writing TRR and XTC files ^^^^^^^^^^^^^^^^^^^^^^^^^ +TODO: + Anything interesting about writing these files