.. -*- 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`: http://www.scd.stfc.ac.uk//44516.aspx
.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
.. _PyMol: http://www.pymol.org/
.. _PDB: http://www.rcsb.org/pdb/static.do?p=file_formats/pdb/index.html
.. _XYZ format: http://openbabel.org/wiki/XYZ_%28format%29


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

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

The MDAnalysis community subscribes to a `Code of Conduct`_ that all community
members agree and adhere to --- please 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/



User Guide
==========

The MDAnalysis `User Guide`_ provides comprehensive information on how to
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


.. _installation-instructions:

Installing MDAnalysis
=====================

The easiest approach to `install the latest release`_ is to use a package that
can be installed either with conda_ or pip_.

conda
-----

First installation with conda_:

.. code-block:: bash

   conda config --add channels conda-forge
   conda install mdanalysis

which will automatically install a *full set of dependencies*.

To upgrade later:

.. code-block:: bash

   conda update mdanalysis

pip
---

Installation with `pip`_ and a *minimal set of dependencies*:

.. code-block:: bash

   pip install --upgrade MDAnalysis

To install with a *full set of dependencies* (which includes everything needed
for :mod:`MDAnalysis.analysis`), add the ``[analysis]`` tag:

.. code-block:: bash

   pip install --upgrade MDAnalysis[analysis]


Tests
-----

If you want to `run the tests`_ or use example files to follow some of the
examples in the documentation or the tutorials_, also install the
``MDAnalysisTests`` package:

.. code-block:: bash

   conda install mdanalysistests            # with conda
   pip install --upgrade MDAnalysisTests    # with pip

.. _install the latest release:
   https://userguide.mdanalysis.org/stable/installation.html#installation
.. _pip:
   http://www.pip-installer.org/en/latest/index.html
.. _conda:
   http://conda.pydata.org/docs/
.. _run the tests: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests
.. _tutorials: https://www.mdanalysis.org/pages/learning_MDAnalysis/


Source Code
===========

**Source code** is available from
https://github.com/MDAnalysis/mdanalysis/ and is packaged 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 the development version`_ of MDAnalysis.

.. _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 the development version`: https://userguide.mdanalysis.org/stable/installation.html#development-versions


Citation
========

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

MDAnalysis also contains specific algorithms and whole analysis
modules whose algorithms have also been published in the scientific
literature. Please make sure to also reference any
:ref:`references-components` in published work.

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`
