.. -*- coding: utf-8 -*-
.. MDAnalysis documentation master file, created by
.. sphinx-quickstart on Mon Sep 27 09:39:55 2010.
.. You can adapt this file completely to your liking, but it should at least
.. contain the root `toctree` directive.

###############################
MDAnalysis documentation
###############################


:Release: |release|
:Date: |today|

**MDAnalysis** (`www.mdanalysis.org`_) is an object-oriented python
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
most of these formats, too, together with atom selections for use in
Gromacs_, CHARMM_, VMD_ and PyMol_ (see :ref:`Selection exporters`).

It allows one to read molecular dynamics trajectories and access the
atomic coordinates through `NumPy`_ arrays. This provides a flexible and
relatively fast framework for complex analysis tasks. Fairly complete
atom :ref:`selection-commands-label` are implemented. Trajectories can
also be manipulated (for instance, fit to a reference structure) and
written out in a range of formats.

.. _www.mdanalysis.org: https://www.mdanalysis.org
.. _NumPy: https://numpy.org/
.. _CHARMM:  http://www.charmm.org/
.. _Amber:   http://ambermd.org/
.. _LAMMPS:  http://lammps.sandia.gov/
.. _NAMD:    http://www.ks.uiuc.edu/Research/namd/
.. _Gromacs: http://www.gromacs.org/
.. _`DL_POLY`: https://www.sc.stfc.ac.uk/software/type/computational-materials-and-molecular-science/?searchquery=dl_poly
.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
.. _PyMol: http://www.pymol.org/
.. _PDB: https://www.wwpdb.org/documentation/file-formats-and-the-pdb
.. _XYZ format: https://en.wikipedia.org/wiki/XYZ_file_format


Getting involved
================

Please report **bugs** or **enhancement requests** through the `Issue
Tracker`_. Questions can also be asked on the `GitHub Discussions`_.

The MDAnalysis community follows a `Code of Conduct`_ that all members are expected to adhere to. 
Please take a moment to read it.

.. _Issue Tracker: https://github.com/MDAnalysis/mdanalysis/issues
.. _GitHub Discussions: https://github.com/MDAnalysis/mdanalysis/discussions
.. _Code of Conduct: https://www.mdanalysis.org/pages/conduct/


.. _installation-instructions:

Installing and using MDAnalysis
===============================

The MDAnalysis `User Guide`_ provides comprehensive information on how to `install`_
and use the library. We would recommend that new users have a look at the
`Quick Start Guide`_. The User Guide also has a set of `examples`_ on how to
use the MDAnalysis library which may be of interest.

.. _User Guide: https://userguide.mdanalysis.org/stable/index.html
.. _Quick Start Guide: https://userguide.mdanalysis.org/stable/examples/quickstart.html
.. _examples: https://userguide.mdanalysis.org/stable/examples/README.html
.. _install: https://userguide.mdanalysis.org/stable/installation.html 

Source code
===========

The MDAnalysis source code is available on https://github.com/MDAnalysis/mdanalysis/ and is 
distributed under the `Lesser GNU Public Licence, version 3 or any later version`_. Individual components
of the source code are provided under LGPL compatible licenses, details can be
found in the `MDAnalysis license file`_. Obtain the sources with `git`_.

.. code-block:: bash

   git clone https://github.com/MDAnalysis/mdanalysis.git


The `User Guide`_ provides more information on how to
`install from source`_.

.. _Lesser GNU Public Licence, version 3 or any later version: https://www.gnu.org/licenses/lgpl-3.0.en.html
.. _MDAnalysis license file: https://github.com/MDAnalysis/mdanalysis/blob/develop/LICENSE
.. _git: https://git-scm.com/
.. _install from source: https://userguide.mdanalysis.org/stable/installation.html


Citation
========

When using MDAnalysis in published work, please cite
[Michaud-Agrawal2011]_ and [Gowers2016]_.

MDAnalysis includes specific algorithms and analysis modules, some of which have been published in the scientific literature.  
Please ensure you cite the relevant :ref:`references-components` when using these features in your research.

Thank you!

.. Hide the contents from the front page because they are already in
.. the side bar in the Alabaster sphinx style; requires Alabaster
.. config sidebar_includehidden=True (default)

.. Contents
.. ========

.. toctree::
   :maxdepth: 4
   :caption: Documentation
   :numbered:     
   :hidden:

   ./documentation_pages/overview
   ./documentation_pages/topology
   ./documentation_pages/selections
   ./documentation_pages/analysis_modules
   ./documentation_pages/topology_modules
   ./documentation_pages/guesser_modules
   ./documentation_pages/coordinates_modules
   ./documentation_pages/converters
   ./documentation_pages/trajectory_transformations
   ./documentation_pages/selections_modules
   ./documentation_pages/auxiliary_modules
   ./documentation_pages/core_modules
   ./documentation_pages/visualization_modules
   ./documentation_pages/lib_modules
   ./documentation_pages/version
   ./documentation_pages/units
   ./documentation_pages/exceptions
   ./documentation_pages/references


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`