diff --git a/package/doc/sphinx/Makefile b/package/doc/sphinx/Makefile index 071a744aab0..20875d98323 100644 --- a/package/doc/sphinx/Makefile +++ b/package/doc/sphinx/Makefile @@ -1,132 +1,132 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -v -W -PAPER = -BUILDDIR = .. - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - for i in html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex text man changes linkcheck doctest; do \ - rm -rf $(BUILDDIR)/$$i; \ - done - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MDAnalysis.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MDAnalysis.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/MDAnalysis" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MDAnalysis" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build -v -W +PAPER = +BUILDDIR = .. + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + for i in html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex text man changes linkcheck doctest; do \ + rm -rf $(BUILDDIR)/$$i; \ + done + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MDAnalysis.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MDAnalysis.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/MDAnalysis" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MDAnalysis" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/package/doc/sphinx/conf.py b/package/doc/sphinx/conf.py new file mode 100644 index 00000000000..aad31f31aaf --- /dev/null +++ b/package/doc/sphinx/conf.py @@ -0,0 +1,12 @@ +autodoc_mock_imports = [ + "mdahole2", + "PathSimAnalysis", + "waterdynamics", +] +latex_engine = "pdflatex" + +latex_elements = { + "papersize": "letterpaper", + "pointsize": "10pt", + "extraclassoptions": "openany,oneside", +} diff --git a/package/doc/sphinx/doc/sphinx/source/documentation_pages/references.rst b/package/doc/sphinx/doc/sphinx/source/documentation_pages/references.rst new file mode 100644 index 00000000000..e69de29bb2d diff --git a/package/doc/sphinx/source/conf.py b/package/doc/sphinx/source/conf.py index 44070577893..5f03fbd82aa 100644 --- a/package/doc/sphinx/source/conf.py +++ b/package/doc/sphinx/source/conf.py @@ -1,355 +1,355 @@ -# -*- coding: utf-8 -*- -# -# MDAnalysis documentation build configuration file, created by -# sphinx-quickstart on Mon Sep 27 09:39:55 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os -import datetime -import MDAnalysis as mda - -# Custom MDA Formating -from pybtex.style.formatting.unsrt import Style as UnsrtStyle -from pybtex.style.labels import BaseLabelStyle -from pybtex.plugin import register_plugin - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown -# here. - -# make sure sphinx always uses the current branch -sys.path.insert(0, os.path.abspath("../../..")) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.intersphinx", - "sphinx.ext.mathjax", - "sphinx.ext.viewcode", - "sphinx.ext.napoleon", - "sphinx.ext.todo", - "sphinx_sitemap", - "mdanalysis_sphinx_theme", - "sphinxcontrib.bibtex", - "sphinx.ext.doctest", -] - -bibtex_bibfiles = ["references.bib"] - - -# Define custom MDA style for references -class KeyLabelStyle(BaseLabelStyle): - def format_labels(self, entries): - entry_list = [] - for entry in entries: - author = str(entry.persons["author"][0]).split(",")[0] - year = entry.fields["year"] - entry_list.append(f"{author}{year}") - return entry_list - - -class KeyStyle(UnsrtStyle): - default_label_style = "keylabel" - - -register_plugin("pybtex.style.labels", "keylabel", KeyLabelStyle) -register_plugin("pybtex.style.formatting", "MDA", KeyStyle) - -mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML" - -# for sitemap with https://github.com/jdillard/sphinx-sitemap -# This sitemap is correct both for the development and release docs, which -# are both served from docs.mdanalysis.org/$version . -# The docs used to be available automatically at mdanalysis.org/mdanalysis; -# they are now at docs.mdanalysis.org/, which requires a CNAME DNS record -# pointing to mdanalysis.github.io. To change this URL you should change/delete -# the CNAME record for "docs" and update the URL in GitHub settings -site_url = "https://docs.mdanalysis.org/" - -# Add any paths that contain templates here, relative to this directory. -# templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = ".rst" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -# 'index' has the advantage that it is immediately picked up by the webserver -master_doc = "index" - -# General information about the project. -# (take the list from AUTHORS) -# Ordering: (1) Naveen (2) Elizabeth, then all contributors in alphabetical order -# (last) Oliver -author_list = mda.__authors__ -authors = ", ".join(author_list[:-1]) + ", and " + author_list[-1] -project = "MDAnalysis" -now = datetime.datetime.now() -copyright = "2005-{}, ".format(now.year) + authors - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# Dynamically calculate the version -packageversion = __import__("MDAnalysis").__version__ -# The short X.Y version. -# version = '.'.join(packageversion.split('.')[:2]) -version = packageversion # needed for right sitemap.xml URLs -# The full version, including alpha/beta/rc tags. -release = packageversion - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ["_build"] - -# The reST default role (used for this markup: `text`) to use for all documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "default" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# to include decorated objects like __init__ -autoclass_content = "both" - -# to prevent including of member entries in toctree -toc_object_entries = False - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = "mdanalysis_sphinx_theme" - -extra_nav_links = {} -extra_nav_links["MDAnalysis"] = "https://mdanalysis.org" -extra_nav_links["User guide"] = "https://userguide.mdanalysis.org" -extra_nav_links["MDAKits"] = "https://mdakits.mdanalysis.org/" - - -html_theme_options = { - "mda_official": True, - "extra_nav_links": extra_nav_links, -} - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_context = { - "versions_json_url": "https://docs.mdanalysis.org/versions.json" -} - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# For RTD theme: custom.css to override theme defaults. -html_static_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# alabaster sidebars -html_sidebars = { - "**": [ - "about.html", - "navigation.html", - "relations.html", - "searchbox.html", - ] -} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -html_use_opensearch = "https://docs.mdanalysis.org" - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = "MDAnalysisdoc" - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -# latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -# latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ("MDAnalysis.tex", "MDAnalysis Documentation", authors, "manual"), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -# latex_preamble = '' - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [("mdanalysis", "MDAnalysis Documentation", [authors], 1)] - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = "MDAnalysis" -epub_author = authors -epub_publisher = "Arizona State University, Tempe, Arizona, USA" -epub_copyright = "2015, " + authors - -# The language of the text. It defaults to the language option -# or en if the language is not set. -# epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -# epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# epub_identifier = '' - -# A unique identification for the text. -# epub_uid = '' - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# epub_post_files = [] - -# A list of files that should not be packed into the epub file. -# epub_exclude_files = [] - -# The depth of the table of contents in toc.ncx. -# epub_tocdepth = 3 - -# Allow duplicate toc entries. -# epub_tocdup = True - - -# Configuration for intersphinx: refer to the Python standard library -# and other packages used by MDAnalysis -intersphinx_mapping = { - "h5py": ("https://docs.h5py.org/en/stable", None), - "python": ("https://docs.python.org/3/", None), - "scipy": ("https://docs.scipy.org/doc/scipy/", None), - "gsd": ("https://gsd.readthedocs.io/en/stable/", None), - "maplotlib": ("https://matplotlib.org/stable/", None), - "griddataformats": ("https://mdanalysis.org/GridDataFormats/", None), - "pmda": ("https://mdanalysis.org/pmda/", None), - "networkx": ("https://networkx.org/documentation/stable/", None), - "numpy": ("https://numpy.org/doc/stable/", None), - "parmed": ("https://parmed.github.io/ParmEd/html/", None), - "rdkit": ("https://rdkit.org/docs/", None), - "waterdynamics": ("https://www.mdanalysis.org/waterdynamics/", None), - "pathsimanalysis": ("https://www.mdanalysis.org/PathSimAnalysis/", None), - "mdahole2": ("https://www.mdanalysis.org/mdahole2/", None), - "dask": ("https://docs.dask.org/en/stable/", None), - "imdclient": ("https://imdclient.readthedocs.io/en/stable/", None), - "pooch": ("https://www.fatiando.org/pooch/latest/", None), - "requests": ("https://requests.readthedocs.io/en/latest/", None), -} +# -*- coding: utf-8 -*- +# +# MDAnalysis documentation build configuration file, created by +# sphinx-quickstart on Mon Sep 27 09:39:55 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import datetime +import MDAnalysis as mda + +# Custom MDA Formating +from pybtex.style.formatting.unsrt import Style as UnsrtStyle +from pybtex.style.labels import BaseLabelStyle +from pybtex.plugin import register_plugin + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown +# here. + +# make sure sphinx always uses the current branch +sys.path.insert(0, os.path.abspath("../../..")) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.todo", + "sphinx_sitemap", + "mdanalysis_sphinx_theme", + "sphinxcontrib.bibtex", + "sphinx.ext.doctest", +] + +bibtex_bibfiles = ["references.bib"] + + +# Define custom MDA style for references +class KeyLabelStyle(BaseLabelStyle): + def format_labels(self, entries): + entry_list = [] + for entry in entries: + author = str(entry.persons["author"][0]).split(",")[0] + year = entry.fields["year"] + entry_list.append(f"{author}{year}") + return entry_list + + +class KeyStyle(UnsrtStyle): + default_label_style = "keylabel" + + +register_plugin("pybtex.style.labels", "keylabel", KeyLabelStyle) +register_plugin("pybtex.style.formatting", "MDA", KeyStyle) + +mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML" + +# for sitemap with https://github.com/jdillard/sphinx-sitemap +# This sitemap is correct both for the development and release docs, which +# are both served from docs.mdanalysis.org/$version . +# The docs used to be available automatically at mdanalysis.org/mdanalysis; +# they are now at docs.mdanalysis.org/, which requires a CNAME DNS record +# pointing to mdanalysis.github.io. To change this URL you should change/delete +# the CNAME record for "docs" and update the URL in GitHub settings +site_url = "https://docs.mdanalysis.org/" + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = ".rst" + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +# 'index' has the advantage that it is immediately picked up by the webserver +master_doc = "index" + +# General information about the project. +# (take the list from AUTHORS) +# Ordering: (1) Naveen (2) Elizabeth, then all contributors in alphabetical order +# (last) Oliver +author_list = mda.__authors__ +authors = ", ".join(author_list[:-1]) + ", and " + author_list[-1] +project = "MDAnalysis" +now = datetime.datetime.now() +copyright = "2005-{}, ".format(now.year) + authors + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# Dynamically calculate the version +packageversion = __import__("MDAnalysis").__version__ +# The short X.Y version. +# version = '.'.join(packageversion.split('.')[:2]) +version = packageversion # needed for right sitemap.xml URLs +# The full version, including alpha/beta/rc tags. +release = packageversion + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["_build"] + +# The reST default role (used for this markup: `text`) to use for all documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "default" + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# to include decorated objects like __init__ +autoclass_content = "both" + +# to prevent including of member entries in toctree +toc_object_entries = False + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "mdanalysis_sphinx_theme" + +extra_nav_links = {} +extra_nav_links["MDAnalysis"] = "https://mdanalysis.org" +extra_nav_links["User guide"] = "https://userguide.mdanalysis.org" +extra_nav_links["MDAKits"] = "https://mdakits.mdanalysis.org/" + + +html_theme_options = { + "mda_official": True, + "extra_nav_links": extra_nav_links, +} + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_context = { + "versions_json_url": "https://docs.mdanalysis.org/versions.json" +} + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# For RTD theme: custom.css to override theme defaults. +html_static_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# alabaster sidebars +html_sidebars = { + "**": [ + "about.html", + "navigation.html", + "relations.html", + "searchbox.html", + ] +} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +html_use_opensearch = "https://docs.mdanalysis.org" + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = "MDAnalysisdoc" + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +# latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +# latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ("MDAnalysis.tex", "MDAnalysis Documentation", authors, "manual"), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +# latex_preamble = '' + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [("mdanalysis", "MDAnalysis Documentation", [authors], 1)] + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = "MDAnalysis" +epub_author = authors +epub_publisher = "Arizona State University, Tempe, Arizona, USA" +epub_copyright = "2015, " + authors + +# The language of the text. It defaults to the language option +# or en if the language is not set. +# epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +# epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# epub_identifier = '' + +# A unique identification for the text. +# epub_uid = '' + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# epub_post_files = [] + +# A list of files that should not be packed into the epub file. +# epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +# epub_tocdepth = 3 + +# Allow duplicate toc entries. +# epub_tocdup = True + + +# Configuration for intersphinx: refer to the Python standard library +# and other packages used by MDAnalysis +intersphinx_mapping = { + "h5py": ("https://docs.h5py.org/en/stable", None), + "python": ("https://docs.python.org/3/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/", None), + "gsd": ("https://gsd.readthedocs.io/en/stable/", None), + "maplotlib": ("https://matplotlib.org/stable/", None), + "griddataformats": ("https://mdanalysis.org/GridDataFormats/", None), + "pmda": ("https://mdanalysis.org/pmda/", None), + "networkx": ("https://networkx.org/documentation/stable/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "parmed": ("https://parmed.github.io/ParmEd/html/", None), + "rdkit": ("https://rdkit.org/docs/", None), + "waterdynamics": ("https://www.mdanalysis.org/waterdynamics/", None), + "pathsimanalysis": ("https://www.mdanalysis.org/PathSimAnalysis/", None), + "mdahole2": ("https://www.mdanalysis.org/mdahole2/", None), + "dask": ("https://docs.dask.org/en/stable/", None), + "imdclient": ("https://imdclient.readthedocs.io/en/stable/", None), + "pooch": ("https://www.fatiando.org/pooch/latest/", None), + "requests": ("https://requests.readthedocs.io/en/latest/", None), +} diff --git a/package/doc/sphinx/source/documentation_pages/analysis/align.rst b/package/doc/sphinx/source/documentation_pages/analysis/align.rst index 513985d7921..1f7528269a4 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/align.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/align.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.align - +.. automodule:: MDAnalysis.analysis.align + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/atomicdistances.rst b/package/doc/sphinx/source/documentation_pages/analysis/atomicdistances.rst index 42c884e7932..c565cc9f663 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/atomicdistances.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/atomicdistances.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.atomicdistances - :members: +.. automodule:: MDAnalysis.analysis.atomicdistances + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/backends.rst b/package/doc/sphinx/source/documentation_pages/analysis/backends.rst index 36f2a40cf11..2575bfe77b6 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/backends.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/backends.rst @@ -1,4 +1,4 @@ -.. automodule:: MDAnalysis.analysis.backends - :members: - :private-members: - +.. automodule:: MDAnalysis.analysis.backends + :members: + :private-members: + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/base.rst b/package/doc/sphinx/source/documentation_pages/analysis/base.rst index 2c2d884fc71..1eaf5a715ec 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/base.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/base.rst @@ -1,4 +1,4 @@ -.. automodule:: MDAnalysis.analysis.base - :members: - :private-members: - +.. automodule:: MDAnalysis.analysis.base + :members: + :private-members: + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/bat.rst b/package/doc/sphinx/source/documentation_pages/analysis/bat.rst index 9c0f799c759..a02795a5f77 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/bat.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/bat.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.bat +.. automodule:: MDAnalysis.analysis.bat diff --git a/package/doc/sphinx/source/documentation_pages/analysis/contacts.rst b/package/doc/sphinx/source/documentation_pages/analysis/contacts.rst index 9cf301ffb83..2572e6ac5d6 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/contacts.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/contacts.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.contacts - +.. automodule:: MDAnalysis.analysis.contacts + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/data.rst b/package/doc/sphinx/source/documentation_pages/analysis/data.rst index 63008abaf34..8c8b87d3a71 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/data.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/data.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.data.filenames - :members: +.. automodule:: MDAnalysis.analysis.data.filenames + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/density.rst b/package/doc/sphinx/source/documentation_pages/analysis/density.rst index 40cb906b201..91ef19c5a12 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/density.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/density.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.density - +.. automodule:: MDAnalysis.analysis.density + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/dielectric.rst b/package/doc/sphinx/source/documentation_pages/analysis/dielectric.rst index 215727b583e..dfacc31dd4b 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/dielectric.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/dielectric.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.analysis.dielectric - :members: - +.. automodule:: MDAnalysis.analysis.dielectric + :members: + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/diffusionmap.rst b/package/doc/sphinx/source/documentation_pages/analysis/diffusionmap.rst index 1eefec1e079..485ef4dfbfd 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/diffusionmap.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/diffusionmap.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.diffusionmap +.. automodule:: MDAnalysis.analysis.diffusionmap diff --git a/package/doc/sphinx/source/documentation_pages/analysis/dihedrals.rst b/package/doc/sphinx/source/documentation_pages/analysis/dihedrals.rst index eeb1a2ec4b8..3f06dc3fb7e 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/dihedrals.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/dihedrals.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.dihedrals +.. automodule:: MDAnalysis.analysis.dihedrals diff --git a/package/doc/sphinx/source/documentation_pages/analysis/distances.rst b/package/doc/sphinx/source/documentation_pages/analysis/distances.rst index ef143694949..8f5995d40ed 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/distances.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/distances.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.distances - :members: +.. automodule:: MDAnalysis.analysis.distances + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore.rst index ee165ae7559..4e5d2413efa 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore.rst @@ -1,64 +1,64 @@ -=============================================================================== - ENCORE Ensemble Similarity Calculations --- :mod:`MDAnalysis.analysis.encore` -=============================================================================== - -:Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen -:Year: 2015-2017 -:Copyright: Lesser GNU Public License v2.1+ -:Maintainer: Matteo Tiberti , mtiberti on github - -.. versionadded:: 0.16.0 - - -.. deprecated:: 2.8.0 - This module is deprecated in favour of the - MDAKit `mdaencore `_ and will be removed - in MDAnalysis 3.0.0. - -The module contains implementations of similarity measures between protein -ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and examples -are described in :footcite:p:`Tiberti2015`. - -The module includes facilities for handling ensembles and trajectories through -the :class:`Universe` class, performing clustering or dimensionality reduction -of the ensemble space, estimating multivariate probability distributions from -the input data, and more. ENCORE can be used to compare experimental and -simulation-derived ensembles, as well as estimate the convergence of -trajectories from time-dependent simulations. - -ENCORE includes three different methods for calculations of similarity measures -between ensembles implemented in individual functions: - - -+ **Harmonic Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.hes` -+ **Clustering Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.ces` -+ **Dimensional Reduction Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.dres` - -as well as two methods to evaluate the convergence of trajectories: - -+ **Clustering based convergence evaluation** : :func:`~MDAnalysis.analysis.encore.similarity.ces_convergence` -+ **Dimensionality-reduction based convergence evaluation** : :func:`~MDAnalysis.analysis.encore.similarity.dres_convergence` - - -When using this module in published work please cite :footcite:p:`Tiberti2015`. - - -Modules -------- - -.. toctree:: - :maxdepth: 1 - - ./encore/similarity - ./encore/clustering - ./encore/dimensionality_reduction - ./encore/confdistmatrix - ./encore/covariance - ./encore/bootstrap - ./encore/utils - - -References ----------- - -.. footbibliography:: +=============================================================================== + ENCORE Ensemble Similarity Calculations --- :mod:`MDAnalysis.analysis.encore` +=============================================================================== + +:Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen +:Year: 2015-2017 +:Copyright: Lesser GNU Public License v2.1+ +:Maintainer: Matteo Tiberti , mtiberti on github + +.. versionadded:: 0.16.0 + + +.. deprecated:: 2.8.0 + This module is deprecated in favour of the + MDAKit `mdaencore `_ and will be removed + in MDAnalysis 3.0.0. + +The module contains implementations of similarity measures between protein +ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and examples +are described in :footcite:p:`Tiberti2015`. + +The module includes facilities for handling ensembles and trajectories through +the :class:`Universe` class, performing clustering or dimensionality reduction +of the ensemble space, estimating multivariate probability distributions from +the input data, and more. ENCORE can be used to compare experimental and +simulation-derived ensembles, as well as estimate the convergence of +trajectories from time-dependent simulations. + +ENCORE includes three different methods for calculations of similarity measures +between ensembles implemented in individual functions: + + ++ **Harmonic Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.hes` ++ **Clustering Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.ces` ++ **Dimensional Reduction Ensemble Similarity** : :func:`~MDAnalysis.analysis.encore.similarity.dres` + +as well as two methods to evaluate the convergence of trajectories: + ++ **Clustering based convergence evaluation** : :func:`~MDAnalysis.analysis.encore.similarity.ces_convergence` ++ **Dimensionality-reduction based convergence evaluation** : :func:`~MDAnalysis.analysis.encore.similarity.dres_convergence` + + +When using this module in published work please cite :footcite:p:`Tiberti2015`. + + +Modules +------- + +.. toctree:: + :maxdepth: 1 + + ./encore/similarity + ./encore/clustering + ./encore/dimensionality_reduction + ./encore/confdistmatrix + ./encore/covariance + ./encore/bootstrap + ./encore/utils + + +References +---------- + +.. footbibliography:: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/bootstrap.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/bootstrap.rst index 5c844a1112f..27426a865ca 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/bootstrap.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/bootstrap.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.encore.bootstrap - :members: +.. automodule:: MDAnalysis.analysis.encore.bootstrap + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/clustering.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/clustering.rst index 0b0ca7ea642..9ff83e2c595 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/clustering.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/clustering.rst @@ -1,24 +1,24 @@ -============ - Clustering -============ - -.. automodule:: MDAnalysis.analysis.encore.clustering.cluster - :members: - -.. automodule:: MDAnalysis.analysis.encore.clustering.ClusterCollection - :members: - -.. automodule:: MDAnalysis.analysis.encore.clustering.ClusteringMethod - :members: - - -Clustering algorithms -===================== - -The following clustering algorithms are always available: - -.. automodule:: MDAnalysis.analysis.encore.clustering.affinityprop - :members: - - - +============ + Clustering +============ + +.. automodule:: MDAnalysis.analysis.encore.clustering.cluster + :members: + +.. automodule:: MDAnalysis.analysis.encore.clustering.ClusterCollection + :members: + +.. automodule:: MDAnalysis.analysis.encore.clustering.ClusteringMethod + :members: + + +Clustering algorithms +===================== + +The following clustering algorithms are always available: + +.. automodule:: MDAnalysis.analysis.encore.clustering.affinityprop + :members: + + + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/confdistmatrix.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/confdistmatrix.rst index 0f3e232d953..7663cada91d 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/confdistmatrix.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/confdistmatrix.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.encore.confdistmatrix - :members: +.. automodule:: MDAnalysis.analysis.encore.confdistmatrix + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/covariance.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/covariance.rst index 8f7fd5a6c87..90aa8bdc0ab 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/covariance.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/covariance.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.encore.covariance - :members: +.. automodule:: MDAnalysis.analysis.encore.covariance + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/dimensionality_reduction.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/dimensionality_reduction.rst index 7d326824218..a773c2c32d0 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/dimensionality_reduction.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/dimensionality_reduction.rst @@ -1,18 +1,18 @@ -========================== - Dimensionality reduction -========================== - -.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality - :members: - -.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.DimensionalityReductionMethod - :members: - -Dimensionality reduction algorithms -=================================== - -The following dimensionality reduction algorithms are always natively -available: - -.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.stochasticproxembed - :members: +========================== + Dimensionality reduction +========================== + +.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality + :members: + +.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.DimensionalityReductionMethod + :members: + +Dimensionality reduction algorithms +=================================== + +The following dimensionality reduction algorithms are always natively +available: + +.. automodule:: MDAnalysis.analysis.encore.dimensionality_reduction.stochasticproxembed + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/similarity.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/similarity.rst index 6d550d22d2f..e4814005331 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/similarity.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/similarity.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.encore.similarity - :members: +.. automodule:: MDAnalysis.analysis.encore.similarity + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/encore/utils.rst b/package/doc/sphinx/source/documentation_pages/analysis/encore/utils.rst index e1b1e27b717..fc24f50e94a 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/encore/utils.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/encore/utils.rst @@ -1,13 +1,13 @@ -============================== - Utility functions for ENCORE -============================== - -.. deprecated:: 2.8.0 - This module is deprecated in favour of the - MDAKit `mdaencore `_ and will be removed - in MDAnalysis 3.0.0. - -.. automodule:: MDAnalysis.analysis.encore.utils - :members: - -.. autofunction:: MDAnalysis.analysis.encore.cutils.PureRMSD +============================== + Utility functions for ENCORE +============================== + +.. deprecated:: 2.8.0 + This module is deprecated in favour of the + MDAKit `mdaencore `_ and will be removed + in MDAnalysis 3.0.0. + +.. automodule:: MDAnalysis.analysis.encore.utils + :members: + +.. autofunction:: MDAnalysis.analysis.encore.cutils.PureRMSD diff --git a/package/doc/sphinx/source/documentation_pages/analysis/gnm.rst b/package/doc/sphinx/source/documentation_pages/analysis/gnm.rst index 8f28ec66c55..bb554e76935 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/gnm.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/gnm.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.gnm +.. automodule:: MDAnalysis.analysis.gnm diff --git a/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel.rst b/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel.rst index 79b79c7e364..06b63be1330 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.hydrogenbonds.hbond_autocorrel +.. automodule:: MDAnalysis.analysis.hydrogenbonds.hbond_autocorrel diff --git a/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel_deprecated.rst b/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel_deprecated.rst index bf960e41bf4..75c14b1d4c8 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel_deprecated.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/hbond_autocorrel_deprecated.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.hbonds.hbond_autocorrel +.. automodule:: MDAnalysis.analysis.hbonds.hbond_autocorrel diff --git a/package/doc/sphinx/source/documentation_pages/analysis/helix_analysis.rst b/package/doc/sphinx/source/documentation_pages/analysis/helix_analysis.rst index 864e786ae1e..05784daaceb 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/helix_analysis.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/helix_analysis.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.helix_analysis - +.. automodule:: MDAnalysis.analysis.helix_analysis + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/hole2.rst b/package/doc/sphinx/source/documentation_pages/analysis/hole2.rst index 6c49fdfff61..1f364e126d2 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/hole2.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/hole2.rst @@ -1,50 +1,50 @@ -=================================================== - HOLE analysis --- :mod:`MDAnalysis.analysis.hole2` -=================================================== - -:Author: Lily Wang -:Year: 2020 -:Copyright: Lesser GNU Public License v2.1+ - -.. versionadded:: 1.0.0 - -This module provides an updated interface for the HOLE_ suite of tools -:footcite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter -pathway :footcite:p:`Stelzl2014` as a function of time or arbitrary order -parameters. It replaces :mod:`MDAnalysis.analysis.hole`. - -HOLE_ must be installed separately and can be obtained in binary form -from http://www.holeprogram.org/ or as source from -https://github.com/osmart/hole2. (HOLE is open source and available -under the Apache v2.0 license.) - - -.. deprecated:: 2.8.0 - This module is deprecated in favour of the mdakit - `mdahole2 `_ and - will be removed in MDAnalysis 3.0.0. - -.. _HOLE: http://www.holeprogram.org/ - - -See Also --------- -:mod:`mdahole2.analysis.hole` - - -Module ------- - -.. automodule:: MDAnalysis.analysis.hole2 - - - -Utility functions and templates -------------------------------- - -.. automodule:: MDAnalysis.analysis.hole2.utils - :members: - - -.. automodule:: MDAnalysis.analysis.hole2.templates - :members: +=================================================== + HOLE analysis --- :mod:`MDAnalysis.analysis.hole2` +=================================================== + +:Author: Lily Wang +:Year: 2020 +:Copyright: Lesser GNU Public License v2.1+ + +.. versionadded:: 1.0.0 + +This module provides an updated interface for the HOLE_ suite of tools +:footcite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter +pathway :footcite:p:`Stelzl2014` as a function of time or arbitrary order +parameters. It replaces :mod:`MDAnalysis.analysis.hole`. + +HOLE_ must be installed separately and can be obtained in binary form +from http://www.holeprogram.org/ or as source from +https://github.com/osmart/hole2. (HOLE is open source and available +under the Apache v2.0 license.) + + +.. deprecated:: 2.8.0 + This module is deprecated in favour of the mdakit + `mdahole2 `_ and + will be removed in MDAnalysis 3.0.0. + +.. _HOLE: http://www.holeprogram.org/ + + +See Also +-------- +:mod:`mdahole2.analysis.hole` + + +Module +------ + +.. automodule:: MDAnalysis.analysis.hole2 + + + +Utility functions and templates +------------------------------- + +.. automodule:: MDAnalysis.analysis.hole2.utils + :members: + + +.. automodule:: MDAnalysis.analysis.hole2.templates + :members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/hydrogenbonds.rst b/package/doc/sphinx/source/documentation_pages/analysis/hydrogenbonds.rst index e67253d13af..3fbbeb12092 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/hydrogenbonds.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/hydrogenbonds.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.hydrogenbonds.hbond_analysis +.. automodule:: MDAnalysis.analysis.hydrogenbonds.hbond_analysis diff --git a/package/doc/sphinx/source/documentation_pages/analysis/leaflet.rst b/package/doc/sphinx/source/documentation_pages/analysis/leaflet.rst index be64581bcb5..5daec2826c9 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/leaflet.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/leaflet.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.leaflet +.. automodule:: MDAnalysis.analysis.leaflet diff --git a/package/doc/sphinx/source/documentation_pages/analysis/legacy/x3dna.rst b/package/doc/sphinx/source/documentation_pages/analysis/legacy/x3dna.rst index 63a5668d27c..06935b57453 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/legacy/x3dna.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/legacy/x3dna.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.legacy.x3dna +.. automodule:: MDAnalysis.analysis.legacy.x3dna diff --git a/package/doc/sphinx/source/documentation_pages/analysis/legacy_modules.rst b/package/doc/sphinx/source/documentation_pages/analysis/legacy_modules.rst index c8ad08e0fde..df23eff081e 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/legacy_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/legacy_modules.rst @@ -1,35 +1,35 @@ -============================================================ - :mod:`MDAnalysis.analysis.legacy` --- Legacy analysis code -============================================================ - -.. versionadded:: 0.16.0 - -The :mod:`MDAnalysis.analysis.legacy` package contains analysis -modules that are not or only incompletely tested and not regularly -maintained. They nevertheless still provide useful and sometimes -unique analysis capabilities and are therefore provided **as -is**. (For further discussion, see `Issue 743`_.) - -.. warning:: - - Code in the :mod:`~MDAnalysis.analysis.legacy` package is not - regularly maintained. Please use it very carefully. - -If you want to use modules from this package then you will have to import -them explicitly. For example, :: - - from MDAnalysis.analysis.legacy import x3dna - - -.. _Issue 743: https://github.com/MDAnalysis/mdanalysis/issues/743 - - -Legacy modules -============== - -.. toctree:: - :maxdepth: 1 - - legacy/x3dna - - +============================================================ + :mod:`MDAnalysis.analysis.legacy` --- Legacy analysis code +============================================================ + +.. versionadded:: 0.16.0 + +The :mod:`MDAnalysis.analysis.legacy` package contains analysis +modules that are not or only incompletely tested and not regularly +maintained. They nevertheless still provide useful and sometimes +unique analysis capabilities and are therefore provided **as +is**. (For further discussion, see `Issue 743`_.) + +.. warning:: + + Code in the :mod:`~MDAnalysis.analysis.legacy` package is not + regularly maintained. Please use it very carefully. + +If you want to use modules from this package then you will have to import +them explicitly. For example, :: + + from MDAnalysis.analysis.legacy import x3dna + + +.. _Issue 743: https://github.com/MDAnalysis/mdanalysis/issues/743 + + +Legacy modules +============== + +.. toctree:: + :maxdepth: 1 + + legacy/x3dna + + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/lineardensity.rst b/package/doc/sphinx/source/documentation_pages/analysis/lineardensity.rst index 2e4b4de2e59..ed09aef3ee7 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/lineardensity.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/lineardensity.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.analysis.lineardensity - :members: - +.. automodule:: MDAnalysis.analysis.lineardensity + :members: + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/msd.rst b/package/doc/sphinx/source/documentation_pages/analysis/msd.rst index 4fcc341139b..5efbaf49006 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/msd.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/msd.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.msd +.. automodule:: MDAnalysis.analysis.msd diff --git a/package/doc/sphinx/source/documentation_pages/analysis/nuclinfo.rst b/package/doc/sphinx/source/documentation_pages/analysis/nuclinfo.rst index db0ede32083..7912e179338 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/nuclinfo.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/nuclinfo.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.nuclinfo - +.. automodule:: MDAnalysis.analysis.nuclinfo + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/parallelization.rst b/package/doc/sphinx/source/documentation_pages/analysis/parallelization.rst index 3070614b5a3..097537b29b7 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/parallelization.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/parallelization.rst @@ -1,363 +1,363 @@ -.. -*- coding: utf-8 -*- - -.. _parallel-analysis: - -================= -Parallel analysis -================= - -.. versionadded:: 2.8.0 - Parallelization of analysis classes was added during Google Summer of Code - 2023 by `@marinegor `_ and MDAnalysis GSoC mentors. - -This section explains the implementation and background for -parallelization with the :class:`MDAnalysis.analysis.base.AnalysisBase`, what -users and developers need to know, when you should use parallelization (almost -always!), and when you should abstain from doing so (rarely). - - -How to use parallelization -========================== - -In order to use parallelization in a built-in analysis class ``SomeAnalysisClass``, -simply check which backends are available (see :ref:`backends` for backends -that are generally available), and then just enable them by providing -``backend='multiprocessing'`` and ``n_workers=...`` to ``SomeClass.run(...)`` -method: - -.. code-block:: python - - u = mda.Universe(...) - my_run = SomeClass(trajectory) - assert SomeClass.get_supported_backends() == ('serial', 'multiprocessing', 'dask') - - my_run.run(backend='multiprocessing', n_workers=12) - -For some classes, such as :class:`MDAnalysis.analysis.rms.RMSF` (in its current implementation), -split-apply-combine parallelization isn't possible, and running them will be -impossible with any but the ``serial`` backend. - -.. Note:: - - Parallelization is getting added to existing analysis classes. Initially, - only :class:`MDAnalysis.analysis.rms.RMSD` supports parallel analysis, but - we aim to increase support in future releases. Please check issues labeled - `parallelization` on the `MDAnalysis issues tracker `_. - - -How does parallelization work -============================= - -The main idea behind its current implementation is that a trajectory analysis is -often trivially parallelizable, meaning you can analyze all frames -independently, and then merge them in a single object. This approach is also -known as "split-apply-combine", and isn't new to MDAnalysis users, since it was -first introduced in `PMDA`_ :footcite:p:`Fan2019`. -Version 2.8.0 of MDAnalysis brings this approach to the main library. - -.. _`PMDA`: https://github.com/mdanalysis/pmda - - -split-apply-combine -------------------- - -The following scheme explains the current :meth:`AnalysisBase.run -` protocol (user-implemented methods -are highlighted in orange): - -.. figure:: /images/AnalysisBase_parallel.png - - -In short, after checking input parameters and configuring the backend, -:class:`AnalysisBase <` splits all the -frames into *computation groups* (equally sized sequential groups of frames to -be processed by each worker). All groups then get **split** between workers of -a backend configured early, the main instance gets serialized and distributed -between workers, and then -:meth:`~MDAnalysis.analysis.base.AnalysisBase._compute()` method gets called -for all frames of a computation group. Within this method, a user-implemented -:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` method gets -**applied** to each frame in a computation group. After that, the main -instance gets an object that will **combine** all the objects from other -workers, and all instances get *merged* with an instance of -:class:`MDAnalysis.analysis.results.ResultsGroup`. Then, a normal -user-implemented :meth:`~MDAnalysis.analysis.base.AnalysisBase._compute` method -is called. - -Parallelization is fully compatible with existing code and does *not* break -any existing code pre-2.8.0. The parallelization protocol mimics the -single-process workflow where possible. Thus, user-implemented methods such as -:meth:`~MDAnalysis.analysis.base.AnalysisBase._prepare`, -:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` and -:meth:`~MDAnalysis.analysis.base.AnalysisBase._conclude` won't need to know -they are operating on an instance within the main python process, or on a -remote instance, since the executed code is the same in both cases. - - -Methods in ``AnalysisBase`` for parallelization ------------------------------------------------ - -For developers of new analysis tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to write your own *parallel* analysis class, you have to implement -:meth:`~MDAnalysis.analysis.base.AnalysisBase._prepare`, -:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` and -:meth:`~MDAnalysis.analysis.base.AnalysisBase._conclude`. You also have to -denote if your analysis can run in parallel by following the steps under -:ref:`adding-parallelization`. - -.. Note:: - - Attributes that are the same for the whole trajectory, should be defined - in `__init__` method because they need to be consistent across all workers. - -For MDAnalysis developers -~~~~~~~~~~~~~~~~~~~~~~~~~ - -From a developer point of view, there are a few methods that are important in -order to understand how parallelization is implemented: - -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._define_run_frames` -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._prepare_sliced_trajectory` -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._configure_backend` -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._setup_computation_groups` -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._compute` -#. :meth:`MDAnalysis.analysis.base.AnalysisBase._get_aggregator` - -The first two methods share the functionality of :meth:`_setup_frames`. -:meth:`_define_run_frames` is run once during analysis, as it checks that input -parameters `start`, `stop`, `step` or `frames` are consistent with the given -trajectory and prepares the ``slicer`` object that defines the iteration -pattern through the trajectory. :meth:`_prepare_sliced_trajectory` assigns to -the :attr:`self._sliced_trajectory` attribute, computes the number of frames in -it, and fills the :attr:`self.frames` and :attr:`self.times` arrays. In case -the computation will be later split between other processes, this method will -be called again on each of the computation groups. - -The method :meth:`_configure_backend` performs basic health checks for a given -analysis class -- namely, it compares a given backend (if it's a :class:`str` -instance, such as ``'multiprocessing'``) with the list of builtin backends (and -also the backends implemented for a given analysis subclass), and configures a -:class:`MDAnalysis.analysis.backends.BackendBase` instance accordingly. If the -user decides to provide a custom backend (any subclass of -:class:`MDAnalysis.analysis.backends.BackendBase`, or anything with an -:meth:`apply` method), it ensures that the number of workers wasn't specified -twice (during backend initialization and in :meth:`run` arguments). - -After a backend is configured, :meth:`_setup_computation_groups` splits the -frames prepared earlier in :attr:`self._prepare_sliced_trajectory` into a -number of groups, by default equal to the number of workers. - -In the :meth:`_compute` method, frames get initialized again with -:meth:`_prepare_sliced_trajectory`, and attributes necessary for a specific -analysis get initialized with the :meth:`_prepare` method. Then the function -iterates over :attr:`self._sliced_trajectory`, assigning -:attr:`self._frame_index` and :attr:`self._ts` as frame index (within a -computation group) and timestamp, and also setting respective -:attr:`self.frames` and :attr:`self.times` array values. - -After :meth:`_compute` has finished, the main analysis instance calls the -:meth:`_get_aggregator` method, which merges the :attr:`self.results` -attributes from other processes into a single -:class:`MDAnalysis.analysis.results.Results` instance, making it look for the -subsequent :meth:`_conclude` method as if the run was performed in a serial -fashion, without parallelization. - - -Helper classes for parallelization -================================== - -``ResultsGroup`` ----------------- - -:class:`MDAnalysis.analysis.results.ResultsGroup` extends the functionality of -the :class:`MDAnalysis.analysis.results.Results` class. Since the ``Results`` -class is basically a dictionary that also keeps track of assigned attributes, it -is possible to iterate over all these attributes later. ``ResultsGroup`` does -exactly that: given a list of the ``Results`` objects with the same attributes, -it applies a specific aggregation function to every attribute, and stores it as -a same attribute of the returned object: - -.. code-block:: python - - from MDAnalysis.analysis.results import ResultsGroup, Results - group = ResultsGroup(lookup={'mass': ResultsGroup.float_mean}) - obj1 = Results(mass=1) - obj2 = Results(mass=3) - assert group.merge([obj1, obj2]) == Results(mass=2.0) - - -``BackendBase`` ---------------- - -:class:`MDAnalysis.analysis.backends.BackendBase` holds all backend attributes, -and also implements an :meth:`MDAnalysis.analysis.backends.BackendBase.apply` -method, applying a given function to a list of its parameters, but in a parallel -fashion. Although in ``AnalysisBase`` it is used to apply a ``_compute`` -function, in principle it can be used to any arbitrary function and arguments, -given they're serializable. - - -When to use parallelization? (Known limitations) -================================================ - -For now, the syntax for running parallel analysis is explicit, meaning by -default the ``serial`` version will be run, and the parallelization won't be -enabled by default. Although we expect the parallelization to be useful in most -cases, there are some known caveats from the inital benchmarks. - -Fast ``_single_frame`` compared to reading from disk ----------------------------------------------------- - -In all cases, parallelization will not be useful only when frames are being -processed faster than being read from the disk, otherwise reading is the -bottleneck here. Hence, you'll benefit from parallelization only if you have -relatively much compute per frame, or a fast drive, as illustrated below: - -.. figure:: /images/parallelization_time.png - -In other words, if you have *fast* analysis (say, -:class:`MDAnalysis.analysis.rms.RMSD`) **and** a slow HDD drive, you are likely -to not get any benefits from parallelization. Otherwise, you should be fine. - -Serialization issues --------------------- - -For built-in analysis classes, the default serialization with both -:mod:`multiprocessing` and :mod:`dask` is known to work. If you're using some custom -analysis class that e.g. stores a non-serializable object in one of its -attributes, you might get a serialization error (:exc:`PicklingError` if you're -using a ``multiprocessing`` backend). If you want to get around that, we suggest -trying ``backend='dask'`` (it uses ``dask`` serialization engine instead of -:mod:`pickle`). - -Out of memory issues --------------------- - -If you have large memory footprint of each worker, you can run into -out-of-memory errors (i.e. your server freezes when executing a run). In this -case we suggest decreasing the number of workers from all available CPUs (that -you can get with :func:`multiprocessing.cpu_count`) to a smaller number. - -Progress bar is missing ------------------------ - -It is yet not possible to get a progress bar running with any parallel backend. -If you want an ETA of your analysis, we suggest running it in ``serial`` mode -for the first 10-100 frames with ``verbose=True``, and then running it with -multiple workers. Processing time scales almost linearly, so you can get your -ETA by dividing ``serial`` ETA by the number of workers. - - -.. _adding-parallelization: - -Adding parallelization to your own analysis class -================================================= - -If you want to add parallelization to your own analysis class, first make sure -your algorithm allows you to do that, i.e. you can process each frame independently. -Then it's rather simple -- let's look at the actual code that added -parallelization to the :class:`MDAnalysis.analysis.rms.RMSD`: - -.. code-block:: python - - from MDAnalysis.analysis.base import AnalysisBase - from MDAnalysis.analysis.results import ResultsGroup - - class RMSD(BackendBase): - @classmethod - def get_supported_backends(cls): - return ('serial', 'multiprocessing', 'dask',) - - _analysis_algorithm_is_parallelizable = True - - def _get_aggregator(self): - return ResultsGroup(lookup={'rmsd': ResultsGroup.ndarray_vstack}) - - -That's it! The first two methods are boilerplate -- -:meth:`get_supported_backends` returns a tuple with built-in backends that will -work for your class (if there are no serialization issues, it should be all -three), and ``_is_parallelizable`` is ``True`` (which is set to ``False`` in -``AnalysisBase``, hence we have to re-define it), and :meth:`_get_aggregator` -will be used as described earlier. Note that :mod:`MDAnalysis.analysis.results` -also provides a few convenient functions (defined as class methods of -:class:`~MDAnalysis.analysis.results.ResultsGroup`) for results aggregation: - -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.flatten_sequence` -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_sum` -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_mean` -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.float_mean` -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_hstack` -#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_vstack` - - -So you'll likely find appropriate functions for basic aggregation there. - -Writing custom backends -======================= - -In order to write your custom backend (e.g. using :mod:`dask.distributed`), inherit -from the :class:`MDAnalysis.analysis.backends.BackendBase` and (re)-implement -:meth:`__init__` and :meth:`apply` methods. Optionally, you can implement methods for -validation of correct backend initialization -- :meth:`_get_checks` and -:meth:`_get_warnings`, that would raise an exception or give a warning, respectively, -when a new class instance is created: - -#. :meth:`MDAnalysis.analysis.backends._get_checks` -#. :meth:`MDAnalysis.analysis.backends._get_warnings` - -.. code-block:: python - - from MDAnalysis.analysis.backends import BackendBase - class ThreadsBackend(BackendBase): - def __init__(self, n_workers: int, starting_message: str = "Useless backend"): - self.n_workers = n_workers - self.starting_message = starting_message - self._validate() - - def _get_warnings(self): - return {True: 'warning: this backend is useless'} - - def _get_checks(self): - return {isinstance(self.n_workers, int), 'error: self.n_workers is not an integer'} - - def apply(self, func, computations): - from multiprocessing.dummy import Pool - - with Pool(processes=self.n_workers) as pool: - print(self.starting_message) - results = pool.map(func, computations) - return results - - -In order to use a custom backend with another analysis class that does not -explicitly support it, you must *explicitly state* that you're about to use an -unsupported_backend by passing the keyword argument -``unsupported_backend=True``: - -.. code-block:: python - - from MDAnalysis.analysis.rms import RMSD - R = RMSD(...) # setup the run - n_workers = 2 - backend = ThreadsBackend(n_workers=n_workers) - R.run(backend=backend, unsupported_backend=True) - -In this way, you will override the check for supported backends. - -.. Warning:: - - When you use ``unsupported_backend=True`` you should make sure that you get - the same results as when using a supported backend for which the analysis - class was tested. - - Before reporting a problem with an analysis class, make sure you tested it - with a supported backend. When reporting *always mention if you used* - ``unsupported_backend=True``. - - -.. rubric:: References -.. footbibliography:: - +.. -*- coding: utf-8 -*- + +.. _parallel-analysis: + +================= +Parallel analysis +================= + +.. versionadded:: 2.8.0 + Parallelization of analysis classes was added during Google Summer of Code + 2023 by `@marinegor `_ and MDAnalysis GSoC mentors. + +This section explains the implementation and background for +parallelization with the :class:`MDAnalysis.analysis.base.AnalysisBase`, what +users and developers need to know, when you should use parallelization (almost +always!), and when you should abstain from doing so (rarely). + + +How to use parallelization +========================== + +In order to use parallelization in a built-in analysis class ``SomeAnalysisClass``, +simply check which backends are available (see :ref:`backends` for backends +that are generally available), and then just enable them by providing +``backend='multiprocessing'`` and ``n_workers=...`` to ``SomeClass.run(...)`` +method: + +.. code-block:: python + + u = mda.Universe(...) + my_run = SomeClass(trajectory) + assert SomeClass.get_supported_backends() == ('serial', 'multiprocessing', 'dask') + + my_run.run(backend='multiprocessing', n_workers=12) + +For some classes, such as :class:`MDAnalysis.analysis.rms.RMSF` (in its current implementation), +split-apply-combine parallelization isn't possible, and running them will be +impossible with any but the ``serial`` backend. + +.. Note:: + + Parallelization is getting added to existing analysis classes. Initially, + only :class:`MDAnalysis.analysis.rms.RMSD` supports parallel analysis, but + we aim to increase support in future releases. Please check issues labeled + `parallelization` on the `MDAnalysis issues tracker `_. + + +How does parallelization work +============================= + +The main idea behind its current implementation is that a trajectory analysis is +often trivially parallelizable, meaning you can analyze all frames +independently, and then merge them in a single object. This approach is also +known as "split-apply-combine", and isn't new to MDAnalysis users, since it was +first introduced in `PMDA`_ :footcite:p:`Fan2019`. +Version 2.8.0 of MDAnalysis brings this approach to the main library. + +.. _`PMDA`: https://github.com/mdanalysis/pmda + + +split-apply-combine +------------------- + +The following scheme explains the current :meth:`AnalysisBase.run +` protocol (user-implemented methods +are highlighted in orange): + +.. figure:: /images/AnalysisBase_parallel.png + + +In short, after checking input parameters and configuring the backend, +:class:`AnalysisBase <` splits all the +frames into *computation groups* (equally sized sequential groups of frames to +be processed by each worker). All groups then get **split** between workers of +a backend configured early, the main instance gets serialized and distributed +between workers, and then +:meth:`~MDAnalysis.analysis.base.AnalysisBase._compute()` method gets called +for all frames of a computation group. Within this method, a user-implemented +:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` method gets +**applied** to each frame in a computation group. After that, the main +instance gets an object that will **combine** all the objects from other +workers, and all instances get *merged* with an instance of +:class:`MDAnalysis.analysis.results.ResultsGroup`. Then, a normal +user-implemented :meth:`~MDAnalysis.analysis.base.AnalysisBase._compute` method +is called. + +Parallelization is fully compatible with existing code and does *not* break +any existing code pre-2.8.0. The parallelization protocol mimics the +single-process workflow where possible. Thus, user-implemented methods such as +:meth:`~MDAnalysis.analysis.base.AnalysisBase._prepare`, +:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` and +:meth:`~MDAnalysis.analysis.base.AnalysisBase._conclude` won't need to know +they are operating on an instance within the main python process, or on a +remote instance, since the executed code is the same in both cases. + + +Methods in ``AnalysisBase`` for parallelization +----------------------------------------------- + +For developers of new analysis tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to write your own *parallel* analysis class, you have to implement +:meth:`~MDAnalysis.analysis.base.AnalysisBase._prepare`, +:meth:`~MDAnalysis.analysis.base.AnalysisBase._single_frame` and +:meth:`~MDAnalysis.analysis.base.AnalysisBase._conclude`. You also have to +denote if your analysis can run in parallel by following the steps under +:ref:`adding-parallelization`. + +.. Note:: + + Attributes that are the same for the whole trajectory, should be defined + in `__init__` method because they need to be consistent across all workers. + +For MDAnalysis developers +~~~~~~~~~~~~~~~~~~~~~~~~~ + +From a developer point of view, there are a few methods that are important in +order to understand how parallelization is implemented: + +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._define_run_frames` +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._prepare_sliced_trajectory` +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._configure_backend` +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._setup_computation_groups` +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._compute` +#. :meth:`MDAnalysis.analysis.base.AnalysisBase._get_aggregator` + +The first two methods share the functionality of :meth:`_setup_frames`. +:meth:`_define_run_frames` is run once during analysis, as it checks that input +parameters `start`, `stop`, `step` or `frames` are consistent with the given +trajectory and prepares the ``slicer`` object that defines the iteration +pattern through the trajectory. :meth:`_prepare_sliced_trajectory` assigns to +the :attr:`self._sliced_trajectory` attribute, computes the number of frames in +it, and fills the :attr:`self.frames` and :attr:`self.times` arrays. In case +the computation will be later split between other processes, this method will +be called again on each of the computation groups. + +The method :meth:`_configure_backend` performs basic health checks for a given +analysis class -- namely, it compares a given backend (if it's a :class:`str` +instance, such as ``'multiprocessing'``) with the list of builtin backends (and +also the backends implemented for a given analysis subclass), and configures a +:class:`MDAnalysis.analysis.backends.BackendBase` instance accordingly. If the +user decides to provide a custom backend (any subclass of +:class:`MDAnalysis.analysis.backends.BackendBase`, or anything with an +:meth:`apply` method), it ensures that the number of workers wasn't specified +twice (during backend initialization and in :meth:`run` arguments). + +After a backend is configured, :meth:`_setup_computation_groups` splits the +frames prepared earlier in :attr:`self._prepare_sliced_trajectory` into a +number of groups, by default equal to the number of workers. + +In the :meth:`_compute` method, frames get initialized again with +:meth:`_prepare_sliced_trajectory`, and attributes necessary for a specific +analysis get initialized with the :meth:`_prepare` method. Then the function +iterates over :attr:`self._sliced_trajectory`, assigning +:attr:`self._frame_index` and :attr:`self._ts` as frame index (within a +computation group) and timestamp, and also setting respective +:attr:`self.frames` and :attr:`self.times` array values. + +After :meth:`_compute` has finished, the main analysis instance calls the +:meth:`_get_aggregator` method, which merges the :attr:`self.results` +attributes from other processes into a single +:class:`MDAnalysis.analysis.results.Results` instance, making it look for the +subsequent :meth:`_conclude` method as if the run was performed in a serial +fashion, without parallelization. + + +Helper classes for parallelization +================================== + +``ResultsGroup`` +---------------- + +:class:`MDAnalysis.analysis.results.ResultsGroup` extends the functionality of +the :class:`MDAnalysis.analysis.results.Results` class. Since the ``Results`` +class is basically a dictionary that also keeps track of assigned attributes, it +is possible to iterate over all these attributes later. ``ResultsGroup`` does +exactly that: given a list of the ``Results`` objects with the same attributes, +it applies a specific aggregation function to every attribute, and stores it as +a same attribute of the returned object: + +.. code-block:: python + + from MDAnalysis.analysis.results import ResultsGroup, Results + group = ResultsGroup(lookup={'mass': ResultsGroup.float_mean}) + obj1 = Results(mass=1) + obj2 = Results(mass=3) + assert group.merge([obj1, obj2]) == Results(mass=2.0) + + +``BackendBase`` +--------------- + +:class:`MDAnalysis.analysis.backends.BackendBase` holds all backend attributes, +and also implements an :meth:`MDAnalysis.analysis.backends.BackendBase.apply` +method, applying a given function to a list of its parameters, but in a parallel +fashion. Although in ``AnalysisBase`` it is used to apply a ``_compute`` +function, in principle it can be used to any arbitrary function and arguments, +given they're serializable. + + +When to use parallelization? (Known limitations) +================================================ + +For now, the syntax for running parallel analysis is explicit, meaning by +default the ``serial`` version will be run, and the parallelization won't be +enabled by default. Although we expect the parallelization to be useful in most +cases, there are some known caveats from the inital benchmarks. + +Fast ``_single_frame`` compared to reading from disk +---------------------------------------------------- + +In all cases, parallelization will not be useful only when frames are being +processed faster than being read from the disk, otherwise reading is the +bottleneck here. Hence, you'll benefit from parallelization only if you have +relatively much compute per frame, or a fast drive, as illustrated below: + +.. figure:: /images/parallelization_time.png + +In other words, if you have *fast* analysis (say, +:class:`MDAnalysis.analysis.rms.RMSD`) **and** a slow HDD drive, you are likely +to not get any benefits from parallelization. Otherwise, you should be fine. + +Serialization issues +-------------------- + +For built-in analysis classes, the default serialization with both +:mod:`multiprocessing` and :mod:`dask` is known to work. If you're using some custom +analysis class that e.g. stores a non-serializable object in one of its +attributes, you might get a serialization error (:exc:`PicklingError` if you're +using a ``multiprocessing`` backend). If you want to get around that, we suggest +trying ``backend='dask'`` (it uses ``dask`` serialization engine instead of +:mod:`pickle`). + +Out of memory issues +-------------------- + +If you have large memory footprint of each worker, you can run into +out-of-memory errors (i.e. your server freezes when executing a run). In this +case we suggest decreasing the number of workers from all available CPUs (that +you can get with :func:`multiprocessing.cpu_count`) to a smaller number. + +Progress bar is missing +----------------------- + +It is yet not possible to get a progress bar running with any parallel backend. +If you want an ETA of your analysis, we suggest running it in ``serial`` mode +for the first 10-100 frames with ``verbose=True``, and then running it with +multiple workers. Processing time scales almost linearly, so you can get your +ETA by dividing ``serial`` ETA by the number of workers. + + +.. _adding-parallelization: + +Adding parallelization to your own analysis class +================================================= + +If you want to add parallelization to your own analysis class, first make sure +your algorithm allows you to do that, i.e. you can process each frame independently. +Then it's rather simple -- let's look at the actual code that added +parallelization to the :class:`MDAnalysis.analysis.rms.RMSD`: + +.. code-block:: python + + from MDAnalysis.analysis.base import AnalysisBase + from MDAnalysis.analysis.results import ResultsGroup + + class RMSD(BackendBase): + @classmethod + def get_supported_backends(cls): + return ('serial', 'multiprocessing', 'dask',) + + _analysis_algorithm_is_parallelizable = True + + def _get_aggregator(self): + return ResultsGroup(lookup={'rmsd': ResultsGroup.ndarray_vstack}) + + +That's it! The first two methods are boilerplate -- +:meth:`get_supported_backends` returns a tuple with built-in backends that will +work for your class (if there are no serialization issues, it should be all +three), and ``_is_parallelizable`` is ``True`` (which is set to ``False`` in +``AnalysisBase``, hence we have to re-define it), and :meth:`_get_aggregator` +will be used as described earlier. Note that :mod:`MDAnalysis.analysis.results` +also provides a few convenient functions (defined as class methods of +:class:`~MDAnalysis.analysis.results.ResultsGroup`) for results aggregation: + +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.flatten_sequence` +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_sum` +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_mean` +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.float_mean` +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_hstack` +#. :meth:`~MDAnalysis.analysis.results.ResultsGroup.ndarray_vstack` + + +So you'll likely find appropriate functions for basic aggregation there. + +Writing custom backends +======================= + +In order to write your custom backend (e.g. using :mod:`dask.distributed`), inherit +from the :class:`MDAnalysis.analysis.backends.BackendBase` and (re)-implement +:meth:`__init__` and :meth:`apply` methods. Optionally, you can implement methods for +validation of correct backend initialization -- :meth:`_get_checks` and +:meth:`_get_warnings`, that would raise an exception or give a warning, respectively, +when a new class instance is created: + +#. :meth:`MDAnalysis.analysis.backends._get_checks` +#. :meth:`MDAnalysis.analysis.backends._get_warnings` + +.. code-block:: python + + from MDAnalysis.analysis.backends import BackendBase + class ThreadsBackend(BackendBase): + def __init__(self, n_workers: int, starting_message: str = "Useless backend"): + self.n_workers = n_workers + self.starting_message = starting_message + self._validate() + + def _get_warnings(self): + return {True: 'warning: this backend is useless'} + + def _get_checks(self): + return {isinstance(self.n_workers, int), 'error: self.n_workers is not an integer'} + + def apply(self, func, computations): + from multiprocessing.dummy import Pool + + with Pool(processes=self.n_workers) as pool: + print(self.starting_message) + results = pool.map(func, computations) + return results + + +In order to use a custom backend with another analysis class that does not +explicitly support it, you must *explicitly state* that you're about to use an +unsupported_backend by passing the keyword argument +``unsupported_backend=True``: + +.. code-block:: python + + from MDAnalysis.analysis.rms import RMSD + R = RMSD(...) # setup the run + n_workers = 2 + backend = ThreadsBackend(n_workers=n_workers) + R.run(backend=backend, unsupported_backend=True) + +In this way, you will override the check for supported backends. + +.. Warning:: + + When you use ``unsupported_backend=True`` you should make sure that you get + the same results as when using a supported backend for which the analysis + class was tested. + + Before reporting a problem with an analysis class, make sure you tested it + with a supported backend. When reporting *always mention if you used* + ``unsupported_backend=True``. + + +.. rubric:: References +.. footbibliography:: + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/pca.rst b/package/doc/sphinx/source/documentation_pages/analysis/pca.rst index dc90112ad4b..a6ff776b179 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/pca.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/pca.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.pca +.. automodule:: MDAnalysis.analysis.pca diff --git a/package/doc/sphinx/source/documentation_pages/analysis/polymer.rst b/package/doc/sphinx/source/documentation_pages/analysis/polymer.rst index 6b7d9b81138..91de05ee276 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/polymer.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/polymer.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.analysis.polymer - :members: - :inherited-members: +.. automodule:: MDAnalysis.analysis.polymer + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/analysis/psa.rst b/package/doc/sphinx/source/documentation_pages/analysis/psa.rst index bdc747c3a6f..af25310f76b 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/psa.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/psa.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.psa - +.. automodule:: MDAnalysis.analysis.psa + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/rdf.rst b/package/doc/sphinx/source/documentation_pages/analysis/rdf.rst index a12bf803213..fe93baed4a0 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/rdf.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/rdf.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.rdf +.. automodule:: MDAnalysis.analysis.rdf :members: \ No newline at end of file diff --git a/package/doc/sphinx/source/documentation_pages/analysis/results.rst b/package/doc/sphinx/source/documentation_pages/analysis/results.rst index 22fc9fd81f3..0d461330e2a 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/results.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/results.rst @@ -1,4 +1,4 @@ -.. automodule:: MDAnalysis.analysis.results - :members: - - +.. automodule:: MDAnalysis.analysis.results + :members: + + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/rms.rst b/package/doc/sphinx/source/documentation_pages/analysis/rms.rst index 3e3124acd01..c7506ddfc41 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/rms.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/rms.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.rms - +.. automodule:: MDAnalysis.analysis.rms + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/waterdynamics.rst b/package/doc/sphinx/source/documentation_pages/analysis/waterdynamics.rst index 2db6600b282..1404e6c134f 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/waterdynamics.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/waterdynamics.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.analysis.waterdynamics - +.. automodule:: MDAnalysis.analysis.waterdynamics + diff --git a/package/doc/sphinx/source/documentation_pages/analysis/wbridge_analysis.rst b/package/doc/sphinx/source/documentation_pages/analysis/wbridge_analysis.rst index ea9ab08ee18..8ed068b93d1 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis/wbridge_analysis.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis/wbridge_analysis.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.analysis.hydrogenbonds.wbridge_analysis +.. automodule:: MDAnalysis.analysis.hydrogenbonds.wbridge_analysis diff --git a/package/doc/sphinx/source/documentation_pages/analysis_modules.rst b/package/doc/sphinx/source/documentation_pages/analysis_modules.rst index 01e1af833c2..743ba8d5106 100644 --- a/package/doc/sphinx/source/documentation_pages/analysis_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/analysis_modules.rst @@ -1,268 +1,268 @@ -.. Contains the formatted docstrings from the analysis modules located in 'mdanalysis/MDAnalysis/analysis', although in some cases the documentation imports functions and docstrings from other files which are also curated to reStructuredText markup. - -.. module:: MDAnalysis.analysis - -.. _analysis-label: - -**************** -Analysis modules -**************** - -The :mod:`MDAnalysis.analysis` module provides a wide collection of analysis tools for -molecular dynamics trajectories. These modules build upon MDAnalysis core functionality -(trajectory I/O, selections, etc.) and are designed both for reuse in research workflows -and as examples of using the MDAnalysis API. Each module typically defines an analysis -class that follows a standard interface. - -See the `User Guide Analysis section`_ for interactive examples and additional context. - -.. _User Guide Analysis section: https://userguide.mdanalysis.org/stable/examples/analysis/README.html - - -Getting started with analysis -============================= - -General usage pattern ---------------------- - -Most analysis tools are implemented as single classes and follow this usage pattern: - -#. Import the module (e.g., :mod:`MDAnalysis.analysis.rms`). -#. Initialize the analysis class with the required arguments. -#. Run the analysis with :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`. -#. Access results via the :attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute. - -.. code-block:: python - - from MDAnalysis.analysis import ExampleAnalysisModule # (e.g. RMSD) - analysis_obj = ExampleAnalysisModule.AnalysisClass(universe, ...) - analysis_obj.run(start=start_frame, stop=stop_frame, step=step) - print(analysis_obj.results) - -Please see the individual module documentation for any specific caveats -and also read and cite the reference papers associated with these algorithms. - - -Using parallelization for analysis tools ----------------------------------------- - -.. versionadded:: 2.8.0 - -Many analysis tools (based on :class:`~MDAnalysis.analysis.base.AnalysisBase`) -can be :ref:`run in parallel ` using a simple -split-apply-combine scheme whereby slices of the trajectory ("split") are analyzed in -parallel ("apply" the analysis function) and the data from the parallel executions -are "combined" at the end. - -MDAnalysis supports different :ref:`backends ` for the parallel execution such as -:mod:`multiprocessing` or `dask`_ (see :mod:`MDAnalysis.analysis.backends`). -As a special case, serial execution is handled by the default ``backend='serial'``, i.e., -by default, none of the analysis tools run in parallel and one has to explicitly request -parallel execution. Without any additionally installed dependencies, only one parallel backend -is supported -- Python :mod:`multiprocessing` (which is available in the Python standard -library), which processes each slice of a trajectory by running a separate *process* on a -different core of a multi-core CPU. - -.. _dask: https://dask.org/ - -.. Note:: - - Not all analysis tools in MDAnalysis can be parallelized and others have - not yet been updated to make use of the :ref:`parallelization framework `, - which was introduced in release 2.8.0. MDAnalysis aims to have parallelization enabled for - all analysis tools that support it by release 3.0. - -In order to use parallelization, add ``backend='multiprocessing'`` to the arguments of the -:meth:`~MDAnalysis.analysis.base.AnalysisBase.run` method together with ``n_workers=N`` where -``N`` is the number of CPUs that you want to use for parallelization. -(You can use ``multiprocessing.cpu_count()`` to get the maximum available number of CPUs on your -machine but this may not always lead to the best performance because of computational overheads and -the fact that parallel access to a single trajectory file is often a performance bottleneck.) As an -example we show how to run an RMSD calculation in parallel: - -.. code-block:: python - - import multiprocessing - import MDAnalysis as mda - from MDAnalysisTests.datafiles import PSF, DCD - from MDAnalysis.analysis.rms import RMSD - from MDAnalysis.analysis.align import AverageStructure - - # initialize the universe - u = mda.Universe(PSF, DCD) - - # calculate average structure for reference - avg = AverageStructure(mobile=u).run() - ref = avg.results.universe - - # initialize RMSD run - rmsd = RMSD(u, ref, select='backbone') - rmsd.run(backend='multiprocessing', n_workers=multiprocessing.cpu_count()) - -Be explicit and specify both ``backend`` and ``n_workers``. Choosing too many -workers or using large trajectory frames may lead to an out-of-memory error. - -You can also implement your own backends -- see :mod:`MDAnalysis.analysis.backends`. - -.. SeeAlso:: - :ref:`parallel-analysis` for technical details - - - -Additional dependencies ------------------------ - -Some of the modules in :mod:`MDAnalysis.analysis` require additional Python -packages to enable full functionality. For example, -:mod:`MDAnalysis.analysis.encore` provides more options if `scikit-learn`_ is -installed. If you installed MDAnalysis with :program:`pip` (see -:ref:`installation-instructions`) these packages are *not automatically -installed* although one can add the ``[analysis]`` tag to the :program:`pip` -command to force their installation. If you installed MDAnalysis with -:program:`conda` then a *full set of dependencies* is automatically installed. - -Other modules require external programs. For instance, the -:mod:`MDAnalysis.analysis.hole2` module requires an installation of the HOLE_ -suite of programs. You will need to install these external dependencies by -following their installation instructions before you can use the corresponding -MDAnalysis module. - -.. _scikit-learn: http://scikit-learn.org/ -.. _HOLE: http://www.holeprogram.org/ - - -Building blocks for Analysis -============================ - -The building block for the analysis modules is -:class:`MDAnalysis.analysis.base.AnalysisBase`. -To build your own analysis class start by reading the documentation. - -.. toctree:: - :maxdepth: 1 - - analysis/base - analysis/backends - analysis/results - analysis/parallelization - -Distances and contacts -====================== - -.. toctree:: - :maxdepth: 1 - - analysis/align - analysis/contacts - analysis/distances - analysis/atomicdistances - analysis/rms - analysis/psa - analysis/encore - analysis/bat - -Hydrogen bonding -================ - -.. toctree:: - :maxdepth: 1 - - analysis/hydrogenbonds - analysis/hbond_autocorrel - analysis/wbridge_analysis - -Deprecated modules: - -.. toctree:: - :maxdepth: 1 - - analysis/hbond_autocorrel_deprecated - -Membranes and membrane proteins -=============================== - -.. toctree:: - :maxdepth: 1 - - analysis/hole2 - analysis/leaflet - -Nucleic acids -============= - -.. toctree:: - :maxdepth: 1 - - analysis/nuclinfo - analysis/nucleicacids - -Polymers -======== - -.. toctree:: - :maxdepth: 1 - - analysis/polymer - - -Structure -========= - -Macromolecules --------------- - -.. toctree:: - :maxdepth: 1 - - analysis/gnm - analysis/helix_analysis - analysis/dihedrals - analysis/dssp - -Liquids -------- - -.. toctree:: - :maxdepth: 1 - - analysis/rdf - analysis/msd - -Volumetric analysis -=================== - -.. toctree:: - :maxdepth: 1 - - analysis/density - analysis/lineardensity - analysis/waterdynamics - analysis/dielectric - -Dimensionality Reduction -======================== -.. toctree:: - :maxdepth: 1 - - analysis/diffusionmap - analysis/pca - -Legacy analysis modules -======================= - -The :mod:`MDAnalysis.analysis.legacy` module contains code that for a -range of reasons is not as well maintained and tested as the other -analysis modules. *Use with care.* - -.. toctree:: - :maxdepth: 1 - - analysis/legacy_modules - -Data -==== - -.. toctree:: - :maxdepth: 1 - - analysis/data +.. Contains the formatted docstrings from the analysis modules located in 'mdanalysis/MDAnalysis/analysis', although in some cases the documentation imports functions and docstrings from other files which are also curated to reStructuredText markup. + +.. module:: MDAnalysis.analysis + +.. _analysis-label: + +**************** +Analysis modules +**************** + +The :mod:`MDAnalysis.analysis` module provides a wide collection of analysis tools for +molecular dynamics trajectories. These modules build upon MDAnalysis core functionality +(trajectory I/O, selections, etc.) and are designed both for reuse in research workflows +and as examples of using the MDAnalysis API. Each module typically defines an analysis +class that follows a standard interface. + +See the `User Guide Analysis section`_ for interactive examples and additional context. + +.. _User Guide Analysis section: https://userguide.mdanalysis.org/stable/examples/analysis/README.html + + +Getting started with analysis +============================= + +General usage pattern +--------------------- + +Most analysis tools are implemented as single classes and follow this usage pattern: + +#. Import the module (e.g., :mod:`MDAnalysis.analysis.rms`). +#. Initialize the analysis class with the required arguments. +#. Run the analysis with :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`. +#. Access results via the :attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute. + +.. code-block:: python + + from MDAnalysis.analysis import ExampleAnalysisModule # (e.g. RMSD) + analysis_obj = ExampleAnalysisModule.AnalysisClass(universe, ...) + analysis_obj.run(start=start_frame, stop=stop_frame, step=step) + print(analysis_obj.results) + +Please see the individual module documentation for any specific caveats +and also read and cite the reference papers associated with these algorithms. + + +Using parallelization for analysis tools +---------------------------------------- + +.. versionadded:: 2.8.0 + +Many analysis tools (based on :class:`~MDAnalysis.analysis.base.AnalysisBase`) +can be :ref:`run in parallel ` using a simple +split-apply-combine scheme whereby slices of the trajectory ("split") are analyzed in +parallel ("apply" the analysis function) and the data from the parallel executions +are "combined" at the end. + +MDAnalysis supports different :ref:`backends ` for the parallel execution such as +:mod:`multiprocessing` or `dask`_ (see :mod:`MDAnalysis.analysis.backends`). +As a special case, serial execution is handled by the default ``backend='serial'``, i.e., +by default, none of the analysis tools run in parallel and one has to explicitly request +parallel execution. Without any additionally installed dependencies, only one parallel backend +is supported -- Python :mod:`multiprocessing` (which is available in the Python standard +library), which processes each slice of a trajectory by running a separate *process* on a +different core of a multi-core CPU. + +.. _dask: https://dask.org/ + +.. Note:: + + Not all analysis tools in MDAnalysis can be parallelized and others have + not yet been updated to make use of the :ref:`parallelization framework `, + which was introduced in release 2.8.0. MDAnalysis aims to have parallelization enabled for + all analysis tools that support it by release 3.0. + +In order to use parallelization, add ``backend='multiprocessing'`` to the arguments of the +:meth:`~MDAnalysis.analysis.base.AnalysisBase.run` method together with ``n_workers=N`` where +``N`` is the number of CPUs that you want to use for parallelization. +(You can use ``multiprocessing.cpu_count()`` to get the maximum available number of CPUs on your +machine but this may not always lead to the best performance because of computational overheads and +the fact that parallel access to a single trajectory file is often a performance bottleneck.) As an +example we show how to run an RMSD calculation in parallel: + +.. code-block:: python + + import multiprocessing + import MDAnalysis as mda + from MDAnalysisTests.datafiles import PSF, DCD + from MDAnalysis.analysis.rms import RMSD + from MDAnalysis.analysis.align import AverageStructure + + # initialize the universe + u = mda.Universe(PSF, DCD) + + # calculate average structure for reference + avg = AverageStructure(mobile=u).run() + ref = avg.results.universe + + # initialize RMSD run + rmsd = RMSD(u, ref, select='backbone') + rmsd.run(backend='multiprocessing', n_workers=multiprocessing.cpu_count()) + +Be explicit and specify both ``backend`` and ``n_workers``. Choosing too many +workers or using large trajectory frames may lead to an out-of-memory error. + +You can also implement your own backends -- see :mod:`MDAnalysis.analysis.backends`. + +.. SeeAlso:: + :ref:`parallel-analysis` for technical details + + + +Additional dependencies +----------------------- + +Some of the modules in :mod:`MDAnalysis.analysis` require additional Python +packages to enable full functionality. For example, +:mod:`MDAnalysis.analysis.encore` provides more options if `scikit-learn`_ is +installed. If you installed MDAnalysis with :program:`pip` (see +:ref:`installation-instructions`) these packages are *not automatically +installed* although one can add the ``[analysis]`` tag to the :program:`pip` +command to force their installation. If you installed MDAnalysis with +:program:`conda` then a *full set of dependencies* is automatically installed. + +Other modules require external programs. For instance, the +:mod:`MDAnalysis.analysis.hole2` module requires an installation of the HOLE_ +suite of programs. You will need to install these external dependencies by +following their installation instructions before you can use the corresponding +MDAnalysis module. + +.. _scikit-learn: http://scikit-learn.org/ +.. _HOLE: http://www.holeprogram.org/ + + +Building blocks for Analysis +============================ + +The building block for the analysis modules is +:class:`MDAnalysis.analysis.base.AnalysisBase`. +To build your own analysis class start by reading the documentation. + +.. toctree:: + :maxdepth: 1 + + analysis/base + analysis/backends + analysis/results + analysis/parallelization + +Distances and contacts +====================== + +.. toctree:: + :maxdepth: 1 + + analysis/align + analysis/contacts + analysis/distances + analysis/atomicdistances + analysis/rms + analysis/psa + analysis/encore + analysis/bat + +Hydrogen bonding +================ + +.. toctree:: + :maxdepth: 1 + + analysis/hydrogenbonds + analysis/hbond_autocorrel + analysis/wbridge_analysis + +Deprecated modules: + +.. toctree:: + :maxdepth: 1 + + analysis/hbond_autocorrel_deprecated + +Membranes and membrane proteins +=============================== + +.. toctree:: + :maxdepth: 1 + + analysis/hole2 + analysis/leaflet + +Nucleic acids +============= + +.. toctree:: + :maxdepth: 1 + + analysis/nuclinfo + analysis/nucleicacids + +Polymers +======== + +.. toctree:: + :maxdepth: 1 + + analysis/polymer + + +Structure +========= + +Macromolecules +-------------- + +.. toctree:: + :maxdepth: 1 + + analysis/gnm + analysis/helix_analysis + analysis/dihedrals + analysis/dssp + +Liquids +------- + +.. toctree:: + :maxdepth: 1 + + analysis/rdf + analysis/msd + +Volumetric analysis +=================== + +.. toctree:: + :maxdepth: 1 + + analysis/density + analysis/lineardensity + analysis/waterdynamics + analysis/dielectric + +Dimensionality Reduction +======================== +.. toctree:: + :maxdepth: 1 + + analysis/diffusionmap + analysis/pca + +Legacy analysis modules +======================= + +The :mod:`MDAnalysis.analysis.legacy` module contains code that for a +range of reasons is not as well maintained and tested as the other +analysis modules. *Use with care.* + +.. toctree:: + :maxdepth: 1 + + analysis/legacy_modules + +Data +==== + +.. toctree:: + :maxdepth: 1 + + analysis/data diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary/EDR.rst b/package/doc/sphinx/source/documentation_pages/auxiliary/EDR.rst index 01ff5c913ea..c434b886c67 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary/EDR.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary/EDR.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.auxiliary.EDR +.. automodule:: MDAnalysis.auxiliary.EDR diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary/XVG.rst b/package/doc/sphinx/source/documentation_pages/auxiliary/XVG.rst index 08e68d05bd3..c984f3e26e7 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary/XVG.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary/XVG.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.auxiliary.XVG - +.. automodule:: MDAnalysis.auxiliary.XVG + diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary/base.rst b/package/doc/sphinx/source/documentation_pages/auxiliary/base.rst index 982d6962496..58686728013 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary/base.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary/base.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.auxiliary.base - +.. automodule:: MDAnalysis.auxiliary.base + diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary/core.rst b/package/doc/sphinx/source/documentation_pages/auxiliary/core.rst index f2bdfb0e1bc..34b140b8605 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary/core.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary/core.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.auxiliary.core - +.. automodule:: MDAnalysis.auxiliary.core + diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary/init.rst b/package/doc/sphinx/source/documentation_pages/auxiliary/init.rst index 850d09a8067..9a31289584c 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary/init.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary/init.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.auxiliary.__init__ - +.. automodule:: MDAnalysis.auxiliary.__init__ + diff --git a/package/doc/sphinx/source/documentation_pages/auxiliary_modules.rst b/package/doc/sphinx/source/documentation_pages/auxiliary_modules.rst index 0ff1b033e82..02e638f5e7f 100644 --- a/package/doc/sphinx/source/documentation_pages/auxiliary_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/auxiliary_modules.rst @@ -1,17 +1,17 @@ -.. Contains the formatted docstrings from the auxiliary modules located in 'mdanalysis/MDAnalysis/auxiliary' - -***************** -Auxiliary modules -***************** - -The auxiliary module contains the classes to read auxiliary data and sort out -alignment between auxiliary and trajectory data. - -.. toctree:: - :maxdepth: 1 - - auxiliary/init - auxiliary/base - auxiliary/core - auxiliary/XVG - auxiliary/EDR +.. Contains the formatted docstrings from the auxiliary modules located in 'mdanalysis/MDAnalysis/auxiliary' + +***************** +Auxiliary modules +***************** + +The auxiliary module contains the classes to read auxiliary data and sort out +alignment between auxiliary and trajectory data. + +.. toctree:: + :maxdepth: 1 + + auxiliary/init + auxiliary/base + auxiliary/core + auxiliary/XVG + auxiliary/EDR diff --git a/package/doc/sphinx/source/documentation_pages/converters.rst b/package/doc/sphinx/source/documentation_pages/converters.rst index 3bb4a8e0722..2a7ef86c5b1 100644 --- a/package/doc/sphinx/source/documentation_pages/converters.rst +++ b/package/doc/sphinx/source/documentation_pages/converters.rst @@ -1,62 +1,62 @@ -.. module:: MDAnalysis.converters - -.. _`Converter modules`: - -************************** -Converter modules -************************** - -.. versionadded:: 2.0.0 - -The :mod:`MDAnalysis.converters` module contains the Converter classes that -MDAnalysis uses to convert MDAnalysis structures to and from other Python -packages. - -If you are converting *to* MDAnalysis, you can use the normal syntax for -creating a Universe from files. Typically MDAnalysis will recognise which -library it is dealing with, so you will not need to pass in a ``format`` keyword. - -For example:: - - import MDAnalysis as mda - from MDAnalysis import GRO - import parmed as pmd - - pgro = pmd.load_file(GRO) # creates parmed structure - ugro = mda.Universe(pgro) # you can just pass it in - -If you are converting *from* MDAnalysis, use the -:func:`~MDAnalysis.core.groups.AtomGroup.convert_to` method. With this, -you will have to specify a package name (case-insensitive). :: - - pgro2 = ugro.atoms.convert_to('PARMED') # converts back to parmed structure - -Another syntax is also available for tab-completion support:: - - pgro2 = ugro.atoms.convert_to.parmed() - - -.. rubric:: Available converters - -.. toctree:: - :maxdepth: 1 - - converters/ParmEd - converters/RDKit - converters/OpenMM - -.. rubric:: Converter functionalities - -.. toctree:: - :maxdepth: 1 - - core/accessors - - -Developers may find the :mod:`MDAnaylsis.converters.base` module helpful for -creating new converter classes. - -.. toctree:: - :maxdepth: 1 - +.. module:: MDAnalysis.converters + +.. _`Converter modules`: + +************************** +Converter modules +************************** + +.. versionadded:: 2.0.0 + +The :mod:`MDAnalysis.converters` module contains the Converter classes that +MDAnalysis uses to convert MDAnalysis structures to and from other Python +packages. + +If you are converting *to* MDAnalysis, you can use the normal syntax for +creating a Universe from files. Typically MDAnalysis will recognise which +library it is dealing with, so you will not need to pass in a ``format`` keyword. + +For example:: + + import MDAnalysis as mda + from MDAnalysis import GRO + import parmed as pmd + + pgro = pmd.load_file(GRO) # creates parmed structure + ugro = mda.Universe(pgro) # you can just pass it in + +If you are converting *from* MDAnalysis, use the +:func:`~MDAnalysis.core.groups.AtomGroup.convert_to` method. With this, +you will have to specify a package name (case-insensitive). :: + + pgro2 = ugro.atoms.convert_to('PARMED') # converts back to parmed structure + +Another syntax is also available for tab-completion support:: + + pgro2 = ugro.atoms.convert_to.parmed() + + +.. rubric:: Available converters + +.. toctree:: + :maxdepth: 1 + + converters/ParmEd + converters/RDKit + converters/OpenMM + +.. rubric:: Converter functionalities + +.. toctree:: + :maxdepth: 1 + + core/accessors + + +Developers may find the :mod:`MDAnaylsis.converters.base` module helpful for +creating new converter classes. + +.. toctree:: + :maxdepth: 1 + converters/base \ No newline at end of file diff --git a/package/doc/sphinx/source/documentation_pages/converters/OpenMM.rst b/package/doc/sphinx/source/documentation_pages/converters/OpenMM.rst index 01fd1d5fca4..34e324d218f 100644 --- a/package/doc/sphinx/source/documentation_pages/converters/OpenMM.rst +++ b/package/doc/sphinx/source/documentation_pages/converters/OpenMM.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.converters.OpenMMParser - -.. automodule:: MDAnalysis.converters.OpenMM +.. automodule:: MDAnalysis.converters.OpenMMParser + +.. automodule:: MDAnalysis.converters.OpenMM diff --git a/package/doc/sphinx/source/documentation_pages/converters/ParmEd.rst b/package/doc/sphinx/source/documentation_pages/converters/ParmEd.rst index fc249683811..050e59c8438 100644 --- a/package/doc/sphinx/source/documentation_pages/converters/ParmEd.rst +++ b/package/doc/sphinx/source/documentation_pages/converters/ParmEd.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.converters.ParmEdParser - -.. automodule:: MDAnalysis.converters.ParmEd +.. automodule:: MDAnalysis.converters.ParmEdParser + +.. automodule:: MDAnalysis.converters.ParmEd diff --git a/package/doc/sphinx/source/documentation_pages/converters/RDKit.rst b/package/doc/sphinx/source/documentation_pages/converters/RDKit.rst index fa4525f69b6..efe098b00ba 100644 --- a/package/doc/sphinx/source/documentation_pages/converters/RDKit.rst +++ b/package/doc/sphinx/source/documentation_pages/converters/RDKit.rst @@ -1,5 +1,5 @@ -.. automodule:: MDAnalysis.converters.RDKitParser - -.. automodule:: MDAnalysis.converters.RDKit - -.. automodule:: MDAnalysis.converters.RDKitInferring +.. automodule:: MDAnalysis.converters.RDKitParser + +.. automodule:: MDAnalysis.converters.RDKit + +.. automodule:: MDAnalysis.converters.RDKitInferring diff --git a/package/doc/sphinx/source/documentation_pages/converters/base.rst b/package/doc/sphinx/source/documentation_pages/converters/base.rst index 5bd2124869d..d342d3beec0 100644 --- a/package/doc/sphinx/source/documentation_pages/converters/base.rst +++ b/package/doc/sphinx/source/documentation_pages/converters/base.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.converters.base +.. automodule:: MDAnalysis.converters.base diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/CRD.rst b/package/doc/sphinx/source/documentation_pages/coordinates/CRD.rst index 96e9c4322f1..3fc4ff4a9d0 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/CRD.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/CRD.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.CRD - :members: +.. automodule:: MDAnalysis.coordinates.CRD + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/DCD.rst b/package/doc/sphinx/source/documentation_pages/coordinates/DCD.rst index 7ebed363a87..b8f511e0919 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/DCD.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/DCD.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.DCD +.. automodule:: MDAnalysis.coordinates.DCD diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/DLPoly.rst b/package/doc/sphinx/source/documentation_pages/coordinates/DLPoly.rst index 3f68e546c2d..f1f567ec6a1 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/DLPoly.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/DLPoly.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.DLPoly - :members: +.. automodule:: MDAnalysis.coordinates.DLPoly + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/DMS.rst b/package/doc/sphinx/source/documentation_pages/coordinates/DMS.rst index eb42d8f802c..cc63973c0e8 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/DMS.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/DMS.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.DMS - :members: +.. automodule:: MDAnalysis.coordinates.DMS + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/FHIAIMS.rst b/package/doc/sphinx/source/documentation_pages/coordinates/FHIAIMS.rst index f078e23b1bf..92bfb34f25e 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/FHIAIMS.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/FHIAIMS.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.FHIAIMS - +.. automodule:: MDAnalysis.coordinates.FHIAIMS + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/GMS.rst b/package/doc/sphinx/source/documentation_pages/coordinates/GMS.rst index dd811a04075..08b272e22a5 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/GMS.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/GMS.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.GMS - +.. automodule:: MDAnalysis.coordinates.GMS + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/GRO.rst b/package/doc/sphinx/source/documentation_pages/coordinates/GRO.rst index 5031c40fe32..659995c58a0 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/GRO.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/GRO.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.GRO - +.. automodule:: MDAnalysis.coordinates.GRO + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/GSD.rst b/package/doc/sphinx/source/documentation_pages/coordinates/GSD.rst index aff15b428fa..4fdae5f57e7 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/GSD.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/GSD.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.GSD +.. automodule:: MDAnalysis.coordinates.GSD diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/H5MD.rst b/package/doc/sphinx/source/documentation_pages/coordinates/H5MD.rst index 3757e061488..b7975c4c968 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/H5MD.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/H5MD.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.H5MD +.. automodule:: MDAnalysis.coordinates.H5MD diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/INPCRD.rst b/package/doc/sphinx/source/documentation_pages/coordinates/INPCRD.rst index 1d697c0ccf2..84f8fbdf61b 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/INPCRD.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/INPCRD.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.INPCRD +.. automodule:: MDAnalysis.coordinates.INPCRD diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/LAMMPS.rst b/package/doc/sphinx/source/documentation_pages/coordinates/LAMMPS.rst index 804bc509f6e..29f2ffbd628 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/LAMMPS.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/LAMMPS.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.LAMMPS - +.. automodule:: MDAnalysis.coordinates.LAMMPS + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/MMTF.rst b/package/doc/sphinx/source/documentation_pages/coordinates/MMTF.rst index 09df91d6c62..ecaa73beab2 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/MMTF.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/MMTF.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.MMTF - +.. automodule:: MDAnalysis.coordinates.MMTF + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/MOL2.rst b/package/doc/sphinx/source/documentation_pages/coordinates/MOL2.rst index 278b94d7b29..322d2d44551 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/MOL2.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/MOL2.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.MOL2 - +.. automodule:: MDAnalysis.coordinates.MOL2 + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/NAMDBIN.rst b/package/doc/sphinx/source/documentation_pages/coordinates/NAMDBIN.rst index 974ef39c954..30050690c52 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/NAMDBIN.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/NAMDBIN.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.NAMDBIN +.. automodule:: MDAnalysis.coordinates.NAMDBIN diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/PDB.rst b/package/doc/sphinx/source/documentation_pages/coordinates/PDB.rst index 0ca77f92c6a..3d5dc421969 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/PDB.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/PDB.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.PDB - +.. automodule:: MDAnalysis.coordinates.PDB + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/PDBQT.rst b/package/doc/sphinx/source/documentation_pages/coordinates/PDBQT.rst index 48b76473254..e61712b159b 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/PDBQT.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/PDBQT.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.PDBQT - :members: +.. automodule:: MDAnalysis.coordinates.PDBQT + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/PQR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/PQR.rst index 3ebc0846dcb..c0e97651919 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/PQR.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/PQR.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.PQR - :members: +.. automodule:: MDAnalysis.coordinates.PQR + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TNG.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TNG.rst index b8c8c3bca3d..ae8fa1fc221 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TNG.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TNG.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.TNG - :members: +.. automodule:: MDAnalysis.coordinates.TNG + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TPR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TPR.rst index ef37e7af1e0..d7782fc5b15 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TPR.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TPR.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.TPR +.. automodule:: MDAnalysis.coordinates.TPR diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TRC.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TRC.rst index 9312cc177df..0f40507af57 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TRC.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TRC.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.TRC +.. automodule:: MDAnalysis.coordinates.TRC diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TRJ.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TRJ.rst index 2059bc55fe1..d0f089a3b1f 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TRJ.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TRJ.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.TRJ - +.. automodule:: MDAnalysis.coordinates.TRJ + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst index 4c9b0770dd4..f83d06d05bd 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TRR.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.coordinates.TRR - :members: - :inherited-members: +.. automodule:: MDAnalysis.coordinates.TRR + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TRZ.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TRZ.rst index 0fe61ad8992..48f683cf57a 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TRZ.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TRZ.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.TRZ - +.. automodule:: MDAnalysis.coordinates.TRZ + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/TXYZ.rst b/package/doc/sphinx/source/documentation_pages/coordinates/TXYZ.rst index 2dbe52423be..3a60d771c84 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/TXYZ.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/TXYZ.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.TXYZ - +.. automodule:: MDAnalysis.coordinates.TXYZ + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/XDR.rst b/package/doc/sphinx/source/documentation_pages/coordinates/XDR.rst index 1c585e324ef..47d4dacd9a1 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/XDR.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/XDR.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.coordinates.XDR - :members: - :inherited-members: +.. automodule:: MDAnalysis.coordinates.XDR + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst b/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst index 1588bb88550..9a8f97dadf1 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/XTC.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.coordinates.XTC - :members: - :inherited-members: +.. automodule:: MDAnalysis.coordinates.XTC + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/XYZ.rst b/package/doc/sphinx/source/documentation_pages/coordinates/XYZ.rst index a98129b608d..03809ea2e89 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/XYZ.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/XYZ.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.XYZ - :members: +.. automodule:: MDAnalysis.coordinates.XYZ + :members: diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/base.rst b/package/doc/sphinx/source/documentation_pages/coordinates/base.rst index 700ee30f5fd..b4f54df1f5f 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/base.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/base.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.base - +.. automodule:: MDAnalysis.coordinates.base + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/chain.rst b/package/doc/sphinx/source/documentation_pages/coordinates/chain.rst index 180b4266691..cd79e5972bd 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/chain.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/chain.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.chain - +.. automodule:: MDAnalysis.coordinates.chain + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/chemfiles.rst b/package/doc/sphinx/source/documentation_pages/coordinates/chemfiles.rst index 13016a9a621..ddc0486a540 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/chemfiles.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/chemfiles.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.chemfiles +.. automodule:: MDAnalysis.coordinates.chemfiles diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/core.rst b/package/doc/sphinx/source/documentation_pages/coordinates/core.rst index 37696683e7a..c1274b974c5 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/core.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/core.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.core - +.. automodule:: MDAnalysis.coordinates.core + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/init.rst b/package/doc/sphinx/source/documentation_pages/coordinates/init.rst index 2b3637156f3..b2b399e4f3c 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/init.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/init.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.coordinates.__init__ - +.. automodule:: MDAnalysis.coordinates.__init__ + diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/memory.rst b/package/doc/sphinx/source/documentation_pages/coordinates/memory.rst index e02e1e1d4c2..6763ed3bf9c 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/memory.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/memory.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.memory +.. automodule:: MDAnalysis.coordinates.memory diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/null.rst b/package/doc/sphinx/source/documentation_pages/coordinates/null.rst index ab0b375de41..70e33502936 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/null.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/null.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.null +.. automodule:: MDAnalysis.coordinates.null diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/pickle_readers.rst b/package/doc/sphinx/source/documentation_pages/coordinates/pickle_readers.rst index fbcc881ab0c..5703c4ce23f 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/pickle_readers.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/pickle_readers.rst @@ -1,102 +1,102 @@ -.. Contains the formatted docstrings for the serialization of universe located -.. mainly in 'MDAnalysis/libs/pickle_file_io.py' -.. _serialization: - -********************************************************* -Serialization of Coordinate Readers -********************************************************* - -To achieve a working implementation of parallelism, this document illustrates -the basic idea of how different coordinate readers are being serialized in MDAnalysis, -and what developers should do to serialize a new reader. - -To make sure every Trajectory reader can be successfully -serialized, we implement picklable I/O classes (see :ref:`implemented-fileio`). -When the file is pickled, filename and other necessary attributes of the open -file handle are saved. On unpickling, the file is opened by filename. -This means that for a successful unpickle, the original file still has to -be accessible with its filename. To retain the current frame of the trajectory, -:func:`_read_frame(previous frame)` will be called during unpickling. - -.. _how_to_serialize_a_new_reader: - -How to serialize a new reader ------------------------------ - -File Access -^^^^^^^^^^^ -If the new reader uses :func:`util.anyopen()` -(e.g. :class:`MDAnalysis.coordinates.PDB.PDBReader`), -the reading handler can be pickled without modification. -If the new reader uses I/O classes from other package -(e.g. :class:`MDAnalysis.coordinates.GSD.GSDReader`), -and cannot be pickled natively, create a new picklable class inherited from -the file class in that package -(e.g. :class:`MDAnalysis.coordinates.GSD.GSDPicklable`), -adding :func:`__getstate__`, -:func:`__setstate__` functions (or :func:`__reduce__` if needed. Consult the -pickle `documentation `_ of python) -to allow file handler serialization. - -To seek or not to seek -^^^^^^^^^^^^^^^^^^^^^^ -Some I/O classes support :func:`seek` and :func:`tell` functions to allow the file -to be pickled with an offset. It is normally not needed for MDAnalysis with -random access. But if error occurs during testing, find a way to make the offset work. -Maybe this I/O class supports frame indexing? Maybe the file handler inside this I/O -class supports offset? - -For example, in :class:`MDAnalysis.coordinates.TRZ.TRZReader`, -:func:`_read_frame` is implemented by :func:`_seek` ing the file into -its previous frame and :func:`_read_next_timestep`, so the offset of the file is crucial -for such machinery to work. - -Miscellaneous -^^^^^^^^^^^^^ -If pickle still fails due to some unpicklable attributes, try to find a way -to pickle those, or write custom :func:`__getstate__` and :func:`__setstate__` -methods for the reader. - -If the new reader is written in Cython, read :class:`lib.formats.libmdaxdr` and -:class:`lib.formats.libdcd` files as references. - -.. _test_pickle: - -Tests ------ -_SingleFrameReader Test -^^^^^^^^^^^^^^^^^^^^^^^ -If the new reader is a single-frame reader, the basic test should normally -inherited from :class:`_SingleFrameReader`, where the pickliablity is tested. - -BaseReaderTest and MultiframeReaderTest -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If the test for the new reader uses :class:`BaseReaderTest` or -:class:`MultiframeReaderTest`, whether the current timestep information is -saved (the former), whether its relative position is maintained, -i.e. next() reads the right next timestep, and whether its last timestep -can be pickled, are already tested. - -File handler Test -^^^^^^^^^^^^^^^^^ -If the new reader accesses the file with :func:`util.anyopen`, add necessary -tests inside ``parallelism/test_multiprocessing.py`` for the reader. - -If the new reader accessed the file with a new picklable I/O class, -add necessary tests inside ``utils/test_pickleio.py`` for the I/O class, -``parallelism/test_multiprocessing.py`` for the reader. - -.. _implemented-fileio: - -Currently implemented picklable IO Formats ------------------------------------------- - -* :class:`MDAnalysis.lib.picklable_file_io.FileIOPicklable` -* :class:`MDAnalysis.lib.picklable_file_io.BufferIOPicklable` -* :class:`MDAnalysis.lib.picklable_file_io.TextIOPicklable` -* :class:`MDAnalysis.lib.picklable_file_io.BZ2Picklable` -* :class:`MDAnalysis.lib.picklable_file_io.GzipPicklable` -* :class:`MDAnalysis.coordinates.GSD.GSDPicklable` -* :class:`MDAnalysis.coordinates.TRJ.NCDFPicklable` -* :class:`MDAnalysis.coordinates.chemfiles.ChemfilesPicklable` -* :class:`MDAnalysis.coordinates.H5MD.H5PYPicklable` +.. Contains the formatted docstrings for the serialization of universe located +.. mainly in 'MDAnalysis/libs/pickle_file_io.py' +.. _serialization: + +********************************************************* +Serialization of Coordinate Readers +********************************************************* + +To achieve a working implementation of parallelism, this document illustrates +the basic idea of how different coordinate readers are being serialized in MDAnalysis, +and what developers should do to serialize a new reader. + +To make sure every Trajectory reader can be successfully +serialized, we implement picklable I/O classes (see :ref:`implemented-fileio`). +When the file is pickled, filename and other necessary attributes of the open +file handle are saved. On unpickling, the file is opened by filename. +This means that for a successful unpickle, the original file still has to +be accessible with its filename. To retain the current frame of the trajectory, +:func:`_read_frame(previous frame)` will be called during unpickling. + +.. _how_to_serialize_a_new_reader: + +How to serialize a new reader +----------------------------- + +File Access +^^^^^^^^^^^ +If the new reader uses :func:`util.anyopen()` +(e.g. :class:`MDAnalysis.coordinates.PDB.PDBReader`), +the reading handler can be pickled without modification. +If the new reader uses I/O classes from other package +(e.g. :class:`MDAnalysis.coordinates.GSD.GSDReader`), +and cannot be pickled natively, create a new picklable class inherited from +the file class in that package +(e.g. :class:`MDAnalysis.coordinates.GSD.GSDPicklable`), +adding :func:`__getstate__`, +:func:`__setstate__` functions (or :func:`__reduce__` if needed. Consult the +pickle `documentation `_ of python) +to allow file handler serialization. + +To seek or not to seek +^^^^^^^^^^^^^^^^^^^^^^ +Some I/O classes support :func:`seek` and :func:`tell` functions to allow the file +to be pickled with an offset. It is normally not needed for MDAnalysis with +random access. But if error occurs during testing, find a way to make the offset work. +Maybe this I/O class supports frame indexing? Maybe the file handler inside this I/O +class supports offset? + +For example, in :class:`MDAnalysis.coordinates.TRZ.TRZReader`, +:func:`_read_frame` is implemented by :func:`_seek` ing the file into +its previous frame and :func:`_read_next_timestep`, so the offset of the file is crucial +for such machinery to work. + +Miscellaneous +^^^^^^^^^^^^^ +If pickle still fails due to some unpicklable attributes, try to find a way +to pickle those, or write custom :func:`__getstate__` and :func:`__setstate__` +methods for the reader. + +If the new reader is written in Cython, read :class:`lib.formats.libmdaxdr` and +:class:`lib.formats.libdcd` files as references. + +.. _test_pickle: + +Tests +----- +_SingleFrameReader Test +^^^^^^^^^^^^^^^^^^^^^^^ +If the new reader is a single-frame reader, the basic test should normally +inherited from :class:`_SingleFrameReader`, where the pickliablity is tested. + +BaseReaderTest and MultiframeReaderTest +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If the test for the new reader uses :class:`BaseReaderTest` or +:class:`MultiframeReaderTest`, whether the current timestep information is +saved (the former), whether its relative position is maintained, +i.e. next() reads the right next timestep, and whether its last timestep +can be pickled, are already tested. + +File handler Test +^^^^^^^^^^^^^^^^^ +If the new reader accesses the file with :func:`util.anyopen`, add necessary +tests inside ``parallelism/test_multiprocessing.py`` for the reader. + +If the new reader accessed the file with a new picklable I/O class, +add necessary tests inside ``utils/test_pickleio.py`` for the I/O class, +``parallelism/test_multiprocessing.py`` for the reader. + +.. _implemented-fileio: + +Currently implemented picklable IO Formats +------------------------------------------ + +* :class:`MDAnalysis.lib.picklable_file_io.FileIOPicklable` +* :class:`MDAnalysis.lib.picklable_file_io.BufferIOPicklable` +* :class:`MDAnalysis.lib.picklable_file_io.TextIOPicklable` +* :class:`MDAnalysis.lib.picklable_file_io.BZ2Picklable` +* :class:`MDAnalysis.lib.picklable_file_io.GzipPicklable` +* :class:`MDAnalysis.coordinates.GSD.GSDPicklable` +* :class:`MDAnalysis.coordinates.TRJ.NCDFPicklable` +* :class:`MDAnalysis.coordinates.chemfiles.ChemfilesPicklable` +* :class:`MDAnalysis.coordinates.H5MD.H5PYPicklable` diff --git a/package/doc/sphinx/source/documentation_pages/coordinates/timestep.rst b/package/doc/sphinx/source/documentation_pages/coordinates/timestep.rst index 34c34cfbcbd..7832d39289f 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates/timestep.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates/timestep.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.coordinates.timestep +.. automodule:: MDAnalysis.coordinates.timestep diff --git a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst index 8a27767f23f..e2a9b8a3084 100644 --- a/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/coordinates_modules.rst @@ -1,73 +1,73 @@ -.. Contains the formatted docstrings from the coordinates modules located in 'mdanalysis/MDAnalysis/coordinates' -.. _Coordinates: - -************************** -Coordinates modules -************************** - -The coordinates module contains the classes to read and write -trajectories. Typically, MDAnalysis recognizes :ref:`Supported coordinate -formats` by the file extension and hence most users probably do not need to -concern themselves with classes and functions described here. However, -if MDAnalysis fails to recognize a coordinate file then the user can -provide the format in the keyword argument *format* to -:class:`~MDAnalysis.core.universe.Universe` to force the format. - -.. rubric:: Coordinate formats - -.. toctree:: - :maxdepth: 1 - - coordinates/init - coordinates/CRD - coordinates/DCD - coordinates/DLPoly - coordinates/DMS - coordinates/GMS - coordinates/GSD - coordinates/GRO - coordinates/H5MD - coordinates/IMD - coordinates/INPCRD - coordinates/LAMMPS - coordinates/MMTF - coordinates/MOL2 - coordinates/NAMDBIN - coordinates/PDB - coordinates/PDBQT - coordinates/PQR - coordinates/TNG - coordinates/TPR - coordinates/TRC - coordinates/TRJ - coordinates/TRR - coordinates/TRZ - coordinates/TXYZ - coordinates/XTC - coordinates/XYZ - coordinates/FHIAIMS - coordinates/memory - coordinates/chemfiles - coordinates/null - -.. rubric:: Coordinate core modules - -The remaining pages are primarily of interest to -developers. Programmers and anyone trying to implement new -functionality should first read the :ref:`Trajectory API`. - - -.. toctree:: - :maxdepth: 1 - - coordinates/timestep - coordinates/base - coordinates/core - coordinates/pickle_readers - coordinates/chain - coordinates/XDR - -In particular, all trajectory readers have to be -:ref:`serializable` and they should pass all tests -available in the ``MDAnalysisTests.coordinates.base.MultiframeReaderTest`` -or ``MDAnalysisTests.coordinates.base.BaseReaderTest``. +.. Contains the formatted docstrings from the coordinates modules located in 'mdanalysis/MDAnalysis/coordinates' +.. _Coordinates: + +************************** +Coordinates modules +************************** + +The coordinates module contains the classes to read and write +trajectories. Typically, MDAnalysis recognizes :ref:`Supported coordinate +formats` by the file extension and hence most users probably do not need to +concern themselves with classes and functions described here. However, +if MDAnalysis fails to recognize a coordinate file then the user can +provide the format in the keyword argument *format* to +:class:`~MDAnalysis.core.universe.Universe` to force the format. + +.. rubric:: Coordinate formats + +.. toctree:: + :maxdepth: 1 + + coordinates/init + coordinates/CRD + coordinates/DCD + coordinates/DLPoly + coordinates/DMS + coordinates/GMS + coordinates/GSD + coordinates/GRO + coordinates/H5MD + coordinates/IMD + coordinates/INPCRD + coordinates/LAMMPS + coordinates/MMTF + coordinates/MOL2 + coordinates/NAMDBIN + coordinates/PDB + coordinates/PDBQT + coordinates/PQR + coordinates/TNG + coordinates/TPR + coordinates/TRC + coordinates/TRJ + coordinates/TRR + coordinates/TRZ + coordinates/TXYZ + coordinates/XTC + coordinates/XYZ + coordinates/FHIAIMS + coordinates/memory + coordinates/chemfiles + coordinates/null + +.. rubric:: Coordinate core modules + +The remaining pages are primarily of interest to +developers. Programmers and anyone trying to implement new +functionality should first read the :ref:`Trajectory API`. + + +.. toctree:: + :maxdepth: 1 + + coordinates/timestep + coordinates/base + coordinates/core + coordinates/pickle_readers + coordinates/chain + coordinates/XDR + +In particular, all trajectory readers have to be +:ref:`serializable` and they should pass all tests +available in the ``MDAnalysisTests.coordinates.base.MultiframeReaderTest`` +or ``MDAnalysisTests.coordinates.base.BaseReaderTest``. diff --git a/package/doc/sphinx/source/documentation_pages/core/groups.rst b/package/doc/sphinx/source/documentation_pages/core/groups.rst index 0ea31cda4ad..ce7312c35e3 100644 --- a/package/doc/sphinx/source/documentation_pages/core/groups.rst +++ b/package/doc/sphinx/source/documentation_pages/core/groups.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.core.groups +.. automodule:: MDAnalysis.core.groups diff --git a/package/doc/sphinx/source/documentation_pages/core/init.rst b/package/doc/sphinx/source/documentation_pages/core/init.rst index 2dc72f84fe1..44ccdb0d863 100644 --- a/package/doc/sphinx/source/documentation_pages/core/init.rst +++ b/package/doc/sphinx/source/documentation_pages/core/init.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.core.__init__ - +.. automodule:: MDAnalysis.core.__init__ + diff --git a/package/doc/sphinx/source/documentation_pages/core/selection.rst b/package/doc/sphinx/source/documentation_pages/core/selection.rst index 8f3e40ecffc..4e34b477593 100644 --- a/package/doc/sphinx/source/documentation_pages/core/selection.rst +++ b/package/doc/sphinx/source/documentation_pages/core/selection.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.core.selection - :members: +.. automodule:: MDAnalysis.core.selection + :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/topology.rst b/package/doc/sphinx/source/documentation_pages/core/topology.rst index 9d9dfa242a8..73763b1a4ce 100644 --- a/package/doc/sphinx/source/documentation_pages/core/topology.rst +++ b/package/doc/sphinx/source/documentation_pages/core/topology.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.core.topology +.. automodule:: MDAnalysis.core.topology diff --git a/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst b/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst index 9eda33222c8..521d453aeb2 100644 --- a/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst +++ b/package/doc/sphinx/source/documentation_pages/core/topologyattrs.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.core.topologyattrs - :members: +.. automodule:: MDAnalysis.core.topologyattrs + :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/topologyobjects.rst b/package/doc/sphinx/source/documentation_pages/core/topologyobjects.rst index 5e8446e8fa4..1937d0523a9 100644 --- a/package/doc/sphinx/source/documentation_pages/core/topologyobjects.rst +++ b/package/doc/sphinx/source/documentation_pages/core/topologyobjects.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.core.topologyobjects - :members: +.. automodule:: MDAnalysis.core.topologyobjects + :members: diff --git a/package/doc/sphinx/source/documentation_pages/core/universe.rst b/package/doc/sphinx/source/documentation_pages/core/universe.rst index 4aff509154d..b6b4edc8c25 100644 --- a/package/doc/sphinx/source/documentation_pages/core/universe.rst +++ b/package/doc/sphinx/source/documentation_pages/core/universe.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.core.universe +.. automodule:: MDAnalysis.core.universe diff --git a/package/doc/sphinx/source/documentation_pages/core_modules.rst b/package/doc/sphinx/source/documentation_pages/core_modules.rst index deb04c22841..4b256b45916 100644 --- a/package/doc/sphinx/source/documentation_pages/core_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/core_modules.rst @@ -1,59 +1,59 @@ -.. Contains the formatted docstrings for the core modules located in 'mdanalysis/MDAnalysis/core' - -************************** -Core modules -************************** - -The :mod:`MDAnalysis.core` modules contain functionality essential for -MDAnalysis, such as the central data structures in -:mod:`MDAnalysis.core.universe` and :mod:`MDAnalysis.core.groups` or -the selection definitions and parsing in -:mod:`MDAnalysis.core.selection`. - -.. toctree:: - :maxdepth: 1 - - core/init - -Important objects for users -=========================== - -All users of MDAnalysis need to understand the two most important -classes in this section, namely the -:class:`~MDAnalysis.core.universe.Universe` and the -:class:`~MDAnalysis.core.groups.AtomGroup`. - -.. toctree:: - :maxdepth: 1 - - core/universe - core/groups - - -.. _topology-system-label: - -Topology system -=============== - -The topology system is primarily of interest to developers. - -.. toctree:: - :maxdepth: 1 - - core/topology - core/topologyobjects - core/topologyattrs - -.. SeeAlso:: :ref:`Developer notes for Topology - Parsers ` - -Selection system -================ - -The selection system is primarily of interest to developers. - -.. toctree:: - :maxdepth: 1 - - core/selection - +.. Contains the formatted docstrings for the core modules located in 'mdanalysis/MDAnalysis/core' + +************************** +Core modules +************************** + +The :mod:`MDAnalysis.core` modules contain functionality essential for +MDAnalysis, such as the central data structures in +:mod:`MDAnalysis.core.universe` and :mod:`MDAnalysis.core.groups` or +the selection definitions and parsing in +:mod:`MDAnalysis.core.selection`. + +.. toctree:: + :maxdepth: 1 + + core/init + +Important objects for users +=========================== + +All users of MDAnalysis need to understand the two most important +classes in this section, namely the +:class:`~MDAnalysis.core.universe.Universe` and the +:class:`~MDAnalysis.core.groups.AtomGroup`. + +.. toctree:: + :maxdepth: 1 + + core/universe + core/groups + + +.. _topology-system-label: + +Topology system +=============== + +The topology system is primarily of interest to developers. + +.. toctree:: + :maxdepth: 1 + + core/topology + core/topologyobjects + core/topologyattrs + +.. SeeAlso:: :ref:`Developer notes for Topology + Parsers ` + +Selection system +================ + +The selection system is primarily of interest to developers. + +.. toctree:: + :maxdepth: 1 + + core/selection + diff --git a/package/doc/sphinx/source/documentation_pages/exceptions.rst b/package/doc/sphinx/source/documentation_pages/exceptions.rst index 8d93a5193f5..787d2e0ab33 100644 --- a/package/doc/sphinx/source/documentation_pages/exceptions.rst +++ b/package/doc/sphinx/source/documentation_pages/exceptions.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.exceptions - :members: +.. automodule:: MDAnalysis.exceptions + :members: diff --git a/package/doc/sphinx/source/documentation_pages/fetchers_modules.rst b/package/doc/sphinx/source/documentation_pages/fetchers_modules.rst index bdcff49164b..4e01acb4197 100644 --- a/package/doc/sphinx/source/documentation_pages/fetchers_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/fetchers_modules.rst @@ -1,18 +1,18 @@ -.. Contains the formatted docstrings from the fetch modules located in 'mdanalysis/MDAnalysis/fetch' - -************************** -Fetchers modules -************************** - -The fetch module contains code that are able to retrieve data from -the internet. All code in this module currently depends on the -dependency :mod:`pooch` which is required in order to run this -module. - -.. rubric:: Fetcher functions - -.. toctree:: - :maxdepth: 1 - - fetchers/init - fetchers/PDB +.. Contains the formatted docstrings from the fetch modules located in 'mdanalysis/MDAnalysis/fetch' + +************************** +Fetchers modules +************************** + +The fetch module contains code that are able to retrieve data from +the internet. All code in this module currently depends on the +dependency :mod:`pooch` which is required in order to run this +module. + +.. rubric:: Fetcher functions + +.. toctree:: + :maxdepth: 1 + + fetchers/init + fetchers/PDB diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst index d672b748bb5..dd12eb77b7a 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst @@ -1,78 +1,78 @@ -.. Contains the formatted docstrings from the guesser modules located in 'mdanalysis/package/MDAnalysis/guesser' - -.. _Guessers: - -************************** -Guesser modules -************************** -This module contains the context-aware guessers, which are used by the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API. Context-aware guessers' main purpose -is to be tailored guesser classes that target specific file format or force field (eg. PDB file format, or Martini forcefield). -Having such guessers makes attribute guessing more accurate and reliable than having generic guessing methods that don't fit all scenarios. - -Example uses of guessers ------------------------- - -Default behavior -~~~~~~~~~~~~~~~~ - -By default, MDAnalysis will guess the "mass" and "type" (atom type) attributes for all particles in the Universe -using the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` at the time of Universe creation, -if they are not read from the input file. If the required information is not present in the input file, -a warning will be raised. -Please see the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` for more information. - - - -Guessing using :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Guessing can be done through the Universe's :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` as following:: - - import MDAnalysis as mda - from MDAnalysisTests.datafiles import PDB - - u = mda.Universe(PDB) - print(hasattr(u.atoms, 'elements')) # returns False - u.guess_TopologyAttrs(to_guess=['elements']) - print(u.atoms.elements) # print ['N' 'H' 'H' ... 'NA' 'NA' 'NA'] - -In the above example, we passed ``elements`` as the attribute we want to guess -:meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` guess then add it as a topology -attribute to the ``AtomGroup`` of the universe. - -If the attribute already exists in the universe, passing the attribute of interest to the ``to_guess`` parameter will only fill the empty values of the attribute if any exists. -To override all the attribute values, you can pass the attribute to the ``force_guess`` parameter instead of ``to_guess`` as following:: - - import MDAnalysis as mda - from MDAnalysisTests.datafiles import PRM12 -  - u = mda.Universe(PRM12, context='default', to_guess=()) # types ['HW', 'OW', ..] - - u.guess_TopologyAttrs(force_guess=['types']) # types ['H', 'O', ..] - - -.. note:: - The default ``context`` will use the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` - - - - -.. rubric:: Available guessers -.. toctree:: - :maxdepth: 1 - - guesser_modules/init - guesser_modules/default_guesser - - -.. rubric:: Guesser core modules - -The remaining pages are primarily of interest to developers as they -contain functions and classes that are used in the implementation of -the context-specific guessers. - -.. toctree:: - :maxdepth: 1 - - guesser_modules/base - guesser_modules/tables +.. Contains the formatted docstrings from the guesser modules located in 'mdanalysis/package/MDAnalysis/guesser' + +.. _Guessers: + +************************** +Guesser modules +************************** +This module contains the context-aware guessers, which are used by the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API. Context-aware guessers' main purpose +is to be tailored guesser classes that target specific file format or force field (eg. PDB file format, or Martini forcefield). +Having such guessers makes attribute guessing more accurate and reliable than having generic guessing methods that don't fit all scenarios. + +Example uses of guessers +------------------------ + +Default behavior +~~~~~~~~~~~~~~~~ + +By default, MDAnalysis will guess the "mass" and "type" (atom type) attributes for all particles in the Universe +using the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` at the time of Universe creation, +if they are not read from the input file. If the required information is not present in the input file, +a warning will be raised. +Please see the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` for more information. + + + +Guessing using :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Guessing can be done through the Universe's :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` as following:: + + import MDAnalysis as mda + from MDAnalysisTests.datafiles import PDB + + u = mda.Universe(PDB) + print(hasattr(u.atoms, 'elements')) # returns False + u.guess_TopologyAttrs(to_guess=['elements']) + print(u.atoms.elements) # print ['N' 'H' 'H' ... 'NA' 'NA' 'NA'] + +In the above example, we passed ``elements`` as the attribute we want to guess +:meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` guess then add it as a topology +attribute to the ``AtomGroup`` of the universe. + +If the attribute already exists in the universe, passing the attribute of interest to the ``to_guess`` parameter will only fill the empty values of the attribute if any exists. +To override all the attribute values, you can pass the attribute to the ``force_guess`` parameter instead of ``to_guess`` as following:: + + import MDAnalysis as mda + from MDAnalysisTests.datafiles import PRM12 +  + u = mda.Universe(PRM12, context='default', to_guess=()) # types ['HW', 'OW', ..] + + u.guess_TopologyAttrs(force_guess=['types']) # types ['H', 'O', ..] + + +.. note:: + The default ``context`` will use the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` + + + + +.. rubric:: Available guessers +.. toctree:: + :maxdepth: 1 + + guesser_modules/init + guesser_modules/default_guesser + + +.. rubric:: Guesser core modules + +The remaining pages are primarily of interest to developers as they +contain functions and classes that are used in the implementation of +the context-specific guessers. + +.. toctree:: + :maxdepth: 1 + + guesser_modules/base + guesser_modules/tables diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules/base.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules/base.rst index cfba20f17be..80c7a4ef455 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules/base.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules/base.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.guesser.base +.. automodule:: MDAnalysis.guesser.base diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules/default_guesser.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules/default_guesser.rst index a3f3f897152..de8dd9e8bc5 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules/default_guesser.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules/default_guesser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.guesser.default_guesser +.. automodule:: MDAnalysis.guesser.default_guesser diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules/init.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules/init.rst index 6fa6449c5c3..5719bc7d0ec 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules/init.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules/init.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.guesser.__init__ +.. automodule:: MDAnalysis.guesser.__init__ diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules/tables.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules/tables.rst index 6116739fe89..a63f69d17b9 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules/tables.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules/tables.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.guesser.tables +.. automodule:: MDAnalysis.guesser.tables diff --git a/package/doc/sphinx/source/documentation_pages/lib/NeighborSearch.rst b/package/doc/sphinx/source/documentation_pages/lib/NeighborSearch.rst index 967e7a13cd9..96af4021cdb 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/NeighborSearch.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/NeighborSearch.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.NeighborSearch - :members: +.. automodule:: MDAnalysis.lib.NeighborSearch + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/c_distances.rst b/package/doc/sphinx/source/documentation_pages/lib/c_distances.rst index 962e1d9055a..c77857476ac 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/c_distances.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/c_distances.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.c_distances - :members: +.. automodule:: MDAnalysis.lib.c_distances + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/c_distances_openmp.rst b/package/doc/sphinx/source/documentation_pages/lib/c_distances_openmp.rst index d03ca6e6f7f..cfbc2b358f1 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/c_distances_openmp.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/c_distances_openmp.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.c_distances_openmp - :members: +.. automodule:: MDAnalysis.lib.c_distances_openmp + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/correlations.rst b/package/doc/sphinx/source/documentation_pages/lib/correlations.rst index e68b0eba864..2049a75a4b3 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/correlations.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/correlations.rst @@ -1,9 +1,9 @@ -.. automodule:: MDAnalysis.lib.correlations - - Autocorrelation Function - ------------------------ - .. autofunction:: MDAnalysis.lib.correlations.autocorrelation - - Intermittency Function - ---------------------- +.. automodule:: MDAnalysis.lib.correlations + + Autocorrelation Function + ------------------------ + .. autofunction:: MDAnalysis.lib.correlations.autocorrelation + + Intermittency Function + ---------------------- .. autofunction:: MDAnalysis.lib.correlations.correct_intermittency \ No newline at end of file diff --git a/package/doc/sphinx/source/documentation_pages/lib/distances.rst b/package/doc/sphinx/source/documentation_pages/lib/distances.rst index c50b85bd1c6..7ce499672fe 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/distances.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/distances.rst @@ -1,18 +1,18 @@ -.. automodule:: MDAnalysis.lib.distances - - - -Low-level modules for :mod:`MDAnalysis.lib.distances` -===================================================== - -:mod:`MDAnalysis.lib._distances` contains low level access to the -*serial* MDAnalysis Cython functions in `distances`. These have -little to no error checking done on inputs so should be used with -caution. Similarly, :mod:`MDAnalysis.lib._distances_openmp` contains -the OpenMP-enable functions. - -.. toctree:: - :maxdepth: 1 - - c_distances - c_distances_openmp +.. automodule:: MDAnalysis.lib.distances + + + +Low-level modules for :mod:`MDAnalysis.lib.distances` +===================================================== + +:mod:`MDAnalysis.lib._distances` contains low level access to the +*serial* MDAnalysis Cython functions in `distances`. These have +little to no error checking done on inputs so should be used with +caution. Similarly, :mod:`MDAnalysis.lib._distances_openmp` contains +the OpenMP-enable functions. + +.. toctree:: + :maxdepth: 1 + + c_distances + c_distances_openmp diff --git a/package/doc/sphinx/source/documentation_pages/lib/formats/libdcd.rst b/package/doc/sphinx/source/documentation_pages/lib/formats/libdcd.rst index aaf528c1d63..048024b46cd 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/formats/libdcd.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/formats/libdcd.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.lib.formats.libdcd - :members: - :inherited-members: +.. automodule:: MDAnalysis.lib.formats.libdcd + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/formats/libmdaxdr.rst b/package/doc/sphinx/source/documentation_pages/lib/formats/libmdaxdr.rst index f6cca2f9f4d..479f68f5417 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/formats/libmdaxdr.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/formats/libmdaxdr.rst @@ -1,3 +1,3 @@ -.. automodule:: MDAnalysis.lib.formats.libmdaxdr - :members: - :inherited-members: +.. automodule:: MDAnalysis.lib.formats.libmdaxdr + :members: + :inherited-members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/log.rst b/package/doc/sphinx/source/documentation_pages/lib/log.rst index 583e7cb4083..744f95cdb5c 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/log.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/log.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.log - :members: +.. automodule:: MDAnalysis.lib.log + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/mdamath.rst b/package/doc/sphinx/source/documentation_pages/lib/mdamath.rst index 22ef1f4fbee..3b6704512b4 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/mdamath.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/mdamath.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.lib.mdamath +.. automodule:: MDAnalysis.lib.mdamath diff --git a/package/doc/sphinx/source/documentation_pages/lib/nsgrid.rst b/package/doc/sphinx/source/documentation_pages/lib/nsgrid.rst index f36f2480b0b..8b508479254 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/nsgrid.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/nsgrid.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.nsgrid +.. automodule:: MDAnalysis.lib.nsgrid :members: \ No newline at end of file diff --git a/package/doc/sphinx/source/documentation_pages/lib/picklable_file_io.rst b/package/doc/sphinx/source/documentation_pages/lib/picklable_file_io.rst index 8df008afdde..2aa3b150bf3 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/picklable_file_io.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/picklable_file_io.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.lib.picklable_file_io +.. automodule:: MDAnalysis.lib.picklable_file_io diff --git a/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst b/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst index b9d710fdf34..0db65961296 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.pkdtree - :members: +.. automodule:: MDAnalysis.lib.pkdtree + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/qcprot.rst b/package/doc/sphinx/source/documentation_pages/lib/qcprot.rst index 0ecd59574fc..8f600b1dcb0 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/qcprot.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/qcprot.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.qcprot - +.. automodule:: MDAnalysis.lib.qcprot + diff --git a/package/doc/sphinx/source/documentation_pages/lib/transformations.rst b/package/doc/sphinx/source/documentation_pages/lib/transformations.rst index 5f45038ca60..f3653a318ca 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/transformations.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/transformations.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.transformations - :members: +.. automodule:: MDAnalysis.lib.transformations + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib/util.rst b/package/doc/sphinx/source/documentation_pages/lib/util.rst index 63db8ea453c..8db6a030735 100644 --- a/package/doc/sphinx/source/documentation_pages/lib/util.rst +++ b/package/doc/sphinx/source/documentation_pages/lib/util.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.lib.util - +.. automodule:: MDAnalysis.lib.util + diff --git a/package/doc/sphinx/source/documentation_pages/lib_modules.rst b/package/doc/sphinx/source/documentation_pages/lib_modules.rst index 4bc76c8fa10..939a4eb9519 100644 --- a/package/doc/sphinx/source/documentation_pages/lib_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/lib_modules.rst @@ -1,110 +1,110 @@ -.. _lib: - -******************************************* -Library functions --- :mod:`MDAnalysis.lib` -******************************************* - -.. module:: MDAnalysis.lib - :synopsis: ``lib`` collects independent code for re-use in MDAnalysis - -:mod:`MDAnalysis.lib` contains code that is independent of the -specific MDAnalysis framework, such as fast calculators for distances -or simple logging support. Modules do not depend on other code inside -MDAnalysis except in :mod:`MDAnalysis.lib` itself (and possibly in -:mod:`MDAnalysis.exceptions`) and thus can be easily imported -elsewhere. - -Overview --------- - -:mod:`MDAnalysis.lib.distances` contains many high performance maths -functions. Most of them have the keyword *backend* that allows one to -either select serial (single threaded) code (``backend="serial``) or -to use parallelized versions (e.g. ``backend="OpenMP"`` for OpenMP -parallelism). - -:mod:`MDAnalysis.lib.transformations` contains a multitude of -matrix operations for manipulating coordinate data. - -:mod:`MDAnalysis.lib.qcprot` contains a fast implementation of -superposition by minimizing the RMSD. - -:mod:`MDAnalysis.lib.util` contains various file and string utility -functions whereas mathematical functions are to be found in -:mod:`MDAnalysis.lib.mdamath`. - -A number of modules are concerned with finding -neighbors. :mod:`MDAnalysis.lib.NeighborSearch` contains high-level -classes to do neighbor searches with MDAnalysis -objects. :mod:`MDAnalysis.lib.nsgrid` contains a fast implementation -of grid neighbor search whereas :mod:`MDAnalysis.lib.pkdtree` uses -KDTrees (with periodic images) for neighbor searching. Some of the -functions in :mod:`MDAnalysis.lib.distances` user either of these -algorithms to speed up distance calculations. - - - -List of modules ---------------- - -.. toctree:: - :maxdepth: 1 - - ./lib/distances - ./lib/NeighborSearch - ./lib/nsgrid - ./lib/pkdtree - ./lib/log - ./lib/mdamath - ./lib/transformations - ./lib/qcprot - ./lib/util - ./lib/correlations - ./lib/picklable_file_io - -Low level file formats ----------------------- - -The modules in :mod:`MDAnalysis.lib.formats` contain code to access various file -formats in a way that is *independent from other MDAnalysis functionality* -(i.e., they do not use any classes from :mod:`MDAnalysis.core` or -:mod:`MDAnalysis.topology`). This low-level code is used in the -:mod:`MDAnalysis.coordinates` module but can also be re-used by other -Python-based projects. - -.. toctree:: - :maxdepth: 1 - - ./lib/formats/libmdaxdr - ./lib/formats/libdcd - -Libmdanalysis -------------- - -The :file:`__init__.pxd` file in :mod:`MDAnalysis.lib.libmdanalysis` provides a -single place to ``cimport`` MDAnalysis' public Cython headers. This is recommended -for advanced developers only. - -For example, imagine we are writing a Cython extension module in -:mod:`MDAnalysis.lib` and we would like to make a function that creates a -:class:`MDAnalysis.coordinates.timestep.Timestep` - -.. code-block:: cython - - from MDAnalysis.lib.libmdanalysis cimport timestep - # or we could use the relative cimport - # from .libmdanalysis cimport timestep - - cdef timestep.Timestep make_timestep(int natoms): - cdef timestep.Timestep ts = timestep.Timestep(natoms) - return ts - - -Currently modules that are exposed as public Cython headers are: - -- :mod:`MDAnalysis.coordinates.timestep` -- :mod:`MDAnalysis.lib.formats.libmdaxdr` -- :mod:`MDAnalysis.lib.formats.libdcd` -- :mod:`MDAnalysis.lib.c_distances` - +.. _lib: + +******************************************* +Library functions --- :mod:`MDAnalysis.lib` +******************************************* + +.. module:: MDAnalysis.lib + :synopsis: ``lib`` collects independent code for re-use in MDAnalysis + +:mod:`MDAnalysis.lib` contains code that is independent of the +specific MDAnalysis framework, such as fast calculators for distances +or simple logging support. Modules do not depend on other code inside +MDAnalysis except in :mod:`MDAnalysis.lib` itself (and possibly in +:mod:`MDAnalysis.exceptions`) and thus can be easily imported +elsewhere. + +Overview +-------- + +:mod:`MDAnalysis.lib.distances` contains many high performance maths +functions. Most of them have the keyword *backend* that allows one to +either select serial (single threaded) code (``backend="serial``) or +to use parallelized versions (e.g. ``backend="OpenMP"`` for OpenMP +parallelism). + +:mod:`MDAnalysis.lib.transformations` contains a multitude of +matrix operations for manipulating coordinate data. + +:mod:`MDAnalysis.lib.qcprot` contains a fast implementation of +superposition by minimizing the RMSD. + +:mod:`MDAnalysis.lib.util` contains various file and string utility +functions whereas mathematical functions are to be found in +:mod:`MDAnalysis.lib.mdamath`. + +A number of modules are concerned with finding +neighbors. :mod:`MDAnalysis.lib.NeighborSearch` contains high-level +classes to do neighbor searches with MDAnalysis +objects. :mod:`MDAnalysis.lib.nsgrid` contains a fast implementation +of grid neighbor search whereas :mod:`MDAnalysis.lib.pkdtree` uses +KDTrees (with periodic images) for neighbor searching. Some of the +functions in :mod:`MDAnalysis.lib.distances` user either of these +algorithms to speed up distance calculations. + + + +List of modules +--------------- + +.. toctree:: + :maxdepth: 1 + + ./lib/distances + ./lib/NeighborSearch + ./lib/nsgrid + ./lib/pkdtree + ./lib/log + ./lib/mdamath + ./lib/transformations + ./lib/qcprot + ./lib/util + ./lib/correlations + ./lib/picklable_file_io + +Low level file formats +---------------------- + +The modules in :mod:`MDAnalysis.lib.formats` contain code to access various file +formats in a way that is *independent from other MDAnalysis functionality* +(i.e., they do not use any classes from :mod:`MDAnalysis.core` or +:mod:`MDAnalysis.topology`). This low-level code is used in the +:mod:`MDAnalysis.coordinates` module but can also be re-used by other +Python-based projects. + +.. toctree:: + :maxdepth: 1 + + ./lib/formats/libmdaxdr + ./lib/formats/libdcd + +Libmdanalysis +------------- + +The :file:`__init__.pxd` file in :mod:`MDAnalysis.lib.libmdanalysis` provides a +single place to ``cimport`` MDAnalysis' public Cython headers. This is recommended +for advanced developers only. + +For example, imagine we are writing a Cython extension module in +:mod:`MDAnalysis.lib` and we would like to make a function that creates a +:class:`MDAnalysis.coordinates.timestep.Timestep` + +.. code-block:: cython + + from MDAnalysis.lib.libmdanalysis cimport timestep + # or we could use the relative cimport + # from .libmdanalysis cimport timestep + + cdef timestep.Timestep make_timestep(int natoms): + cdef timestep.Timestep ts = timestep.Timestep(natoms) + return ts + + +Currently modules that are exposed as public Cython headers are: + +- :mod:`MDAnalysis.coordinates.timestep` +- :mod:`MDAnalysis.lib.formats.libmdaxdr` +- :mod:`MDAnalysis.lib.formats.libdcd` +- :mod:`MDAnalysis.lib.c_distances` + For more details consult the source :mod:`MDAnalysis.lib.libmdanalysis.__init__.pxd` \ No newline at end of file diff --git a/package/doc/sphinx/source/documentation_pages/overview.rst b/package/doc/sphinx/source/documentation_pages/overview.rst index 23cb5433f94..211fed7c755 100644 --- a/package/doc/sphinx/source/documentation_pages/overview.rst +++ b/package/doc/sphinx/source/documentation_pages/overview.rst @@ -1,48 +1,48 @@ -.. _overview-label: - -========================== - Overview of MDAnalysis -========================== - -MDAnalysis is a Python package for the analysis of molecular dynamics simulations. -It provides an object-oriented interface to molecular structures and trajectories, -with direct access to atomic coordinates as :class:`numpy.ndarray` objects for seamless -integration with `NumPy`_ and `SciPy`_. - -This page gives a high-level overview of the most important public classes and modules. -For usage examples and tutorials, refer to the `User Guide`_. - -.. _User Guide: https://userguide.mdanalysis.org/stable/index.html -.. _NumPy: https://numpy.org/ -.. _SciPy: https://scipy.org/ - -Key Classes -=========== - -The core of MDAnalysis revolves around the :class:`~MDAnalysis.core.universe.Universe` class, -which serves as the central data structure that loads and connects topology and coordinate data. -From a :class:`~MDAnalysis.core.universe.Universe`, users typically interact with :class:`~MDAnalysis.core.groups.AtomGroup` -objects — flexible collections of atoms that support structural selections and analysis operations. These selections -are created using `CHARMM-style`_ selection syntax via the :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method, -allowing users to query atoms based on names, residue numbers, segments, and more. - -Individual atoms are represented by the :class:`~MDAnalysis.core.groups.Atom` class, while residues and segments (or chains) are modeled using the -:class:`~MDAnalysis.core.groups.Residue` and :class:`~MDAnalysis.core.groups.Segment` classes, respectively. Together, these -classes form an intuitive, object-oriented hierarchy that makes it easy to navigate and analyze molecular systems. - -.. _CHARMM-style: http://www.charmm.org/documentation/c37b1/select.html - -Core modules -============ - -MDAnalysis is organized into several core modules that provide specialized functionality for -handling and analyzing molecular dynamics data. The :mod:`MDAnalysis.core` module defines the -essential data structures such as :class:`~MDAnalysis.core.universe.Universe`, :class:`~MDAnalysis.core.groups.AtomGroup`, -and related objects. The :mod:`MDAnalysis.analysis` module contains a collection of analysis tools for tasks like RMSD calculation, -diffusion analysis, contact maps, and more. The :mod:`MDAnalysis.selections` module implements the flexible selection language used -to query atoms based on structural properties. Finally, :mod:`MDAnalysis.topology` manages topology parsing and representation, -supporting a wide range of file formats for loading molecular structures. - - - - +.. _overview-label: + +========================== + Overview of MDAnalysis +========================== + +MDAnalysis is a Python package for the analysis of molecular dynamics simulations. +It provides an object-oriented interface to molecular structures and trajectories, +with direct access to atomic coordinates as :class:`numpy.ndarray` objects for seamless +integration with `NumPy`_ and `SciPy`_. + +This page gives a high-level overview of the most important public classes and modules. +For usage examples and tutorials, refer to the `User Guide`_. + +.. _User Guide: https://userguide.mdanalysis.org/stable/index.html +.. _NumPy: https://numpy.org/ +.. _SciPy: https://scipy.org/ + +Key Classes +=========== + +The core of MDAnalysis revolves around the :class:`~MDAnalysis.core.universe.Universe` class, +which serves as the central data structure that loads and connects topology and coordinate data. +From a :class:`~MDAnalysis.core.universe.Universe`, users typically interact with :class:`~MDAnalysis.core.groups.AtomGroup` +objects — flexible collections of atoms that support structural selections and analysis operations. These selections +are created using `CHARMM-style`_ selection syntax via the :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method, +allowing users to query atoms based on names, residue numbers, segments, and more. + +Individual atoms are represented by the :class:`~MDAnalysis.core.groups.Atom` class, while residues and segments (or chains) are modeled using the +:class:`~MDAnalysis.core.groups.Residue` and :class:`~MDAnalysis.core.groups.Segment` classes, respectively. Together, these +classes form an intuitive, object-oriented hierarchy that makes it easy to navigate and analyze molecular systems. + +.. _CHARMM-style: http://www.charmm.org/documentation/c37b1/select.html + +Core modules +============ + +MDAnalysis is organized into several core modules that provide specialized functionality for +handling and analyzing molecular dynamics data. The :mod:`MDAnalysis.core` module defines the +essential data structures such as :class:`~MDAnalysis.core.universe.Universe`, :class:`~MDAnalysis.core.groups.AtomGroup`, +and related objects. The :mod:`MDAnalysis.analysis` module contains a collection of analysis tools for tasks like RMSD calculation, +diffusion analysis, contact maps, and more. The :mod:`MDAnalysis.selections` module implements the flexible selection language used +to query atoms based on structural properties. Finally, :mod:`MDAnalysis.topology` manages topology parsing and representation, +supporting a wide range of file formats for loading molecular structures. + + + + diff --git a/package/doc/sphinx/source/documentation_pages/references.rst b/package/doc/sphinx/source/documentation_pages/references.rst index 284d5a63b78..77fdb6205dd 100644 --- a/package/doc/sphinx/source/documentation_pages/references.rst +++ b/package/doc/sphinx/source/documentation_pages/references.rst @@ -1,287 +1,287 @@ -.. -*- coding: utf-8 -*- -.. note: make sure that no lines accidentally start with a single character -.. followed by a period: reST interprets it as an enumerated list and -.. messes up the formatting - -.. The references are accessible globally; you can cite these papers anywhere -.. in the docs. - -.. _references: - -************ - References -************ - -MDAnalysis and the included algorithms are scientific software that -are described in academic publications. **Please cite these papers when you use -MDAnalysis in published work.** - -It is possible to :ref:`automatically generate a list of references -` for any program that uses -MDAnalysis. This list (in common reference manager formats) contains -the citations associated with the specific algorithms and libraries -that were used in the program. - - -Citations for the whole MDAnalysis library -========================================== - -When using MDAnalysis in published work, please cite -[Michaud-Agrawal2011]_ and [Gowers2016]_. - -(We are currently asking you to cite *both* papers if at all possible -because the 2016 paper describes many updates to the original 2011 -paper and neither paper on its own provides a comprehensive -description of the library. We will publish a complete self-contained -paper with the upcoming 1.0 release of MDAnalysis, which will then -supersede these two citations.) - - -.. [Michaud-Agrawal2011] N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, - and O. Beckstein. MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics - Simulations. *J. Comput. Chem.* **32** (2011), - 2319–2327. doi:`10.1002/jcc.21787`_ - -.. [Gowers2016] R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. - Melo, S. L. Seyler, D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, - and O. Beckstein. `MDAnalysis: A Python package for the rapid analysis of - molecular dynamics simulations`_. In S. Benthall and S. Rostrup, editors, - *Proceedings of the 15th Python in Science Conference*, pages 98-105, - Austin, TX, 2016. SciPy. doi:`10.25080/Majora-629e541a-00e`_ - -.. _`10.1002/jcc.21787`: http://dx.doi.org/10.1002/jcc.21787 -.. _`10.25080/Majora-629e541a-00e`: - https://doi.org/10.25080/Majora-629e541a-00e - -.. _`MDAnalysis: A Python package for the rapid analysis of molecular - dynamics simulations`: - http://conference.scipy.org/proceedings/scipy2016/oliver_beckstein.html - - -.. _references-components: - -Citations for included algorithms and modules -============================================= - -If you use the RMSD calculation (:mod:`MDAnalysis.analysis.rms`) or alignment -code (:mod:`MDAnalysis.analysis.align`) that uses the -:mod:`~MDAnalysis.core.qcprot` module please also cite [Theobald2005b]_ and -[Liu2010b]_. - -.. [Theobald2005b] Douglas L. Theobald. Rapid calculation of RMSD using a - quaternion-based characteristic polynomial. *Acta Crystallographica A* - **61** (2005), 478-480. - -.. [Liu2010b] Pu Liu, Dmitris K. Agrafiotis, and Douglas L. Theobald. Fast - determination of the optimal rotational matrix for macromolecular - superpositions. *J. Comput. Chem.* **31** (2010), 1561–1563. - -If you use the helix analysis algorithm HELANAL_ in -:mod:`MDAnalysis.analysis.helanal` please cite [Bansal2000b]_. - -.. [Bansal2000b] Bansal M, Kumar S, Velavan R. HELANAL — A program to - characterise helix geometry in proteins. *J. Biomol. Struct. Dyn.* **17** - (2000), 811–819 - -.. _HELANAL: http://www.ccrnp.ncifcrf.gov/users/kumarsan/HELANAL/helanal.html - -If you use the GNM trajectory analysis code in -:mod:`MDAnalysis.analysis.gnm` please cite [Hall2007b]_. - -.. [Hall2007b] Benjamin A. Hall, Samantha L. Kaye, Andy Pang, Rafael Perera, and - Philip C. Biggin. Characterization of Protein Conformational States by - Normal-Mode Frequencies. *JACS* **129** (2007), 11394–11401. - -If you use the water analysis code in -:mod:`MDAnalysis.analysis.waterdynamics` please cite [Araya-Secchi2014b]_. - -.. [Araya-Secchi2014b] R. Araya-Secchi., Tomas Perez-Acle, Seung-gu Kang, Tien - Huynh, Alejandro Bernardin, Yerko Escalona, Jose-Antonio Garate, - Agustin D. Martinez, Isaac E. Garcia, Juan C. Saez, Ruhong - Zhou. Characterization of a novel water pocket inside the human Cx26 - hemichannel structure. *Biophysical Journal*, **107** (2014), 599-612. - -If you use the Path Similarity Analysis (PSA) code in -:mod:`MDAnalysis.analysis.psa` please cite [Seyler2015b]_. - -.. [Seyler2015b] Seyler SL, Kumar A, Thorpe MF, Beckstein O. Path Similarity - Analysis: A Method for Quantifying Macromolecular Pathways. *PLoS - Comput Biol* **11** (2015), e1004568. doi: `10.1371/journal.pcbi.1004568`_ - -.. _`10.1371/journal.pcbi.1004568`: http://doi.org/10.1371/journal.pcbi.1004568 - -If you use the implementation of the ENCORE ensemble analysis in -:mod:`MDAnalysis.analysis.encore` please cite [Tiberti2015b]_. - -.. [Tiberti2015b] M. Tiberti, E. Papaleo, T. Bengtsen, W. Boomsma, - and K. Lindorff-Larsen. ENCORE: Software for quantitative ensemble - comparison. *PLoS Comput Biol*, **11** (2015), e1004415. doi: - `10.1371/journal.pcbi.1004415`_ - -.. _`10.1371/journal.pcbi.1004415`: http://doi.org/10.1371/journal.pcbi.1004415 - -If you use the streamline visualization in -:mod:`MDAnalysis.visualization.streamlines` and -:mod:`MDAnalysis.visualization.streamlines_3D` please cite [Chavent2014b]_. - -.. [Chavent2014b] Chavent, M., Reddy, T., Dahl, C.E., Goose, J., Jobard, B., - and Sansom, M.S.P. Methodologies for the analysis of instantaneous lipid - diffusion in MD simulations of large membrane systems. *Faraday - Discussions* **169** (2014), 455–475. doi: `10.1039/c3fd00145h`_ - -.. _`10.1039/c3fd00145h`: https://doi.org/10.1039/c3fd00145h - -If you use the hydrogen bond analysis code in -:mod:`MDAnalysis.analysis.hydrogenbonds.hbond_analysis` please cite [Smith2019]_. - -.. [Smith2019] P. Smith, R. M. Ziolek, E. Gazzarrini, D. M. Owen, and C. D. Lorenz. - On the interaction of hyaluronic acid with synovial fluid lipid membranes. *PCCP* - **21** (2019), 9845-9857. doi: `10.1039/C9CP01532A`_ - -.. _`10.1039/C9CP01532A`: http://dx.doi.org/10.1039/C9CP01532A - -If you use :meth:`~MDAnalysis.analysis.pca.PCA.rmsip` or -:func:`~MDAnalysis.analysis.pca.rmsip` please cite [Amadei1999]_ and -[Leo-Macias2004]_ . - -.. [Amadei1999] Amadei, A., Ceruso, M. A. & Nola, A. D. - On the convergence of the conformational coordinates basis set obtained by the essential dynamics analysis of proteins’ molecular dynamics simulations. - *Proteins: Structure, Function, and Bioinformatics* **36**, 419–424 (1999). - doi: `10.1002/(SICI)1097-0134(19990901)36:4<419::AID-PROT5>3.0.CO;2-U`_ - -.. _`10.1002/(SICI)1097-0134(19990901)36:4<419::AID-PROT5>3.0.CO;2-U`: https://doi.org/10.1002/(SICI)1097-0134(19990901)36:4%3C419::AID-PROT5%3E3.0.CO;2-U - -.. [Leo-Macias2004] Leo-Macias, A., Lopez-Romero, P., Lupyan, D., Zerbino, D. & Ortiz, A. R. - An Analysis of Core Deformations in Protein Superfamilies. - *Biophys J* **88**, 1291–1299 (2005). doi: `10.1529/biophysj.104.052449`_ - -.. _`10.1529/biophysj.104.052449`: https://dx.doi.org/10.1529%2Fbiophysj.104.052449 - -If you use :meth:`~MDAnalysis.analysis.pca.PCA.cumulative_overlap` or -:func:`~MDAnalysis.analysis.pca.cumulative_overlap` please cite [Yang2008]_ . - -.. [Yang2008] Yang, L., Song, G., Carriquiry, A. & Jernigan, R. L. - Close Correspondence between the Motions from Principal Component Analysis of Multiple HIV-1 Protease Structures and Elastic Network Modes. - *Structure* **16**, 321–330 (2008). doi: `10.1016/j.str.2007.12.011`_ - -.. _`10.1016/j.str.2007.12.011`: https://dx.doi.org/10.1016/j.str.2007.12.011 - -If you use the Mean Squared Displacement analysis code in -:mod:`MDAnalysis.analysis.msd` please cite [Calandri2011]_ and [Buyl2018]_. - -.. [Calandri2011] Calandrini, V., Pellegrini, E., Calligari, P., Hinsen, K., Kneller, G. R. - NMoldyn-Interfacing Spectroscopic Experiments, Molecular Dynamics Simulations and Models for Time Correlation Functions. - *Collect. SFN*, **12**, 201–232 (2011). doi: `10.1051/sfn/201112010`_ - -.. _`10.1051/sfn/201112010`: https://doi.org/10.1051/sfn/201112010 - -.. [Buyl2018] Buyl, P. tidynamics: A tiny package to compute the dynamics of stochastic and molecular simulations. Journal of Open Source Software, - 3(28), 877 (2018). doi: `10.21105/joss.00877`_ - -.. _`10.21105/joss.00877`: https://doi.org/10.21105/joss.00877 - -If you calculate shape parameters using -:meth:`~MDAnalysis.core.group.AtomGroup.shape_parameter`, -:meth:`~MDAnalysis.core.group.ResidueGroup.shape_parameter`, -:meth:`~MDAnalysis.core.group.SegmentGroup.shape_parameter` -please cite [Dima2004a]_. - -.. [Dima2004a] Dima, R. I., & Thirumalai, D. (2004). Asymmetry - in the shapes of folded and denatured states of - proteins. *J Phys Chem B*, 108(21), - 6564-6570. doi:`10.1021/jp037128y - `_ - -If you calculate asphericities using -:meth:`~MDAnalysis.core.group.AtomGroup.asphericity`, -:meth:`~MDAnalysis.core.group.ResidueGroup.asphericity`, -:meth:`~MDAnalysis.core.group.SegmentGroup.asphericity` -please cite [Dima2004b]_. - -.. [Dima2004b] Dima, R. I., & Thirumalai, D. (2004). Asymmetry - in the shapes of folded and denatured states of - proteins. *J Phys Chem B*, 108(21), - 6564-6570. doi:`10.1021/jp037128y - `_ - -If you use use the dielectric analysis code in -:class:`~MDAnalysis.analysis.dielectric.DielectricConstant` please cite [Neumann1983]_. - -.. [Neumann1983] Neumann, M. (1983). Dipole - Moment Fluctuation Formulas in Computer Simulations of Polar Systems. - *Molecular Physics* **50**, no. 4, 841–858. doi: `10.1080/00268978300102721`_ - -.. _`10.1080/00268978300102721`: http://doi.org/10.1080/00268978300102721 - -If you use H5MD files using -:mod:`MDAnalysis.coordinates.H5MD.py`, please cite [Buyl2013]_ and -[Jakupovic2021]_. - -.. [Buyl2013] Buyl P., Colberg P., and Höfling F.(2013). - H5MD: A structured, efficient, and portable file format for molecular data. - *Computer Physics Communications*, 185. doi:`10.1016/j.cpc.2014.01.018. - `_ - -.. [Jakupovic2021] Jakupovic E. and Beckstein O., MPI-parallel Molecular - Dynamics Trajectory Analysis with the H5MD Format in the MDAnalysis - Python Package, in *Proceedings of the 20th Python in Science Conference*, - (Meghann Agarwal, Chris Calloway, Dillon Niederhut, and David Shupe, eds.), - pp. 18 – 26, 2021. doi:`10.25080/majora-1b6fd038-005. - `_ - -.. comment:: - - If you use IMD capability with :mod:`MDAnalysis.coordinates.IMD.py`, please cite [IMDv3paper]_. - - .. [IMDv3paper] Authors (YEAR). - IMDv3 Manuscript Title. - *Journal*, 185. doi:`insert-doi-here `_ - -.. todo:: Fill in the final IMDv3 citation once the paper is published. - See https://github.com/MDAnalysis/mdanalysis/issues/5094 - -.. _citations-using-duecredit: - - -Citations using Duecredit -========================= - -Citations can be automatically generated using duecredit_, depending on the -packages used. Duecredit is easy to install via ``pip``. Simply type: - -.. code-block:: bash - - pip install duecredit - -duecredit_ will remain an optional dependency, i.e. any code using -MDAnalysis will work correctly even without duecredit installed. - -A list of citations for ``yourscript.py`` can be obtained using simple -commands. - -.. code-block:: bash - - cd /path/to/yourmodule - python -m duecredit yourscript.py - -or set the environment variable :envvar:`DUECREDIT_ENABLE` - -.. code-block:: bash - - DUECREDIT_ENABLE=yes python yourscript.py - -Once the citations have been extracted (to a hidden file in the -current directory), you can use the :program:`duecredit` program to -export them to different formats. For example, one can display them in -BibTeX format, using: - -.. code-block:: bash - - duecredit summary --format=bibtex - - -**Please cite your use of MDAnalysis and the packages and algorithms -that it uses. Thanks!** - - -.. _duecredit: https://github.com/duecredit/duecredit +.. -*- coding: utf-8 -*- +.. note: make sure that no lines accidentally start with a single character +.. followed by a period: reST interprets it as an enumerated list and +.. messes up the formatting + +.. The references are accessible globally; you can cite these papers anywhere +.. in the docs. + +.. _references: + +************ + References +************ + +MDAnalysis and the included algorithms are scientific software that +are described in academic publications. **Please cite these papers when you use +MDAnalysis in published work.** + +It is possible to :ref:`automatically generate a list of references +` for any program that uses +MDAnalysis. This list (in common reference manager formats) contains +the citations associated with the specific algorithms and libraries +that were used in the program. + + +Citations for the whole MDAnalysis library +========================================== + +When using MDAnalysis in published work, please cite +[Michaud-Agrawal2011]_ and [Gowers2016]_. + +(We are currently asking you to cite *both* papers if at all possible +because the 2016 paper describes many updates to the original 2011 +paper and neither paper on its own provides a comprehensive +description of the library. We will publish a complete self-contained +paper with the upcoming 1.0 release of MDAnalysis, which will then +supersede these two citations.) + + +.. [Michaud-Agrawal2011] N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, + and O. Beckstein. MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics + Simulations. *J. Comput. Chem.* **32** (2011), + 2319–2327. doi:`10.1002/jcc.21787`_ + +.. [Gowers2016] R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. + Melo, S. L. Seyler, D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, + and O. Beckstein. `MDAnalysis: A Python package for the rapid analysis of + molecular dynamics simulations`_. In S. Benthall and S. Rostrup, editors, + *Proceedings of the 15th Python in Science Conference*, pages 98-105, + Austin, TX, 2016. SciPy. doi:`10.25080/Majora-629e541a-00e`_ + +.. _`10.1002/jcc.21787`: http://dx.doi.org/10.1002/jcc.21787 +.. _`10.25080/Majora-629e541a-00e`: + https://doi.org/10.25080/Majora-629e541a-00e + +.. _`MDAnalysis: A Python package for the rapid analysis of molecular + dynamics simulations`: + http://conference.scipy.org/proceedings/scipy2016/oliver_beckstein.html + + +.. _references-components: + +Citations for included algorithms and modules +============================================= + +If you use the RMSD calculation (:mod:`MDAnalysis.analysis.rms`) or alignment +code (:mod:`MDAnalysis.analysis.align`) that uses the +:mod:`~MDAnalysis.core.qcprot` module please also cite [Theobald2005b]_ and +[Liu2010b]_. + +.. [Theobald2005b] Douglas L. Theobald. Rapid calculation of RMSD using a + quaternion-based characteristic polynomial. *Acta Crystallographica A* + **61** (2005), 478-480. + +.. [Liu2010b] Pu Liu, Dmitris K. Agrafiotis, and Douglas L. Theobald. Fast + determination of the optimal rotational matrix for macromolecular + superpositions. *J. Comput. Chem.* **31** (2010), 1561–1563. + +If you use the helix analysis algorithm HELANAL_ in +:mod:`MDAnalysis.analysis.helanal` please cite [Bansal2000b]_. + +.. [Bansal2000b] Bansal M, Kumar S, Velavan R. HELANAL — A program to + characterise helix geometry in proteins. *J. Biomol. Struct. Dyn.* **17** + (2000), 811–819 + +.. _HELANAL: http://www.ccrnp.ncifcrf.gov/users/kumarsan/HELANAL/helanal.html + +If you use the GNM trajectory analysis code in +:mod:`MDAnalysis.analysis.gnm` please cite [Hall2007b]_. + +.. [Hall2007b] Benjamin A. Hall, Samantha L. Kaye, Andy Pang, Rafael Perera, and + Philip C. Biggin. Characterization of Protein Conformational States by + Normal-Mode Frequencies. *JACS* **129** (2007), 11394–11401. + +If you use the water analysis code in +:mod:`MDAnalysis.analysis.waterdynamics` please cite [Araya-Secchi2014b]_. + +.. [Araya-Secchi2014b] R. Araya-Secchi., Tomas Perez-Acle, Seung-gu Kang, Tien + Huynh, Alejandro Bernardin, Yerko Escalona, Jose-Antonio Garate, + Agustin D. Martinez, Isaac E. Garcia, Juan C. Saez, Ruhong + Zhou. Characterization of a novel water pocket inside the human Cx26 + hemichannel structure. *Biophysical Journal*, **107** (2014), 599-612. + +If you use the Path Similarity Analysis (PSA) code in +:mod:`MDAnalysis.analysis.psa` please cite [Seyler2015b]_. + +.. [Seyler2015b] Seyler SL, Kumar A, Thorpe MF, Beckstein O. Path Similarity + Analysis: A Method for Quantifying Macromolecular Pathways. *PLoS + Comput Biol* **11** (2015), e1004568. doi: `10.1371/journal.pcbi.1004568`_ + +.. _`10.1371/journal.pcbi.1004568`: http://doi.org/10.1371/journal.pcbi.1004568 + +If you use the implementation of the ENCORE ensemble analysis in +:mod:`MDAnalysis.analysis.encore` please cite [Tiberti2015b]_. + +.. [Tiberti2015b] M. Tiberti, E. Papaleo, T. Bengtsen, W. Boomsma, + and K. Lindorff-Larsen. ENCORE: Software for quantitative ensemble + comparison. *PLoS Comput Biol*, **11** (2015), e1004415. doi: + `10.1371/journal.pcbi.1004415`_ + +.. _`10.1371/journal.pcbi.1004415`: http://doi.org/10.1371/journal.pcbi.1004415 + +If you use the streamline visualization in +:mod:`MDAnalysis.visualization.streamlines` and +:mod:`MDAnalysis.visualization.streamlines_3D` please cite [Chavent2014b]_. + +.. [Chavent2014b] Chavent, M., Reddy, T., Dahl, C.E., Goose, J., Jobard, B., + and Sansom, M.S.P. Methodologies for the analysis of instantaneous lipid + diffusion in MD simulations of large membrane systems. *Faraday + Discussions* **169** (2014), 455–475. doi: `10.1039/c3fd00145h`_ + +.. _`10.1039/c3fd00145h`: https://doi.org/10.1039/c3fd00145h + +If you use the hydrogen bond analysis code in +:mod:`MDAnalysis.analysis.hydrogenbonds.hbond_analysis` please cite [Smith2019]_. + +.. [Smith2019] P. Smith, R. M. Ziolek, E. Gazzarrini, D. M. Owen, and C. D. Lorenz. + On the interaction of hyaluronic acid with synovial fluid lipid membranes. *PCCP* + **21** (2019), 9845-9857. doi: `10.1039/C9CP01532A`_ + +.. _`10.1039/C9CP01532A`: http://dx.doi.org/10.1039/C9CP01532A + +If you use :meth:`~MDAnalysis.analysis.pca.PCA.rmsip` or +:func:`~MDAnalysis.analysis.pca.rmsip` please cite [Amadei1999]_ and +[Leo-Macias2004]_ . + +.. [Amadei1999] Amadei, A., Ceruso, M. A. & Nola, A. D. + On the convergence of the conformational coordinates basis set obtained by the essential dynamics analysis of proteins’ molecular dynamics simulations. + *Proteins: Structure, Function, and Bioinformatics* **36**, 419–424 (1999). + doi: `10.1002/(SICI)1097-0134(19990901)36:4<419::AID-PROT5>3.0.CO;2-U`_ + +.. _`10.1002/(SICI)1097-0134(19990901)36:4<419::AID-PROT5>3.0.CO;2-U`: https://doi.org/10.1002/(SICI)1097-0134(19990901)36:4%3C419::AID-PROT5%3E3.0.CO;2-U + +.. [Leo-Macias2004] Leo-Macias, A., Lopez-Romero, P., Lupyan, D., Zerbino, D. & Ortiz, A. R. + An Analysis of Core Deformations in Protein Superfamilies. + *Biophys J* **88**, 1291–1299 (2005). doi: `10.1529/biophysj.104.052449`_ + +.. _`10.1529/biophysj.104.052449`: https://dx.doi.org/10.1529%2Fbiophysj.104.052449 + +If you use :meth:`~MDAnalysis.analysis.pca.PCA.cumulative_overlap` or +:func:`~MDAnalysis.analysis.pca.cumulative_overlap` please cite [Yang2008]_ . + +.. [Yang2008] Yang, L., Song, G., Carriquiry, A. & Jernigan, R. L. + Close Correspondence between the Motions from Principal Component Analysis of Multiple HIV-1 Protease Structures and Elastic Network Modes. + *Structure* **16**, 321–330 (2008). doi: `10.1016/j.str.2007.12.011`_ + +.. _`10.1016/j.str.2007.12.011`: https://dx.doi.org/10.1016/j.str.2007.12.011 + +If you use the Mean Squared Displacement analysis code in +:mod:`MDAnalysis.analysis.msd` please cite [Calandri2011]_ and [Buyl2018]_. + +.. [Calandri2011] Calandrini, V., Pellegrini, E., Calligari, P., Hinsen, K., Kneller, G. R. + NMoldyn-Interfacing Spectroscopic Experiments, Molecular Dynamics Simulations and Models for Time Correlation Functions. + *Collect. SFN*, **12**, 201–232 (2011). doi: `10.1051/sfn/201112010`_ + +.. _`10.1051/sfn/201112010`: https://doi.org/10.1051/sfn/201112010 + +.. [Buyl2018] Buyl, P. tidynamics: A tiny package to compute the dynamics of stochastic and molecular simulations. Journal of Open Source Software, + 3(28), 877 (2018). doi: `10.21105/joss.00877`_ + +.. _`10.21105/joss.00877`: https://doi.org/10.21105/joss.00877 + +If you calculate shape parameters using +:meth:`~MDAnalysis.core.group.AtomGroup.shape_parameter`, +:meth:`~MDAnalysis.core.group.ResidueGroup.shape_parameter`, +:meth:`~MDAnalysis.core.group.SegmentGroup.shape_parameter` +please cite [Dima2004a]_. + +.. [Dima2004a] Dima, R. I., & Thirumalai, D. (2004). Asymmetry + in the shapes of folded and denatured states of + proteins. *J Phys Chem B*, 108(21), + 6564-6570. doi:`10.1021/jp037128y + `_ + +If you calculate asphericities using +:meth:`~MDAnalysis.core.group.AtomGroup.asphericity`, +:meth:`~MDAnalysis.core.group.ResidueGroup.asphericity`, +:meth:`~MDAnalysis.core.group.SegmentGroup.asphericity` +please cite [Dima2004b]_. + +.. [Dima2004b] Dima, R. I., & Thirumalai, D. (2004). Asymmetry + in the shapes of folded and denatured states of + proteins. *J Phys Chem B*, 108(21), + 6564-6570. doi:`10.1021/jp037128y + `_ + +If you use use the dielectric analysis code in +:class:`~MDAnalysis.analysis.dielectric.DielectricConstant` please cite [Neumann1983]_. + +.. [Neumann1983] Neumann, M. (1983). Dipole + Moment Fluctuation Formulas in Computer Simulations of Polar Systems. + *Molecular Physics* **50**, no. 4, 841–858. doi: `10.1080/00268978300102721`_ + +.. _`10.1080/00268978300102721`: http://doi.org/10.1080/00268978300102721 + +If you use H5MD files using +:mod:`MDAnalysis.coordinates.H5MD.py`, please cite [Buyl2013]_ and +[Jakupovic2021]_. + +.. [Buyl2013] Buyl P., Colberg P., and Höfling F.(2013). + H5MD: A structured, efficient, and portable file format for molecular data. + *Computer Physics Communications*, 185. doi:`10.1016/j.cpc.2014.01.018. + `_ + +.. [Jakupovic2021] Jakupovic E. and Beckstein O., MPI-parallel Molecular + Dynamics Trajectory Analysis with the H5MD Format in the MDAnalysis + Python Package, in *Proceedings of the 20th Python in Science Conference*, + (Meghann Agarwal, Chris Calloway, Dillon Niederhut, and David Shupe, eds.), + pp. 18 – 26, 2021. doi:`10.25080/majora-1b6fd038-005. + `_ + +.. comment:: + + If you use IMD capability with :mod:`MDAnalysis.coordinates.IMD.py`, please cite [IMDv3paper]_. + + .. [IMDv3paper] Authors (YEAR). + IMDv3 Manuscript Title. + *Journal*, 185. doi:`insert-doi-here `_ + +.. todo:: Fill in the final IMDv3 citation once the paper is published. + See https://github.com/MDAnalysis/mdanalysis/issues/5094 + +.. _citations-using-duecredit: + + +Citations using Duecredit +========================= + +Citations can be automatically generated using duecredit_, depending on the +packages used. Duecredit is easy to install via ``pip``. Simply type: + +.. code-block:: bash + + pip install duecredit + +duecredit_ will remain an optional dependency, i.e. any code using +MDAnalysis will work correctly even without duecredit installed. + +A list of citations for ``yourscript.py`` can be obtained using simple +commands. + +.. code-block:: bash + + cd /path/to/yourmodule + python -m duecredit yourscript.py + +or set the environment variable :envvar:`DUECREDIT_ENABLE` + +.. code-block:: bash + + DUECREDIT_ENABLE=yes python yourscript.py + +Once the citations have been extracted (to a hidden file in the +current directory), you can use the :program:`duecredit` program to +export them to different formats. For example, one can display them in +BibTeX format, using: + +.. code-block:: bash + + duecredit summary --format=bibtex + + +**Please cite your use of MDAnalysis and the packages and algorithms +that it uses. Thanks!** + + +.. _duecredit: https://github.com/duecredit/duecredit diff --git a/package/doc/sphinx/source/documentation_pages/selections.rst b/package/doc/sphinx/source/documentation_pages/selections.rst index e2a020969c6..5f011631aec 100644 --- a/package/doc/sphinx/source/documentation_pages/selections.rst +++ b/package/doc/sphinx/source/documentation_pages/selections.rst @@ -1,478 +1,478 @@ -.. -*- coding: utf-8 -*- -.. _selection-commands-label: - -==================== - Selection commands -==================== - -Once you have the :meth:`~MDAnalysis.core.universe.Universe` object, you can -select atoms (using a syntax very similar to `CHARMM's atom selection -syntax`_):: - - >>> kalp = universe.select_atoms("segid KALP") - -.. _`CHARMM's atom selection syntax`: - https://www.charmm.org/charmm/documentation/by-version/c45b1/select.html - -The :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method of a -:class:`~MDAnalysis.core.groups.AtomGroup` or a -:class:`~MDAnalysis.core.universe.Universe` returns a -:class:`~MDAnalysis.core.groups.AtomGroup`, so you can use all the methods -defined for AtomGroups on them. Selections always return an -:class:`~MDAnalysis.core.groups.AtomGroup` with atoms sorted according to their -index in the topology (this is to ensure that there are not any duplicates, -which can happen with complicated selections). - -One can group subselections using parentheses:: - - >>> universe.select_atoms("segid DMPC and not (name H* or type OW)") - - -Almost all the basic CHARMM selections work. - -It is also possible to export selections for external software -packages with the help of :ref:`Selection exporters`. - -.. note:: - - By default, atoms are sorted by index in the output AtomGroup. - For example, the below code will return the first, second, and - sixth atom in ``ag``:: - - >>> ag = u.select_atoms("name N") - >>> ag2 = ag[[5, 1, 0]] - >>> ag3 = ag2.select_atoms("name N") - >>> np.all(ag3.ix == ag2.ix) - False - - You can turn off sorting behavior with the ``sorted`` keyword:: - - >>> ag = u.select_atoms("name N") - >>> ag2 = ag[[5, 1, 0]] - >>> ag3 = ag2.select_atoms("name N", sorted=False) - >>> np.all(ag3.ix == ag2.ix) - True - - For further details on ordered selections, see :ref:`ordered-selections-label`. - - -Selection Keywords -================== - -The following describes all selection keywords currently understood by the -selection parser. The following applies to all selections: - -* Keywords are case sensitive. -* Atoms are automatically sequentially ordered in a resulting selection (see - notes below on :ref:`ordered-selections-label` for how to circumvent this if - necessary). -* Selections are parsed left to right and parentheses can be used for - grouping. -* You can use the singular name of any topology attribute as a selection - keyword. `Defined topology attributes`_ are listed in the User Guide. - Alternatively, you can define a - :class:`~MDAnalysis.core.topologyattrs.TopologyAttr` yourself, - providing that the attribute ``dtype`` is one of ``int``, ``float``, - ``str`` (or ``object``), or ``bool``. - However, the topology must contain this attribute information for - the selection to work. - - * Selections of attributes that are integers or floats can use the - syntax "myTopologyAttr 0 - 2", "myTopologyAttr 0:2", or - "myTopologyAttr 0 to 2", to select a range with - both ends inclusive. Whitespace and negative numbers are allowed. - * "myTopologyAttr 0" can be used to select all atoms - matching the value; however, this can be tricky with floats because of - precision differences and we recommend using a range like above when - possible. - * Boolean selections default to True, so "myTopologyAttr" and - "myTopologyAttr True" both give all atoms with - ``myTopologyAttr == True``. - -.. seealso:: - - Regular expression patterns - :data:`~MDAnalysis.core.selection.FLOAT_PATTERN` for matching floats; - :data:`~MDAnalysis.core.selection.INT_PATTERN` for matching integers; - and :data:`~MDAnalysis.core.selection.RANGE_PATTERN` for matching - selection ranges. - - -.. _`Defined topology attributes`: https://userguide.mdanalysis.org/stable/topology_system.html#format-specific-attributes - - -Simple selections ------------------ - -This is a non-exhaustive list of the available selection keywords. As noted -in the dot point above, keywords will be automatically generated for any -suitable :class:`~MDAnalysis.core.topologyattrs.TopologyAttr`. A list of -`Defined topology attributes`_ is available in the User Guide. - -protein, backbone, nucleic, nucleicbackbone - selects all atoms that belong to a standard set of residues; a protein - is identfied by a hard-coded set of residue names so it may not - work for esoteric residues. - -water - selects all atoms that belong to a set of water residues; water - is defined with a set of common water abbreviations present in - topology files and may not work with certain water residue names. - Currently the following water resnames are supported: - 3 letter resnames: ``H2O``, ``HOH``, ``OH2``, ``HHO``, ``OHH``, ``TIP``, - ``T3P``, ``T4P``, ``T5P``, ``SOL``, ``WAT``. - 4 letter resnames: ``TIP2``, ``TIP3``, ``TIP4``. - -segid *seg-name* - select by segid (as given in the topology), e.g. ``segid 4AKE`` or - ``segid DMPC`` - -resid *residue-number-range* - resid can take a single residue number or a range of numbers. A range - consists of two numbers separated by a colon (inclusive) such - as ``resid 1:5``. A residue number ("resid") is taken directly from the - topology. - -resnum *resnum-number-range* - resnum is the canonical residue number; typically it is set to the - residue id in the original PDB structure. - -resname *residue-name* - select by residue name, e.g. ``resname LYS``. If a residue shares a name - with a selection keyword, the name must be escaped e.g. ``resname \\water``. - -name *atom-name* - select by atom name (as given in the topology). Often, this is force - field dependent. Example: ``name CA`` (for Cα atoms) or ``name - OW`` (for SPC water oxygen) - -type *atom-type* - select by atom type; this is either a string or a number and depends on - the force field; it is read from the topology file (e.g. the CHARMM PSF - file contains numeric atom types). It has non-sensical values when a - PDB or GRO file is used as a topology. - -atom *seg-name* *residue-number* *atom-name* - a selector for a single atom consisting of segid resid atomname, - e.g. ``DMPC 1 C2`` selects the C2 carbon of the first residue of the - DMPC segment - -altLoc *alternative-location* - a selection for atoms where alternative locations are available, which is - often the case with high-resolution crystal structures - e.g. ``resid 4 and resname ALA and altLoc B`` selects only the atoms of ALA-4 - that have an altLoc B record. - -chainID *chain-name* - a selection for atoms where chainIDs have been defined. - -element *element-name* - a selection for atoms where elements have been defined. e.g. ``element H C`` - -moltype *molecule-type* - select by molecule type, e.g. ``moltype Protein_A``. At the moment, only - the TPR format defines the molecule type. - -smarts *SMARTS-query* - select atoms using Daylight's SMARTS queries, e.g. ``smarts - [#7;R]`` to find nitrogen atoms in rings. Requires RDKit. - All matches are combined as a single unique match. The `smarts` - selection accepts two sets of key word arguments from - `select_atoms()`: the ``rdkit_kwargs`` are passed internally to - `RDKitConverter.convert()` and the ``smarts_kwargs`` are passed to - RDKit's `GetSubstructMatches - `_. - By default, the `useChirality` kwarg in ``rdkit_kwargs`` is set to true - and maxMatches in ``smarts_kwargs`` is ``max(1000, 10 * n_atoms)``, where - ``n_atoms`` is either ``len(AtomGroup)`` or ``len(Universe.atoms)``, - whichever is applicable. Note that the number of matches can occasionally - exceed the default value of maxMatches, causing too few atoms to be - returned. If this occurs, a warning will be issued. The problem can be - fixed by increasing the value of maxMatches. This behavior may be updated - in the future - -chiral *R | S* - select a particular stereocenter. e.g. ``name C and chirality S`` - to select only S-chiral carbon atoms. Only ``R`` and ``S`` will be - possible options but other values will not raise an error. - -formalcharge *formal-charge* - select atoms based on their formal charge, e.g. - ``name O and formalcharge -1`` to select all oxygens with a - negative 1 formal charge. - -Pattern matching ----------------- - -The pattern matching notation described below is used to specify -patterns for matching strings (based on :mod:`fnmatch`): - -``?`` - Is a pattern that will match any single character. For example, - ``resname T?R`` selects residues named "TYR" and "THR". -``*`` - Is a pattern that will match multiple characters. For example, - ``GL*`` selects all strings that start with "GL" such as "GLU", - "GLY", "GLX29", "GLN". -``[seq]`` - Would match any character in seq. For example, "resname GL[NY]" - selects all residues named "GLN" or "GLY" but would not select - "GLU". -``[!seq]`` - Would match any character not in seq. For example, "resname GL[!NY]" - would match residues named "GLU" but would not match "GLN" or "GLY". - -Boolean -------- - -not - all atoms not in the selection, e.g. ``not protein`` selects all atoms - that aren't part of a protein - -and, or - combine two selections according to the rules of boolean algebra, - e.g. ``protein and not (resname ALA or resname LYS)`` selects all atoms - that belong to a protein, but are not in a lysine or alanine residue - -Geometric ---------- - -around *distance* *selection* - selects all atoms a certain cutoff away from another selection, - e.g. ``around 3.5 protein`` selects all atoms not belonging to protein - that are within 3.5 Angstroms from the protein - -sphlayer *innerRadius* *externalRadius* *selection* - selects all atoms within a spherical layer centered in the center of - geometry (COG) of a given selection, e.g., ``sphlayer 2.4 6.0 ( protein - and ( resid 130 or resid 80 ) )`` selects the center of geometry of - protein, resid 130, resid 80 and creates a spherical layer of inner - radius 2.4 and external radius 6.0 around the COG. - -sphzone *externalRadius* *selection* - selects all atoms within a spherical zone centered in the center of - geometry (COG) of a given selection, e.g. ``sphzone 6.0 ( protein and ( - resid 130 or resid 80 ) )`` selects the center of geometry of protein, - resid 130, resid 80 and creates a sphere of radius 6.0 around the COG. - -isolayer *inner radius* *outer radius* *selection* - Similar to sphlayer, but will find layer around all referenced atoms. - For example, if the atom types for a polymer backbone were chosen, then - an isolayer parallel to the backbone will be generated. As another - example, if a set of ions were chosen as a reference to isolate the second - hydration layer, then they will all be included in the same group. - However, in the instance that a molecule is in the second hydration layer - of one ion and the first hydration layer of another, those atoms will not - be included. - -cylayer *innerRadius* *externalRadius* *zMax* *zMin* *selection* - selects all atoms within a cylindric layer centered in the center of - geometry (COG) of a given selection, e.g. ``cylayer 5 10 10 -8 - protein`` selects the center of geometry of protein, and creates a - cylindrical layer of inner radius 5, external radius 10 centered on the - COG. In z, the cylinder extends from 10 above the COG to 8 - below. Positive values for *zMin*, or negative ones for *zMax*, are - allowed. - -cyzone *externalRadius* *zMax* *zMin* *selection* - selects all atoms within a cylindric zone centered in the center of - geometry (COG) of a given selection, e.g. ``cyzone 15 4 -8 protein and - resid 42`` selects the center of geometry of protein and resid 42, and - creates a cylinder of external radius 15 centered on the COG. In z, the - cylinder extends from 4 above the COG to 8 below. Positive values for - *zMin*, or negative ones for *zMax*, are allowed. - - .. versionchanged:: 0.10.0 - keywords *cyzone* and *cylayer* now take *zMax* and *zMin* to be - relative to the COG of *selection*, instead of absolute z-values - in the box. - -point *x* *y* *z* *distance* - selects all atoms within a cutoff of a point in space, make sure - coordinate is separated by spaces, e.g. ``point 5.0 5.0 5.0 3.5`` - selects all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, - 5.0) - -prop [abs] *property* *operator* *value* - selects atoms based on position, using *property* **x**, **y**, or - **z** coordinate. Supports the **abs** keyword (for absolute value) and - the following *operators*: **<, >, <=, >=, ==, !=**. For example, - ``prop z >= 5.0`` selects all atoms with z coordinate greater than 5.0; - ``prop abs z <= 5.0`` selects all atoms within -5.0 <= z <= 5.0. - - -.. note:: - By default periodicity **is** taken into account with geometric - selections, i.e. selections will find atoms that are in different - periodic images. - To control this behaviour, use the boolean ``"periodic"`` keyword - argument of :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms`. - - -Similarity and connectivity ---------------------------- - -same *subkeyword* as *selection* - selects all atoms that have the same *subkeyword* value as any atom in - *selection*. Allowed *subkeyword* values are the atom properties: ``name, - type, resname, resid, segid, mass, charge, radius, bfactor, resnum``, the - groups an atom belong to: ``residue, segment, fragment``, and the atom - coordinates ``x, y, z``. - -byres *selection* - selects all atoms that are in the same segment and residue as selection, - e.g. specify the subselection after the byres keyword. ``byres`` is a - shortcut to ``same residue as`` - -bonded *selection* - selects all atoms that are bonded to selection - eg: ``select name H and bonded name O`` selects only hydrogens bonded to - oxygens - -Index ------ - -bynum *index-range* - selects all atoms within a range of (1-based) inclusive indices, - e.g. ``bynum 1`` selects the first atom in the universe; ``bynum 5:10`` - selects atoms 5 through 10 inclusive. All atoms in the - :class:`MDAnalysis.Universe` are consecutively numbered, and the index - runs from 1 up to the total number of atoms. - -id *index-range* - selects all atoms in a range of (1-based) inclusive indices, e.g. ``id 1`` selects - all the atoms with id 1; ``id 5:7`` selects all atoms with ids 5, all atoms with - ids 6 and all atoms with ids 7. - -index *index-range* - selects all atoms within a range of (0-based) inclusive indices, - e.g. ``index 0`` selects the first atom in the universe; ``index 5:10`` - selects atoms 6 through 11 inclusive. All atoms in the - :class:`MDAnalysis.Universe` are consecutively numbered, and the index - runs from 0 up to the total number of atoms - 1. - - -.. note:: - Conventionally, ``id`` corresponds to the serial number in the PDB format. In contrast - to ``bynum``, the ``id`` topology attribute is not necessarily continuous, ordered, or - unique, and can be arbitrarily assigned by the user. - - -.. _pre-selections-label: - -Preexisting selections and modifiers ------------------------------------- - -group `group-name` - selects the atoms in the :class:`AtomGroup` passed to the function as an - argument named `group-name`. Only the atoms common to `group-name` and the - instance :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` was called - from will be considered, unless ``group`` is preceded by the ``global`` - keyword. `group-name` will be included in the parsing just by comparison of - atom indices. This means that it is up to the user to make sure the - `group-name` group was defined in an appropriate :class:`Universe`. - -global *selection* - by default, when issuing - :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from an - :class:`~MDAnalysis.core.groups.AtomGroup`, selections and subselections - are returned intersected with the atoms of that instance. Prefixing a - selection term with ``global`` causes its selection to be returned in its - entirety. As an example, the ``global`` keyword allows for - ``lipids.select_atoms("around 10 global protein")`` --- where ``lipids`` is - a group that does not contain any proteins. Were ``global`` absent, the - result would be an empty selection since the ``protein`` subselection would - itself be empty. When issuing - :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from a - :class:`~MDAnalysis.core.universe.Universe`, ``global`` is ignored. - -.. versionchanged:: 1.0.0 - The ``fullgroup`` selection has now been removed. Please use the equivalent - ``global group`` selection. - -Dynamic selections -================== - -By default :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` returns an -:class:`~MDAnalysis.core.groups.AtomGroup`, in which the list of atoms is -constant across trajectory frame changes. If -:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` is invoked with named -argument ``updating`` set to ``True``, an -:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` instance will be returned -instead. It behaves just like an :class:`~MDAnalysis.core.groups.AtomGroup` -object, with the difference that the selection expressions are re-evaluated -every time the trajectory frame changes (this happens lazily, only when the -:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` object is accessed so that -there is no redundant updating going on):: - - # A dynamic selection of corner atoms: - >>> ag_updating = universe.select_atoms("prop x < 5 and prop y < 5 and prop z < 5", updating=True) - >>> ag_updating - - >>> universe.trajectory.next() - >>> ag_updating - - -Using the ``group`` selection keyword for -:ref:`preexisting-selections `, one can -make updating selections depend on -:class:`~MDAnalysis.core.groups.AtomGroup`, or even other -:class:`~MDAnalysis.core.groups.UpdatingAtomGroup`, instances. -Likewise, making an updating selection from an already updating group will -cause later updates to also reflect the updating of the base group:: - - >>> chained_ag_updating = ag_updating.select_atoms("resid 1:1000", updating=True) - >>> chained_ag_updating - - >>> universe.trajectory.next() - >>> chained_ag_updating - - -Finally, a non-updating selection or a slicing/addition operation made on an -:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` will return a static -:class:`~MDAnalysis.core.groups.AtomGroup`, which will no longer update -across frames:: - - >>> static_ag = ag_updating.select_atoms("resid 1:1000") - >>> static_ag - - >>> universe.trajectory.next() - >>> static_ag - - -.. _ordered-selections-label: - -Ordered selections -================== - -:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` sorts the atoms -in the :class:`~MDAnalysis.core.groups.AtomGroup` by atom index before -returning them (this is to eliminate possible duplicates in the -selection). If the ordering of atoms is crucial (for instance when -describing angles or dihedrals) or if duplicate atoms are required -then one has to concatenate multiple AtomGroups, which does not sort -them. - -The most straightforward way to concatentate two AtomGroups is by using the -``+`` operator:: - - >>> ordered = u.select_atoms("segid DMPC and resid 3 and name P") + u.select_atoms("segid DMPC and resid 2 and name P") - >>> print(list(ordered)) - [< Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>, - < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] - -A shortcut is to provide *two or more* selections to -:meth:`~MDAnalysis.core.universe.Universe.select_atoms`, which then -does the concatenation automatically:: - - >>> print(list(universe.select_atoms("segid DMPC and resid 3 and name P", "segid DMPC and resid 2 and name P"))) - [< Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>, - < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] - -Just for comparison to show that a single selection string does not -work as one might expect:: - - # WRONG! - >>> print(list(universe.select_atoms("segid DMPC and (resid 3 or resid 2) and name P"))) - [< Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>, - < Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>] +.. -*- coding: utf-8 -*- +.. _selection-commands-label: + +==================== + Selection commands +==================== + +Once you have the :meth:`~MDAnalysis.core.universe.Universe` object, you can +select atoms (using a syntax very similar to `CHARMM's atom selection +syntax`_):: + + >>> kalp = universe.select_atoms("segid KALP") + +.. _`CHARMM's atom selection syntax`: + https://www.charmm.org/charmm/documentation/by-version/c45b1/select.html + +The :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method of a +:class:`~MDAnalysis.core.groups.AtomGroup` or a +:class:`~MDAnalysis.core.universe.Universe` returns a +:class:`~MDAnalysis.core.groups.AtomGroup`, so you can use all the methods +defined for AtomGroups on them. Selections always return an +:class:`~MDAnalysis.core.groups.AtomGroup` with atoms sorted according to their +index in the topology (this is to ensure that there are not any duplicates, +which can happen with complicated selections). + +One can group subselections using parentheses:: + + >>> universe.select_atoms("segid DMPC and not (name H* or type OW)") + + +Almost all the basic CHARMM selections work. + +It is also possible to export selections for external software +packages with the help of :ref:`Selection exporters`. + +.. note:: + + By default, atoms are sorted by index in the output AtomGroup. + For example, the below code will return the first, second, and + sixth atom in ``ag``:: + + >>> ag = u.select_atoms("name N") + >>> ag2 = ag[[5, 1, 0]] + >>> ag3 = ag2.select_atoms("name N") + >>> np.all(ag3.ix == ag2.ix) + False + + You can turn off sorting behavior with the ``sorted`` keyword:: + + >>> ag = u.select_atoms("name N") + >>> ag2 = ag[[5, 1, 0]] + >>> ag3 = ag2.select_atoms("name N", sorted=False) + >>> np.all(ag3.ix == ag2.ix) + True + + For further details on ordered selections, see :ref:`ordered-selections-label`. + + +Selection Keywords +================== + +The following describes all selection keywords currently understood by the +selection parser. The following applies to all selections: + +* Keywords are case sensitive. +* Atoms are automatically sequentially ordered in a resulting selection (see + notes below on :ref:`ordered-selections-label` for how to circumvent this if + necessary). +* Selections are parsed left to right and parentheses can be used for + grouping. +* You can use the singular name of any topology attribute as a selection + keyword. `Defined topology attributes`_ are listed in the User Guide. + Alternatively, you can define a + :class:`~MDAnalysis.core.topologyattrs.TopologyAttr` yourself, + providing that the attribute ``dtype`` is one of ``int``, ``float``, + ``str`` (or ``object``), or ``bool``. + However, the topology must contain this attribute information for + the selection to work. + + * Selections of attributes that are integers or floats can use the + syntax "myTopologyAttr 0 - 2", "myTopologyAttr 0:2", or + "myTopologyAttr 0 to 2", to select a range with + both ends inclusive. Whitespace and negative numbers are allowed. + * "myTopologyAttr 0" can be used to select all atoms + matching the value; however, this can be tricky with floats because of + precision differences and we recommend using a range like above when + possible. + * Boolean selections default to True, so "myTopologyAttr" and + "myTopologyAttr True" both give all atoms with + ``myTopologyAttr == True``. + +.. seealso:: + + Regular expression patterns + :data:`~MDAnalysis.core.selection.FLOAT_PATTERN` for matching floats; + :data:`~MDAnalysis.core.selection.INT_PATTERN` for matching integers; + and :data:`~MDAnalysis.core.selection.RANGE_PATTERN` for matching + selection ranges. + + +.. _`Defined topology attributes`: https://userguide.mdanalysis.org/stable/topology_system.html#format-specific-attributes + + +Simple selections +----------------- + +This is a non-exhaustive list of the available selection keywords. As noted +in the dot point above, keywords will be automatically generated for any +suitable :class:`~MDAnalysis.core.topologyattrs.TopologyAttr`. A list of +`Defined topology attributes`_ is available in the User Guide. + +protein, backbone, nucleic, nucleicbackbone + selects all atoms that belong to a standard set of residues; a protein + is identfied by a hard-coded set of residue names so it may not + work for esoteric residues. + +water + selects all atoms that belong to a set of water residues; water + is defined with a set of common water abbreviations present in + topology files and may not work with certain water residue names. + Currently the following water resnames are supported: + 3 letter resnames: ``H2O``, ``HOH``, ``OH2``, ``HHO``, ``OHH``, ``TIP``, + ``T3P``, ``T4P``, ``T5P``, ``SOL``, ``WAT``. + 4 letter resnames: ``TIP2``, ``TIP3``, ``TIP4``. + +segid *seg-name* + select by segid (as given in the topology), e.g. ``segid 4AKE`` or + ``segid DMPC`` + +resid *residue-number-range* + resid can take a single residue number or a range of numbers. A range + consists of two numbers separated by a colon (inclusive) such + as ``resid 1:5``. A residue number ("resid") is taken directly from the + topology. + +resnum *resnum-number-range* + resnum is the canonical residue number; typically it is set to the + residue id in the original PDB structure. + +resname *residue-name* + select by residue name, e.g. ``resname LYS``. If a residue shares a name + with a selection keyword, the name must be escaped e.g. ``resname \\water``. + +name *atom-name* + select by atom name (as given in the topology). Often, this is force + field dependent. Example: ``name CA`` (for Cα atoms) or ``name + OW`` (for SPC water oxygen) + +type *atom-type* + select by atom type; this is either a string or a number and depends on + the force field; it is read from the topology file (e.g. the CHARMM PSF + file contains numeric atom types). It has non-sensical values when a + PDB or GRO file is used as a topology. + +atom *seg-name* *residue-number* *atom-name* + a selector for a single atom consisting of segid resid atomname, + e.g. ``DMPC 1 C2`` selects the C2 carbon of the first residue of the + DMPC segment + +altLoc *alternative-location* + a selection for atoms where alternative locations are available, which is + often the case with high-resolution crystal structures + e.g. ``resid 4 and resname ALA and altLoc B`` selects only the atoms of ALA-4 + that have an altLoc B record. + +chainID *chain-name* + a selection for atoms where chainIDs have been defined. + +element *element-name* + a selection for atoms where elements have been defined. e.g. ``element H C`` + +moltype *molecule-type* + select by molecule type, e.g. ``moltype Protein_A``. At the moment, only + the TPR format defines the molecule type. + +smarts *SMARTS-query* + select atoms using Daylight's SMARTS queries, e.g. ``smarts + [#7;R]`` to find nitrogen atoms in rings. Requires RDKit. + All matches are combined as a single unique match. The `smarts` + selection accepts two sets of key word arguments from + `select_atoms()`: the ``rdkit_kwargs`` are passed internally to + `RDKitConverter.convert()` and the ``smarts_kwargs`` are passed to + RDKit's `GetSubstructMatches + `_. + By default, the `useChirality` kwarg in ``rdkit_kwargs`` is set to true + and maxMatches in ``smarts_kwargs`` is ``max(1000, 10 * n_atoms)``, where + ``n_atoms`` is either ``len(AtomGroup)`` or ``len(Universe.atoms)``, + whichever is applicable. Note that the number of matches can occasionally + exceed the default value of maxMatches, causing too few atoms to be + returned. If this occurs, a warning will be issued. The problem can be + fixed by increasing the value of maxMatches. This behavior may be updated + in the future + +chiral *R | S* + select a particular stereocenter. e.g. ``name C and chirality S`` + to select only S-chiral carbon atoms. Only ``R`` and ``S`` will be + possible options but other values will not raise an error. + +formalcharge *formal-charge* + select atoms based on their formal charge, e.g. + ``name O and formalcharge -1`` to select all oxygens with a + negative 1 formal charge. + +Pattern matching +---------------- + +The pattern matching notation described below is used to specify +patterns for matching strings (based on :mod:`fnmatch`): + +``?`` + Is a pattern that will match any single character. For example, + ``resname T?R`` selects residues named "TYR" and "THR". +``*`` + Is a pattern that will match multiple characters. For example, + ``GL*`` selects all strings that start with "GL" such as "GLU", + "GLY", "GLX29", "GLN". +``[seq]`` + Would match any character in seq. For example, "resname GL[NY]" + selects all residues named "GLN" or "GLY" but would not select + "GLU". +``[!seq]`` + Would match any character not in seq. For example, "resname GL[!NY]" + would match residues named "GLU" but would not match "GLN" or "GLY". + +Boolean +------- + +not + all atoms not in the selection, e.g. ``not protein`` selects all atoms + that aren't part of a protein + +and, or + combine two selections according to the rules of boolean algebra, + e.g. ``protein and not (resname ALA or resname LYS)`` selects all atoms + that belong to a protein, but are not in a lysine or alanine residue + +Geometric +--------- + +around *distance* *selection* + selects all atoms a certain cutoff away from another selection, + e.g. ``around 3.5 protein`` selects all atoms not belonging to protein + that are within 3.5 Angstroms from the protein + +sphlayer *innerRadius* *externalRadius* *selection* + selects all atoms within a spherical layer centered in the center of + geometry (COG) of a given selection, e.g., ``sphlayer 2.4 6.0 ( protein + and ( resid 130 or resid 80 ) )`` selects the center of geometry of + protein, resid 130, resid 80 and creates a spherical layer of inner + radius 2.4 and external radius 6.0 around the COG. + +sphzone *externalRadius* *selection* + selects all atoms within a spherical zone centered in the center of + geometry (COG) of a given selection, e.g. ``sphzone 6.0 ( protein and ( + resid 130 or resid 80 ) )`` selects the center of geometry of protein, + resid 130, resid 80 and creates a sphere of radius 6.0 around the COG. + +isolayer *inner radius* *outer radius* *selection* + Similar to sphlayer, but will find layer around all referenced atoms. + For example, if the atom types for a polymer backbone were chosen, then + an isolayer parallel to the backbone will be generated. As another + example, if a set of ions were chosen as a reference to isolate the second + hydration layer, then they will all be included in the same group. + However, in the instance that a molecule is in the second hydration layer + of one ion and the first hydration layer of another, those atoms will not + be included. + +cylayer *innerRadius* *externalRadius* *zMax* *zMin* *selection* + selects all atoms within a cylindric layer centered in the center of + geometry (COG) of a given selection, e.g. ``cylayer 5 10 10 -8 + protein`` selects the center of geometry of protein, and creates a + cylindrical layer of inner radius 5, external radius 10 centered on the + COG. In z, the cylinder extends from 10 above the COG to 8 + below. Positive values for *zMin*, or negative ones for *zMax*, are + allowed. + +cyzone *externalRadius* *zMax* *zMin* *selection* + selects all atoms within a cylindric zone centered in the center of + geometry (COG) of a given selection, e.g. ``cyzone 15 4 -8 protein and + resid 42`` selects the center of geometry of protein and resid 42, and + creates a cylinder of external radius 15 centered on the COG. In z, the + cylinder extends from 4 above the COG to 8 below. Positive values for + *zMin*, or negative ones for *zMax*, are allowed. + + .. versionchanged:: 0.10.0 + keywords *cyzone* and *cylayer* now take *zMax* and *zMin* to be + relative to the COG of *selection*, instead of absolute z-values + in the box. + +point *x* *y* *z* *distance* + selects all atoms within a cutoff of a point in space, make sure + coordinate is separated by spaces, e.g. ``point 5.0 5.0 5.0 3.5`` + selects all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, + 5.0) + +prop [abs] *property* *operator* *value* + selects atoms based on position, using *property* **x**, **y**, or + **z** coordinate. Supports the **abs** keyword (for absolute value) and + the following *operators*: **<, >, <=, >=, ==, !=**. For example, + ``prop z >= 5.0`` selects all atoms with z coordinate greater than 5.0; + ``prop abs z <= 5.0`` selects all atoms within -5.0 <= z <= 5.0. + + +.. note:: + By default periodicity **is** taken into account with geometric + selections, i.e. selections will find atoms that are in different + periodic images. + To control this behaviour, use the boolean ``"periodic"`` keyword + argument of :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms`. + + +Similarity and connectivity +--------------------------- + +same *subkeyword* as *selection* + selects all atoms that have the same *subkeyword* value as any atom in + *selection*. Allowed *subkeyword* values are the atom properties: ``name, + type, resname, resid, segid, mass, charge, radius, bfactor, resnum``, the + groups an atom belong to: ``residue, segment, fragment``, and the atom + coordinates ``x, y, z``. + +byres *selection* + selects all atoms that are in the same segment and residue as selection, + e.g. specify the subselection after the byres keyword. ``byres`` is a + shortcut to ``same residue as`` + +bonded *selection* + selects all atoms that are bonded to selection + eg: ``select name H and bonded name O`` selects only hydrogens bonded to + oxygens + +Index +----- + +bynum *index-range* + selects all atoms within a range of (1-based) inclusive indices, + e.g. ``bynum 1`` selects the first atom in the universe; ``bynum 5:10`` + selects atoms 5 through 10 inclusive. All atoms in the + :class:`MDAnalysis.Universe` are consecutively numbered, and the index + runs from 1 up to the total number of atoms. + +id *index-range* + selects all atoms in a range of (1-based) inclusive indices, e.g. ``id 1`` selects + all the atoms with id 1; ``id 5:7`` selects all atoms with ids 5, all atoms with + ids 6 and all atoms with ids 7. + +index *index-range* + selects all atoms within a range of (0-based) inclusive indices, + e.g. ``index 0`` selects the first atom in the universe; ``index 5:10`` + selects atoms 6 through 11 inclusive. All atoms in the + :class:`MDAnalysis.Universe` are consecutively numbered, and the index + runs from 0 up to the total number of atoms - 1. + + +.. note:: + Conventionally, ``id`` corresponds to the serial number in the PDB format. In contrast + to ``bynum``, the ``id`` topology attribute is not necessarily continuous, ordered, or + unique, and can be arbitrarily assigned by the user. + + +.. _pre-selections-label: + +Preexisting selections and modifiers +------------------------------------ + +group `group-name` + selects the atoms in the :class:`AtomGroup` passed to the function as an + argument named `group-name`. Only the atoms common to `group-name` and the + instance :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` was called + from will be considered, unless ``group`` is preceded by the ``global`` + keyword. `group-name` will be included in the parsing just by comparison of + atom indices. This means that it is up to the user to make sure the + `group-name` group was defined in an appropriate :class:`Universe`. + +global *selection* + by default, when issuing + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from an + :class:`~MDAnalysis.core.groups.AtomGroup`, selections and subselections + are returned intersected with the atoms of that instance. Prefixing a + selection term with ``global`` causes its selection to be returned in its + entirety. As an example, the ``global`` keyword allows for + ``lipids.select_atoms("around 10 global protein")`` --- where ``lipids`` is + a group that does not contain any proteins. Were ``global`` absent, the + result would be an empty selection since the ``protein`` subselection would + itself be empty. When issuing + :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` from a + :class:`~MDAnalysis.core.universe.Universe`, ``global`` is ignored. + +.. versionchanged:: 1.0.0 + The ``fullgroup`` selection has now been removed. Please use the equivalent + ``global group`` selection. + +Dynamic selections +================== + +By default :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` returns an +:class:`~MDAnalysis.core.groups.AtomGroup`, in which the list of atoms is +constant across trajectory frame changes. If +:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` is invoked with named +argument ``updating`` set to ``True``, an +:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` instance will be returned +instead. It behaves just like an :class:`~MDAnalysis.core.groups.AtomGroup` +object, with the difference that the selection expressions are re-evaluated +every time the trajectory frame changes (this happens lazily, only when the +:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` object is accessed so that +there is no redundant updating going on):: + + # A dynamic selection of corner atoms: + >>> ag_updating = universe.select_atoms("prop x < 5 and prop y < 5 and prop z < 5", updating=True) + >>> ag_updating + + >>> universe.trajectory.next() + >>> ag_updating + + +Using the ``group`` selection keyword for +:ref:`preexisting-selections `, one can +make updating selections depend on +:class:`~MDAnalysis.core.groups.AtomGroup`, or even other +:class:`~MDAnalysis.core.groups.UpdatingAtomGroup`, instances. +Likewise, making an updating selection from an already updating group will +cause later updates to also reflect the updating of the base group:: + + >>> chained_ag_updating = ag_updating.select_atoms("resid 1:1000", updating=True) + >>> chained_ag_updating + + >>> universe.trajectory.next() + >>> chained_ag_updating + + +Finally, a non-updating selection or a slicing/addition operation made on an +:class:`~MDAnalysis.core.groups.UpdatingAtomGroup` will return a static +:class:`~MDAnalysis.core.groups.AtomGroup`, which will no longer update +across frames:: + + >>> static_ag = ag_updating.select_atoms("resid 1:1000") + >>> static_ag + + >>> universe.trajectory.next() + >>> static_ag + + +.. _ordered-selections-label: + +Ordered selections +================== + +:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` sorts the atoms +in the :class:`~MDAnalysis.core.groups.AtomGroup` by atom index before +returning them (this is to eliminate possible duplicates in the +selection). If the ordering of atoms is crucial (for instance when +describing angles or dihedrals) or if duplicate atoms are required +then one has to concatenate multiple AtomGroups, which does not sort +them. + +The most straightforward way to concatentate two AtomGroups is by using the +``+`` operator:: + + >>> ordered = u.select_atoms("segid DMPC and resid 3 and name P") + u.select_atoms("segid DMPC and resid 2 and name P") + >>> print(list(ordered)) + [< Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>, + < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] + +A shortcut is to provide *two or more* selections to +:meth:`~MDAnalysis.core.universe.Universe.select_atoms`, which then +does the concatenation automatically:: + + >>> print(list(universe.select_atoms("segid DMPC and resid 3 and name P", "segid DMPC and resid 2 and name P"))) + [< Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>, + < Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>] + +Just for comparison to show that a single selection string does not +work as one might expect:: + + # WRONG! + >>> print(list(universe.select_atoms("segid DMPC and (resid 3 or resid 2) and name P"))) + [< Atom 452: name 'P' of type '180' of resid 'DMPC', 2 and 'DMPC'>, + < Atom 570: name 'P' of type '180' of resid 'DMPC', 3 and 'DMPC'>] diff --git a/package/doc/sphinx/source/documentation_pages/selections/base.rst b/package/doc/sphinx/source/documentation_pages/selections/base.rst index 20b0b2e3e40..ee491ee2fd5 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/base.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/base.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.selections.base +.. automodule:: MDAnalysis.selections.base diff --git a/package/doc/sphinx/source/documentation_pages/selections/charmm.rst b/package/doc/sphinx/source/documentation_pages/selections/charmm.rst index 673e74204aa..492dba3ffab 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/charmm.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/charmm.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.selections.charmm - +.. automodule:: MDAnalysis.selections.charmm + diff --git a/package/doc/sphinx/source/documentation_pages/selections/gromacs.rst b/package/doc/sphinx/source/documentation_pages/selections/gromacs.rst index accc0123ad7..c9182a1851d 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/gromacs.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/gromacs.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.selections.gromacs +.. automodule:: MDAnalysis.selections.gromacs diff --git a/package/doc/sphinx/source/documentation_pages/selections/jmol.rst b/package/doc/sphinx/source/documentation_pages/selections/jmol.rst index 9fcce220207..786e53b1c84 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/jmol.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/jmol.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.selections.jmol +.. automodule:: MDAnalysis.selections.jmol diff --git a/package/doc/sphinx/source/documentation_pages/selections/pymol.rst b/package/doc/sphinx/source/documentation_pages/selections/pymol.rst index 390fcdd8381..4cbd197e256 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/pymol.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/pymol.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.selections.pymol - +.. automodule:: MDAnalysis.selections.pymol + diff --git a/package/doc/sphinx/source/documentation_pages/selections/vmd.rst b/package/doc/sphinx/source/documentation_pages/selections/vmd.rst index be547a4d390..55e39faade9 100644 --- a/package/doc/sphinx/source/documentation_pages/selections/vmd.rst +++ b/package/doc/sphinx/source/documentation_pages/selections/vmd.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.selections.vmd - +.. automodule:: MDAnalysis.selections.vmd + diff --git a/package/doc/sphinx/source/documentation_pages/selections_modules.rst b/package/doc/sphinx/source/documentation_pages/selections_modules.rst index a3ec9399451..86800d4d7e5 100644 --- a/package/doc/sphinx/source/documentation_pages/selections_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/selections_modules.rst @@ -1,125 +1,125 @@ -.. Contains the formatted docstrings for the core modules located in 'mdanalysis/MDAnalysis/core' - -.. _`Selection exporters`: - -******************* -Selection exporters -******************* - -The classes in this module allow writing a selection to a file that can be read by -*another program* to select the atoms in a MDAnalysis -:class:`MDAnalysis.core.groups.AtomGroup`. Such cross-package interoperability -allows a user to combine their favourite tools with MDAnalysis for further -visualization or simulation. - - -.. _Supported selection exporters: - -.. table:: Table of supported exporters and recognized file name extensions. - - +---------------+-----------+-------+--------------------------------------------+ - |Name | extension | IO | remarks | - +===============+===========+=======+============================================+ - | vmd | tcl | w | VMD_ macros, available in Representations; | - | | | | module :mod:`MDAnalysis.selections.vmd` | - +---------------+-----------+-------+--------------------------------------------+ - | pymol | pml | w | simple PyMOL_ selection string; | - | | | | module :mod:`MDAnalysis.selections.pymol` | - +---------------+-----------+-------+--------------------------------------------+ - | gromacs | ndx | w | Gromacs_ index file; | - | | | | module :mod:`MDAnalysis.selections.gromacs`| - +---------------+-----------+-------+--------------------------------------------+ - | charmm | str | w | CHARMM_ selection of individual atoms; | - | | | | module :mod:`MDAnalysis.selections.charmm` | - +---------------+-----------+-------+--------------------------------------------+ - | jmol | spt | w | Jmol_ selection commands; | - | | | | module :mod:`MDAnalysis.selections.jmol` | - +---------------+-----------+-------+--------------------------------------------+ - -How to write selections -======================= - -Single AtomGroup ----------------- - -The typical situation is that one has an -:class:`~MDAnalysis.core.groups.AtomGroup` and wants to work with the -same selection of atoms in a different package, for example, to -visualize the atoms in VMD_. First create an :class:`AtomGroup` (named -``g`` in the example below) and then use its -:class:`~MDAnalysis.core.groups.AtomGroup.write` method with the -appropriate *file extension* (see :ref:`Supported selection -exporters` for the recognized *extension*):: - - g = u.select_atoms('protein") - g.write("selections.vmd", name="mda_protein") - -In VMD_, sourcing the file ``selections.vmd`` (written in Tcl) defines -the "macro" ``mda_protein`` that contains the atom indices to select - -.. code-block:: tcl - - source selection.vmd - set sel [atomselect top mda_mdanalysis] - -and in the GUI the macro appears in the :menuselection:`Graphics --> -Representations` window in the list :guilabel:`Selections: Singlewords` as -"mda_protein". - - -Multiple selections -------------------- - -The :class:`~MDAnalysis.core.groups.AtomGroup.write` method can take -additional keyword arguments, including ``mode``. The default is -``mode="w"``, which will overwrite the provided file. If ``mode="a"`` -then the selection is *appended* to the file. - -Alternatively, one may use the -:class:`~MDAnalysis.selections.base.SelectionWriter` itself as a -context manager and write each :class:`AtomGroup` inside the -context. For example, to write multiple groups that were selected to -mark different parts of a lipid bilayer to Gromacs_ index file named -"leaflets.ndx":: - - with mda.selections.gromacs.SelectionWriter('leaflets.ndx', mode='w') as ndx: - ndx.write(upper_saturated, name='upper_sat') - ndx.write(lower_saturated, name='lower_sat') - ndx.write(upper_unsaturated, name='upper_unsat') - ndx.write(lower_unsaturated, name='lower_unsat') - -There is a separate :class:`SelectionWriter` for each format, as -described next. - - -Selection writers -================= - -There exist different :class:`~MDAnalysis.selections.base.SelectionWriterBase` -classes for different packages. The -:func:`~MDAnalysis.selections.get_writer` function can automatically pick -the appropriate one, based on the file name extension in the :ref:`Supported -selection exporters`. - -.. autofunction:: MDAnalysis.selections.get_writer - - -.. rubric:: Formats - -Each module implements a :class:`SelectionWriter` for a specific format. - -.. toctree:: - :maxdepth: 1 - - selections/vmd - selections/pymol - selections/gromacs - selections/charmm - selections/jmol - selections/base - -.. _CHARMM: http://www.charmm.org -.. _Gromacs: http://www.gromacs.org -.. _VMD: http://www.ks.uiuc.edu/Research/vmd/ -.. _PyMOL: http://www.pymol.org -.. _Jmol: https://jmol.sourceforge.net/ +.. Contains the formatted docstrings for the core modules located in 'mdanalysis/MDAnalysis/core' + +.. _`Selection exporters`: + +******************* +Selection exporters +******************* + +The classes in this module allow writing a selection to a file that can be read by +*another program* to select the atoms in a MDAnalysis +:class:`MDAnalysis.core.groups.AtomGroup`. Such cross-package interoperability +allows a user to combine their favourite tools with MDAnalysis for further +visualization or simulation. + + +.. _Supported selection exporters: + +.. table:: Table of supported exporters and recognized file name extensions. + + +---------------+-----------+-------+--------------------------------------------+ + |Name | extension | IO | remarks | + +===============+===========+=======+============================================+ + | vmd | tcl | w | VMD_ macros, available in Representations; | + | | | | module :mod:`MDAnalysis.selections.vmd` | + +---------------+-----------+-------+--------------------------------------------+ + | pymol | pml | w | simple PyMOL_ selection string; | + | | | | module :mod:`MDAnalysis.selections.pymol` | + +---------------+-----------+-------+--------------------------------------------+ + | gromacs | ndx | w | Gromacs_ index file; | + | | | | module :mod:`MDAnalysis.selections.gromacs`| + +---------------+-----------+-------+--------------------------------------------+ + | charmm | str | w | CHARMM_ selection of individual atoms; | + | | | | module :mod:`MDAnalysis.selections.charmm` | + +---------------+-----------+-------+--------------------------------------------+ + | jmol | spt | w | Jmol_ selection commands; | + | | | | module :mod:`MDAnalysis.selections.jmol` | + +---------------+-----------+-------+--------------------------------------------+ + +How to write selections +======================= + +Single AtomGroup +---------------- + +The typical situation is that one has an +:class:`~MDAnalysis.core.groups.AtomGroup` and wants to work with the +same selection of atoms in a different package, for example, to +visualize the atoms in VMD_. First create an :class:`AtomGroup` (named +``g`` in the example below) and then use its +:class:`~MDAnalysis.core.groups.AtomGroup.write` method with the +appropriate *file extension* (see :ref:`Supported selection +exporters` for the recognized *extension*):: + + g = u.select_atoms('protein") + g.write("selections.vmd", name="mda_protein") + +In VMD_, sourcing the file ``selections.vmd`` (written in Tcl) defines +the "macro" ``mda_protein`` that contains the atom indices to select + +.. code-block:: tcl + + source selection.vmd + set sel [atomselect top mda_mdanalysis] + +and in the GUI the macro appears in the :menuselection:`Graphics --> +Representations` window in the list :guilabel:`Selections: Singlewords` as +"mda_protein". + + +Multiple selections +------------------- + +The :class:`~MDAnalysis.core.groups.AtomGroup.write` method can take +additional keyword arguments, including ``mode``. The default is +``mode="w"``, which will overwrite the provided file. If ``mode="a"`` +then the selection is *appended* to the file. + +Alternatively, one may use the +:class:`~MDAnalysis.selections.base.SelectionWriter` itself as a +context manager and write each :class:`AtomGroup` inside the +context. For example, to write multiple groups that were selected to +mark different parts of a lipid bilayer to Gromacs_ index file named +"leaflets.ndx":: + + with mda.selections.gromacs.SelectionWriter('leaflets.ndx', mode='w') as ndx: + ndx.write(upper_saturated, name='upper_sat') + ndx.write(lower_saturated, name='lower_sat') + ndx.write(upper_unsaturated, name='upper_unsat') + ndx.write(lower_unsaturated, name='lower_unsat') + +There is a separate :class:`SelectionWriter` for each format, as +described next. + + +Selection writers +================= + +There exist different :class:`~MDAnalysis.selections.base.SelectionWriterBase` +classes for different packages. The +:func:`~MDAnalysis.selections.get_writer` function can automatically pick +the appropriate one, based on the file name extension in the :ref:`Supported +selection exporters`. + +.. autofunction:: MDAnalysis.selections.get_writer + + +.. rubric:: Formats + +Each module implements a :class:`SelectionWriter` for a specific format. + +.. toctree:: + :maxdepth: 1 + + selections/vmd + selections/pymol + selections/gromacs + selections/charmm + selections/jmol + selections/base + +.. _CHARMM: http://www.charmm.org +.. _Gromacs: http://www.gromacs.org +.. _VMD: http://www.ks.uiuc.edu/Research/vmd/ +.. _PyMOL: http://www.pymol.org +.. _Jmol: https://jmol.sourceforge.net/ diff --git a/package/doc/sphinx/source/documentation_pages/topology.rst b/package/doc/sphinx/source/documentation_pages/topology.rst index 8162638107f..5f612814d52 100644 --- a/package/doc/sphinx/source/documentation_pages/topology.rst +++ b/package/doc/sphinx/source/documentation_pages/topology.rst @@ -1,14 +1,14 @@ -.. -*- coding: utf-8 -*- -.. _topology-label: - -===================== - The topology system -===================== - -See :mod:`MDAnalysis.topology` for details on topology parsing, format support, and -the :class:`~MDAnalysis.core.topology.Topology` object. - -User-level documentation can be found in the `topology section of the User Guide`_. - -.. _topology section of the User Guide: https://userguide.mdanalysis.org/stable/topology_system.html - +.. -*- coding: utf-8 -*- +.. _topology-label: + +===================== + The topology system +===================== + +See :mod:`MDAnalysis.topology` for details on topology parsing, format support, and +the :class:`~MDAnalysis.core.topology.Topology` object. + +User-level documentation can be found in the `topology section of the User Guide`_. + +.. _topology section of the User Guide: https://userguide.mdanalysis.org/stable/topology_system.html + diff --git a/package/doc/sphinx/source/documentation_pages/topology/CRDParser.rst b/package/doc/sphinx/source/documentation_pages/topology/CRDParser.rst index faba597412c..c43ccca8f1c 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/CRDParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/CRDParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.CRDParser +.. automodule:: MDAnalysis.topology.CRDParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/DLPolyParser.rst b/package/doc/sphinx/source/documentation_pages/topology/DLPolyParser.rst index 8364d67589c..b1cf0c4e9d0 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/DLPolyParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/DLPolyParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.DLPolyParser +.. automodule:: MDAnalysis.topology.DLPolyParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/DMSParser.rst b/package/doc/sphinx/source/documentation_pages/topology/DMSParser.rst index 298e49cfabe..31f85e5448e 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/DMSParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/DMSParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.DMSParser +.. automodule:: MDAnalysis.topology.DMSParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/ExtendedPDBParser.rst b/package/doc/sphinx/source/documentation_pages/topology/ExtendedPDBParser.rst index cf5f3d2c43f..755b7541cd3 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/ExtendedPDBParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/ExtendedPDBParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.ExtendedPDBParser +.. automodule:: MDAnalysis.topology.ExtendedPDBParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/FHIAIMSParser.rst b/package/doc/sphinx/source/documentation_pages/topology/FHIAIMSParser.rst index 2e059709845..5fcb2433e23 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/FHIAIMSParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/FHIAIMSParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.FHIAIMSParser - +.. automodule:: MDAnalysis.topology.FHIAIMSParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/GMSParser.rst b/package/doc/sphinx/source/documentation_pages/topology/GMSParser.rst index 94095d10d51..ab60c2d5919 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/GMSParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/GMSParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.GMSParser +.. automodule:: MDAnalysis.topology.GMSParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/GROParser.rst b/package/doc/sphinx/source/documentation_pages/topology/GROParser.rst index cd1f876ded5..411035ed7a0 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/GROParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/GROParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.GROParser +.. automodule:: MDAnalysis.topology.GROParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/GSDParser.rst b/package/doc/sphinx/source/documentation_pages/topology/GSDParser.rst index 50f4d2f4a92..d184b8b4ca0 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/GSDParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/GSDParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.GSDParser +.. automodule:: MDAnalysis.topology.GSDParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/HoomdXMLParser.rst b/package/doc/sphinx/source/documentation_pages/topology/HoomdXMLParser.rst index 9d3b04b8b14..c742ff17489 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/HoomdXMLParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/HoomdXMLParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.HoomdXMLParser +.. automodule:: MDAnalysis.topology.HoomdXMLParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/ITPParser.rst b/package/doc/sphinx/source/documentation_pages/topology/ITPParser.rst index e5d5511caf3..51f73749854 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/ITPParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/ITPParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.ITPParser +.. automodule:: MDAnalysis.topology.ITPParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/LAMMPSParser.rst b/package/doc/sphinx/source/documentation_pages/topology/LAMMPSParser.rst index cd1dde00f94..5f7b5f0796d 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/LAMMPSParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/LAMMPSParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.LAMMPSParser - +.. automodule:: MDAnalysis.topology.LAMMPSParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/MMTFParser.rst b/package/doc/sphinx/source/documentation_pages/topology/MMTFParser.rst index c86da7fe2ef..ecc349dcfc2 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/MMTFParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/MMTFParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.MMTFParser +.. automodule:: MDAnalysis.topology.MMTFParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/MOL2Parser.rst b/package/doc/sphinx/source/documentation_pages/topology/MOL2Parser.rst index 91488264a9a..8bc2b903979 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/MOL2Parser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/MOL2Parser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.MOL2Parser - +.. automodule:: MDAnalysis.topology.MOL2Parser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/MinimalParser.rst b/package/doc/sphinx/source/documentation_pages/topology/MinimalParser.rst index 724af39e3f7..812e5c576eb 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/MinimalParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/MinimalParser.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.MinimalParser +.. automodule:: MDAnalysis.topology.MinimalParser diff --git a/package/doc/sphinx/source/documentation_pages/topology/PDBParser.rst b/package/doc/sphinx/source/documentation_pages/topology/PDBParser.rst index e7ec59cf64b..bd081d49f91 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/PDBParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/PDBParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.PDBParser - +.. automodule:: MDAnalysis.topology.PDBParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/PDBQTParser.rst b/package/doc/sphinx/source/documentation_pages/topology/PDBQTParser.rst index c584b9cea72..5d689e2bda5 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/PDBQTParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/PDBQTParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.PDBQTParser - +.. automodule:: MDAnalysis.topology.PDBQTParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/PQRParser.rst b/package/doc/sphinx/source/documentation_pages/topology/PQRParser.rst index 6061c49e879..35cd93fd1af 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/PQRParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/PQRParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.PQRParser - +.. automodule:: MDAnalysis.topology.PQRParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/PSFParser.rst b/package/doc/sphinx/source/documentation_pages/topology/PSFParser.rst index d8cf0f512c0..054ab4a364c 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/PSFParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/PSFParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.PSFParser - +.. automodule:: MDAnalysis.topology.PSFParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/TOPParser.rst b/package/doc/sphinx/source/documentation_pages/topology/TOPParser.rst index d7738f98b32..f47adce4302 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/TOPParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/TOPParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.TOPParser - +.. automodule:: MDAnalysis.topology.TOPParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/TPRParser.rst b/package/doc/sphinx/source/documentation_pages/topology/TPRParser.rst index 397ae3904bd..dc2f554159f 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/TPRParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/TPRParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.TPRParser - +.. automodule:: MDAnalysis.topology.TPRParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/TXYZParser.rst b/package/doc/sphinx/source/documentation_pages/topology/TXYZParser.rst index c76cb9a7977..ca95dbe92f9 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/TXYZParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/TXYZParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.TXYZParser - +.. automodule:: MDAnalysis.topology.TXYZParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/XYZParser.rst b/package/doc/sphinx/source/documentation_pages/topology/XYZParser.rst index cb29d637c1d..f65bc9688c8 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/XYZParser.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/XYZParser.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.XYZParser - +.. automodule:: MDAnalysis.topology.XYZParser + diff --git a/package/doc/sphinx/source/documentation_pages/topology/base.rst b/package/doc/sphinx/source/documentation_pages/topology/base.rst index fc9b0d2fe1d..1a4f74197b5 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/base.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/base.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.base - +.. automodule:: MDAnalysis.topology.base + diff --git a/package/doc/sphinx/source/documentation_pages/topology/core.rst b/package/doc/sphinx/source/documentation_pages/topology/core.rst index 3e578bd2d81..4f783a8e0f2 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/core.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/core.rst @@ -1,6 +1,6 @@ -.. core.rst uses automatic listing of members at the moment; all the -.. other ones have the classes and functions explicitly listed in the -.. reST doc string. - -.. automodule:: MDAnalysis.topology.core - :members: +.. core.rst uses automatic listing of members at the moment; all the +.. other ones have the classes and functions explicitly listed in the +.. reST doc string. + +.. automodule:: MDAnalysis.topology.core + :members: diff --git a/package/doc/sphinx/source/documentation_pages/topology/guessers.rst b/package/doc/sphinx/source/documentation_pages/topology/guessers.rst index e6449f5ddc8..f512facae66 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/guessers.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/guessers.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.topology.guessers - :members: +.. automodule:: MDAnalysis.topology.guessers + :members: diff --git a/package/doc/sphinx/source/documentation_pages/topology/init.rst b/package/doc/sphinx/source/documentation_pages/topology/init.rst index 5517e354f36..357bcef7036 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/init.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/init.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.__init__ +.. automodule:: MDAnalysis.topology.__init__ diff --git a/package/doc/sphinx/source/documentation_pages/topology/tables.rst b/package/doc/sphinx/source/documentation_pages/topology/tables.rst index f4d579ec9c8..aab066727c2 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/tables.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/tables.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.topology.tables +.. automodule:: MDAnalysis.topology.tables diff --git a/package/doc/sphinx/source/documentation_pages/topology/tpr_util.rst b/package/doc/sphinx/source/documentation_pages/topology/tpr_util.rst index acf5427240a..693e9953da6 100644 --- a/package/doc/sphinx/source/documentation_pages/topology/tpr_util.rst +++ b/package/doc/sphinx/source/documentation_pages/topology/tpr_util.rst @@ -1,21 +1,21 @@ -=============================================== - Utility functions for the TPR topology parser -=============================================== - -The :mod:`MDAnalysis.topology.tpr` module contains classes and -functions on which the Gromacs TPR topology reader -:class:`~MDAnalysis.topology.TPRParser.TPRParser` is built. - -.. automodule:: MDAnalysis.topology.tpr - -.. automodule:: MDAnalysis.topology.tpr.setting - :members: - :undoc-members: - -.. automodule:: MDAnalysis.topology.tpr.obj - :members: - :undoc-members: - -.. automodule:: MDAnalysis.topology.tpr.utils - :members: - :undoc-members: +=============================================== + Utility functions for the TPR topology parser +=============================================== + +The :mod:`MDAnalysis.topology.tpr` module contains classes and +functions on which the Gromacs TPR topology reader +:class:`~MDAnalysis.topology.TPRParser.TPRParser` is built. + +.. automodule:: MDAnalysis.topology.tpr + +.. automodule:: MDAnalysis.topology.tpr.setting + :members: + :undoc-members: + +.. automodule:: MDAnalysis.topology.tpr.obj + :members: + :undoc-members: + +.. automodule:: MDAnalysis.topology.tpr.utils + :members: + :undoc-members: diff --git a/package/doc/sphinx/source/documentation_pages/topology_modules.rst b/package/doc/sphinx/source/documentation_pages/topology_modules.rst index e1f818adabf..ff2148c4018 100644 --- a/package/doc/sphinx/source/documentation_pages/topology_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/topology_modules.rst @@ -1,64 +1,64 @@ -.. Contains the formatted docstrings from the topology modules located in 'mdanalysis/MDAnalysis/topology' - -************************** -Topology modules -************************** - -The topology module contains the functions to read topology -files. MDAnalysis uses topology files to identify atoms and bonds -between the atoms. It can use topology files from MD packages such as -CHARMM's and NAMD's PSF format or Amber's PRMTOP files. In addition, -it can also glean atom information from single frame coordinate files -such the PDB, CRD, or PQR formats (see the :ref:`Supported topology -formats`). - -Typically, MDAnalysis recognizes formats by the file extension and -hence most users probably do not need to concern themselves with -classes and functions described here. However, if MDAnalysis does not -properly recognize a file format then a user can explicitly set the -topology file format in the *topology_format* keyword argument to -:class:`~MDAnalysis.core.universe.Universe`. - -.. rubric:: Topology formats - -.. toctree:: - :maxdepth: 1 - - topology/init - topology/CRDParser - topology/DLPolyParser - topology/DMSParser - topology/FHIAIMSParser - topology/GMSParser - topology/GROParser - topology/GSDParser - topology/HoomdXMLParser - topology/ITPParser - topology/LAMMPSParser - topology/MinimalParser - topology/MMTFParser - topology/MOL2Parser - topology/PDBParser - topology/ExtendedPDBParser - topology/PDBQTParser - topology/PQRParser - topology/PSFParser - topology/TOPParser - topology/TPRParser - topology/TXYZParser - topology/XYZParser - -.. rubric:: Topology core modules - -The remaining pages are primarily of interest to developers as they -contain functions and classes that are used in the implementation of -the topology readers. - -.. toctree:: - :maxdepth: 1 - - topology/base - topology/core - topology/tpr_util - topology/guessers - topology/tables +.. Contains the formatted docstrings from the topology modules located in 'mdanalysis/MDAnalysis/topology' + +************************** +Topology modules +************************** + +The topology module contains the functions to read topology +files. MDAnalysis uses topology files to identify atoms and bonds +between the atoms. It can use topology files from MD packages such as +CHARMM's and NAMD's PSF format or Amber's PRMTOP files. In addition, +it can also glean atom information from single frame coordinate files +such the PDB, CRD, or PQR formats (see the :ref:`Supported topology +formats`). + +Typically, MDAnalysis recognizes formats by the file extension and +hence most users probably do not need to concern themselves with +classes and functions described here. However, if MDAnalysis does not +properly recognize a file format then a user can explicitly set the +topology file format in the *topology_format* keyword argument to +:class:`~MDAnalysis.core.universe.Universe`. + +.. rubric:: Topology formats + +.. toctree:: + :maxdepth: 1 + + topology/init + topology/CRDParser + topology/DLPolyParser + topology/DMSParser + topology/FHIAIMSParser + topology/GMSParser + topology/GROParser + topology/GSDParser + topology/HoomdXMLParser + topology/ITPParser + topology/LAMMPSParser + topology/MinimalParser + topology/MMTFParser + topology/MOL2Parser + topology/PDBParser + topology/ExtendedPDBParser + topology/PDBQTParser + topology/PQRParser + topology/PSFParser + topology/TOPParser + topology/TPRParser + topology/TXYZParser + topology/XYZParser + +.. rubric:: Topology core modules + +The remaining pages are primarily of interest to developers as they +contain functions and classes that are used in the implementation of +the topology readers. + +.. toctree:: + :maxdepth: 1 + + topology/base + topology/core + topology/tpr_util + topology/guessers + topology/tables diff --git a/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst b/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst index 425762bb594..3f644710496 100644 --- a/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst +++ b/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst @@ -1,275 +1,275 @@ -.. Contains the formatted docstrings for the transformations located in 'mdanalysis/MDAnalysis/transformations' -.. _transformations: - -********************************************************* -Trajectory transformations ("on-the-fly" transformations) -********************************************************* - -.. module:: MDAnalysis.transformations - -In MDAnalysis, a *transformation* is a function/function-like class -that modifies the data for the current :class:`Timestep` and returns the -:class:`Timestep`. For instance, coordinate transformations, such as -PBC corrections and molecule fitting are often required for some -analyses and visualization. Transformation functions -(``transformation_1`` and ``transformation_2`` in the following -example) can be called by the user for any given :class:`Timestep` of -the trajectory, - -.. code-block:: python - - u = MDAnalysis.Universe(topology, trajectory) - - for ts in u.trajectory: - ts = transformation_2(transformation_1(ts)) - -where they change the coordinates of the timestep ``ts`` in -place. There is nothing special about these transformations except -that they have to be written in such a way that they change the -:class:`Timestep` in place. - -As described under :ref:`workflows`, multiple transformations can be -grouped together and associated with a trajectory so that the -trajectory is **transformed on-the-fly**, i.e., the data read from the -trajectory file will be changed before it is made available in, say, -the :attr:`AtomGroup.positions` attribute. - -The submodule :mod:`MDAnalysis.transformations` contains a -collection of transformations (see :ref:`transformations-module`) that -can be immediately used but one can always write custom -transformations (see :ref:`custom-transformations`). - - -.. _workflows: - -Workflows ---------- - -Instead of manually applying transformations, it is much more -convenient to associate a whole *workflow* of transformations with a -trajectory and have the transformations be called automatically. - -A workflow is a sequence (tuple or list) of transformation functions -that will be applied in this order. For example, - -.. code-block:: python - - workflow = [transformation_1, transformation_2] - -would effectively result in - -.. code-block:: python - - ts = transformation_2(transformation_1(ts)) - -for every time step in the trajectory. - -One can add a workflow using the -:meth:`Universe.trajectory.add_transformations -` method -of a trajectory (where the list ``workflow`` is taken from the example -above), - -.. code-block:: python - - u.trajectory.add_transformations(*workflow) - -or upon :class:`Universe ` -creation using the keyword argument `transformations`: - -.. code-block:: python - - u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) - -Note that in these two cases, the workflow cannot be changed after having -being added. - - -.. _custom-transformations: - -Creating transformations ------------------------- - -A simple *transformation* can also be a function that takes a -:class:`~MDAnalysis.coordinates.base.Timestep` as input, modifies it, and -returns it. If it takes no other arguments but a :class:`Timestep` -can be defined as the following example: - -.. code-block:: python - - def up_by_2(ts): - """ - Translate all coordinates by 2 angstroms up along the Z dimension. - """ - ts.positions = ts.positions + np.array([0, 0, 2], dtype=np.float32) - return ts - -If the transformation requires other arguments besides the :class:`Timestep`, -the following two methods can be used to create such transformation: - - -.. _custom-transformations-class: - -Creating complex transformation classes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is implemented by inheriting from -:class:`MDAnalysis.transformations.base.TransformationBase`, -which defines :func:`__call__` for the transformation class -and can be applied directly to a :class:`Timestep`. :func:`_transform` has to -be defined and include the operations on the :class:`MDAnalysis.coordinates.base.Timestep`. - -So, a transformation class can be roughly defined as follows: - -.. code-block:: python - - from MDAnalysis.transformations import TransformationBase - - class up_by_x_class(TransformationBase): - def __init__(self, distance): - self.distance = distance - - def _transform(self, ts): - ts.positions = ts.positions + np.array([0, 0, self.distance], dtype=np.float32) - return ts - -It is the default construction method in :mod:`MDAnalysis.transformations` -from release 2.0.0 onwards because it can be reliably serialized. -See :class:`MDAnalysis.transformations.translate` for a simple example. - - -.. _custom-transformations-closure: - -Creating complex transformation closure functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Transformation can also be a wrapped function takes the :class:`Timestep` object as argument. -So in this case, a transformation function (closure) can be roughly defined as follows: - -.. code-block:: python - - def up_by_x_func(distance): - """ - Creates a transformation that will translate all coordinates by a given amount along the Z dimension. - """ - def wrapped(ts): - ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) - return ts - return wrapped - -An alternative to using a wrapped function is using partials from :mod:`functools`. The -above function can be written as: - -.. code-block:: python - - import functools - - def up_by_x(ts, distance): - ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) - return ts - - up_by_2 = functools.partial(up_by_x, distance=2) - -Although functions (closures) work as transformations, they are not used in -in MDAnalysis from release 2.0.0 onwards because they cannot be reliably -serialized and thus a :class:`Universe` with such transformations cannot be -used with common parallelization schemes (e.g., ones based on -:mod:`multiprocessing`). -For detailed descriptions about how to write a closure-style transformation, -please refer to MDAnalysis 1.x documentation. - -.. _transformations-module: - -Transformations in MDAnalysis ------------------------------ - -The module :mod:`MDAnalysis.transformations` contains transformations that can -be immediately used in your own :ref:`workflows`. In order to use -any of these transformations, the module must first be imported: - -.. code-block:: python - - import MDAnalysis.transformations - -A workflow can then be added to a trajectory as described above. Notably, -the parameter `max_threads` can be defined when creating a transformation -instance to limit the maximum threads. -(See :class:`MDAnalysis.transformations.base.TransformationBase` for more details) -Whether a specific transformation can be used along with parallel analysis -can be assessed by checking its -:attr:`~MDAnalysis.transformations.base.TransformationBase.parallelizable` -attribute. - -See :ref:`implemented-transformations` for more on the existing -transformations in :mod:`MDAnalysis.transformations`. - - -How to transformations ----------------------- - -Translating the coordinates of a single frame (although one would normally add -the transformation to a :ref:`workflow`, as shown in the subsequent -examples): - -.. code-block:: python - - u = MDAnalysis.Universe(topology, trajectory) - new_ts = MDAnalysis.transformations.translate([1,1,1])(u.trajectory.ts) - -Create a workflow and add it to the trajectory: - -.. code-block:: python - - u = MDAnalysis.Universe(topology, trajectory) - workflow = [MDAnalysis.transformations.translate([1,1,1]), - MDAnalysis.transformations.translate([1,2,3])] - u.trajectory.add_transformations(*workflow) - -Giving a workflow as a keyword argument when defining the universe: - -.. code-block:: python - - workflow = [MDAnalysis.transformations.translate([1,1,1]), - MDAnalysis.transformations.translate([1,2,3])] - u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) - - -.. _building-block-transformation: - -Building blocks for Transformation Classes ------------------------------------------- -Transformations normally ultilize the power of NumPy to get better performance -on array operations. However, when it comes to parallelism, NumPy will sometimes -oversubscribe the threads, either by hyper threading (when it uses OpenBlas backend), -or by working with other parallel engines (e.g. Dask). - -In MDAnalysis, we use `threadpoolctl `_ -inside :class:`~MDAnalysis.transformations.base.TransformationBase` to control the maximum threads for transformations. - -It is also possible to apply a global thread limit by setting the external environmental -varibale, e.g. :code:`OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 -BLIS_NUM_THREADS=1 python script.py`. Read more about parallelism and resource management -in `scikit-learn documentations `_. - -Users are advised to benchmark code because interaction between different -libraries can lead to sub-optimal performance with defaults. - -.. toctree:: - - ./transformations/base - -.. _implemented-transformations: - -Currently implemented transformations -------------------------------------- - -.. toctree:: - - ./transformations/translate - ./transformations/rotate - ./transformations/positionaveraging - ./transformations/fit - ./transformations/wrap - ./transformations/nojump - ./transformations/boxdimensions - +.. Contains the formatted docstrings for the transformations located in 'mdanalysis/MDAnalysis/transformations' +.. _transformations: + +********************************************************* +Trajectory transformations ("on-the-fly" transformations) +********************************************************* + +.. module:: MDAnalysis.transformations + +In MDAnalysis, a *transformation* is a function/function-like class +that modifies the data for the current :class:`Timestep` and returns the +:class:`Timestep`. For instance, coordinate transformations, such as +PBC corrections and molecule fitting are often required for some +analyses and visualization. Transformation functions +(``transformation_1`` and ``transformation_2`` in the following +example) can be called by the user for any given :class:`Timestep` of +the trajectory, + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory) + + for ts in u.trajectory: + ts = transformation_2(transformation_1(ts)) + +where they change the coordinates of the timestep ``ts`` in +place. There is nothing special about these transformations except +that they have to be written in such a way that they change the +:class:`Timestep` in place. + +As described under :ref:`workflows`, multiple transformations can be +grouped together and associated with a trajectory so that the +trajectory is **transformed on-the-fly**, i.e., the data read from the +trajectory file will be changed before it is made available in, say, +the :attr:`AtomGroup.positions` attribute. + +The submodule :mod:`MDAnalysis.transformations` contains a +collection of transformations (see :ref:`transformations-module`) that +can be immediately used but one can always write custom +transformations (see :ref:`custom-transformations`). + + +.. _workflows: + +Workflows +--------- + +Instead of manually applying transformations, it is much more +convenient to associate a whole *workflow* of transformations with a +trajectory and have the transformations be called automatically. + +A workflow is a sequence (tuple or list) of transformation functions +that will be applied in this order. For example, + +.. code-block:: python + + workflow = [transformation_1, transformation_2] + +would effectively result in + +.. code-block:: python + + ts = transformation_2(transformation_1(ts)) + +for every time step in the trajectory. + +One can add a workflow using the +:meth:`Universe.trajectory.add_transformations +` method +of a trajectory (where the list ``workflow`` is taken from the example +above), + +.. code-block:: python + + u.trajectory.add_transformations(*workflow) + +or upon :class:`Universe ` +creation using the keyword argument `transformations`: + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) + +Note that in these two cases, the workflow cannot be changed after having +being added. + + +.. _custom-transformations: + +Creating transformations +------------------------ + +A simple *transformation* can also be a function that takes a +:class:`~MDAnalysis.coordinates.base.Timestep` as input, modifies it, and +returns it. If it takes no other arguments but a :class:`Timestep` +can be defined as the following example: + +.. code-block:: python + + def up_by_2(ts): + """ + Translate all coordinates by 2 angstroms up along the Z dimension. + """ + ts.positions = ts.positions + np.array([0, 0, 2], dtype=np.float32) + return ts + +If the transformation requires other arguments besides the :class:`Timestep`, +the following two methods can be used to create such transformation: + + +.. _custom-transformations-class: + +Creating complex transformation classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is implemented by inheriting from +:class:`MDAnalysis.transformations.base.TransformationBase`, +which defines :func:`__call__` for the transformation class +and can be applied directly to a :class:`Timestep`. :func:`_transform` has to +be defined and include the operations on the :class:`MDAnalysis.coordinates.base.Timestep`. + +So, a transformation class can be roughly defined as follows: + +.. code-block:: python + + from MDAnalysis.transformations import TransformationBase + + class up_by_x_class(TransformationBase): + def __init__(self, distance): + self.distance = distance + + def _transform(self, ts): + ts.positions = ts.positions + np.array([0, 0, self.distance], dtype=np.float32) + return ts + +It is the default construction method in :mod:`MDAnalysis.transformations` +from release 2.0.0 onwards because it can be reliably serialized. +See :class:`MDAnalysis.transformations.translate` for a simple example. + + +.. _custom-transformations-closure: + +Creating complex transformation closure functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Transformation can also be a wrapped function takes the :class:`Timestep` object as argument. +So in this case, a transformation function (closure) can be roughly defined as follows: + +.. code-block:: python + + def up_by_x_func(distance): + """ + Creates a transformation that will translate all coordinates by a given amount along the Z dimension. + """ + def wrapped(ts): + ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) + return ts + return wrapped + +An alternative to using a wrapped function is using partials from :mod:`functools`. The +above function can be written as: + +.. code-block:: python + + import functools + + def up_by_x(ts, distance): + ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) + return ts + + up_by_2 = functools.partial(up_by_x, distance=2) + +Although functions (closures) work as transformations, they are not used in +in MDAnalysis from release 2.0.0 onwards because they cannot be reliably +serialized and thus a :class:`Universe` with such transformations cannot be +used with common parallelization schemes (e.g., ones based on +:mod:`multiprocessing`). +For detailed descriptions about how to write a closure-style transformation, +please refer to MDAnalysis 1.x documentation. + +.. _transformations-module: + +Transformations in MDAnalysis +----------------------------- + +The module :mod:`MDAnalysis.transformations` contains transformations that can +be immediately used in your own :ref:`workflows`. In order to use +any of these transformations, the module must first be imported: + +.. code-block:: python + + import MDAnalysis.transformations + +A workflow can then be added to a trajectory as described above. Notably, +the parameter `max_threads` can be defined when creating a transformation +instance to limit the maximum threads. +(See :class:`MDAnalysis.transformations.base.TransformationBase` for more details) +Whether a specific transformation can be used along with parallel analysis +can be assessed by checking its +:attr:`~MDAnalysis.transformations.base.TransformationBase.parallelizable` +attribute. + +See :ref:`implemented-transformations` for more on the existing +transformations in :mod:`MDAnalysis.transformations`. + + +How to transformations +---------------------- + +Translating the coordinates of a single frame (although one would normally add +the transformation to a :ref:`workflow`, as shown in the subsequent +examples): + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory) + new_ts = MDAnalysis.transformations.translate([1,1,1])(u.trajectory.ts) + +Create a workflow and add it to the trajectory: + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory) + workflow = [MDAnalysis.transformations.translate([1,1,1]), + MDAnalysis.transformations.translate([1,2,3])] + u.trajectory.add_transformations(*workflow) + +Giving a workflow as a keyword argument when defining the universe: + +.. code-block:: python + + workflow = [MDAnalysis.transformations.translate([1,1,1]), + MDAnalysis.transformations.translate([1,2,3])] + u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) + + +.. _building-block-transformation: + +Building blocks for Transformation Classes +------------------------------------------ +Transformations normally ultilize the power of NumPy to get better performance +on array operations. However, when it comes to parallelism, NumPy will sometimes +oversubscribe the threads, either by hyper threading (when it uses OpenBlas backend), +or by working with other parallel engines (e.g. Dask). + +In MDAnalysis, we use `threadpoolctl `_ +inside :class:`~MDAnalysis.transformations.base.TransformationBase` to control the maximum threads for transformations. + +It is also possible to apply a global thread limit by setting the external environmental +varibale, e.g. :code:`OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 +BLIS_NUM_THREADS=1 python script.py`. Read more about parallelism and resource management +in `scikit-learn documentations `_. + +Users are advised to benchmark code because interaction between different +libraries can lead to sub-optimal performance with defaults. + +.. toctree:: + + ./transformations/base + +.. _implemented-transformations: + +Currently implemented transformations +------------------------------------- + +.. toctree:: + + ./transformations/translate + ./transformations/rotate + ./transformations/positionaveraging + ./transformations/fit + ./transformations/wrap + ./transformations/nojump + ./transformations/boxdimensions + diff --git a/package/doc/sphinx/source/documentation_pages/transformations/base.rst b/package/doc/sphinx/source/documentation_pages/transformations/base.rst index d5a0377540d..fc6643ffa5d 100644 --- a/package/doc/sphinx/source/documentation_pages/transformations/base.rst +++ b/package/doc/sphinx/source/documentation_pages/transformations/base.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.transformations.base +.. automodule:: MDAnalysis.transformations.base diff --git a/package/doc/sphinx/source/documentation_pages/transformations/boxdimensions.rst b/package/doc/sphinx/source/documentation_pages/transformations/boxdimensions.rst index e40789ae657..9e9aa9b0105 100644 --- a/package/doc/sphinx/source/documentation_pages/transformations/boxdimensions.rst +++ b/package/doc/sphinx/source/documentation_pages/transformations/boxdimensions.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.transformations.boxdimensions +.. automodule:: MDAnalysis.transformations.boxdimensions diff --git a/package/doc/sphinx/source/documentation_pages/transformations/nojump.rst b/package/doc/sphinx/source/documentation_pages/transformations/nojump.rst index d1543ca4cb7..2f66123a446 100644 --- a/package/doc/sphinx/source/documentation_pages/transformations/nojump.rst +++ b/package/doc/sphinx/source/documentation_pages/transformations/nojump.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.transformations.nojump +.. automodule:: MDAnalysis.transformations.nojump diff --git a/package/doc/sphinx/source/documentation_pages/transformations/positionaveraging.rst b/package/doc/sphinx/source/documentation_pages/transformations/positionaveraging.rst index 69c94d83640..7ee16ea9b8c 100644 --- a/package/doc/sphinx/source/documentation_pages/transformations/positionaveraging.rst +++ b/package/doc/sphinx/source/documentation_pages/transformations/positionaveraging.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.transformations.positionaveraging +.. automodule:: MDAnalysis.transformations.positionaveraging diff --git a/package/doc/sphinx/source/documentation_pages/units.rst b/package/doc/sphinx/source/documentation_pages/units.rst index dfa08e918f5..35737e9e56e 100644 --- a/package/doc/sphinx/source/documentation_pages/units.rst +++ b/package/doc/sphinx/source/documentation_pages/units.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.units - +.. automodule:: MDAnalysis.units + diff --git a/package/doc/sphinx/source/documentation_pages/version.rst b/package/doc/sphinx/source/documentation_pages/version.rst index a0076f55aba..aecc36fbf5d 100644 --- a/package/doc/sphinx/source/documentation_pages/version.rst +++ b/package/doc/sphinx/source/documentation_pages/version.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.version +.. automodule:: MDAnalysis.version diff --git a/package/doc/sphinx/source/documentation_pages/visualization/streamlines.rst b/package/doc/sphinx/source/documentation_pages/visualization/streamlines.rst index 036aeb55c08..4102b67c438 100644 --- a/package/doc/sphinx/source/documentation_pages/visualization/streamlines.rst +++ b/package/doc/sphinx/source/documentation_pages/visualization/streamlines.rst @@ -1 +1 @@ -.. automodule:: MDAnalysis.visualization.streamlines +.. automodule:: MDAnalysis.visualization.streamlines diff --git a/package/doc/sphinx/source/documentation_pages/visualization/streamlines_3D.rst b/package/doc/sphinx/source/documentation_pages/visualization/streamlines_3D.rst index 60f3a584d04..2d167949224 100644 --- a/package/doc/sphinx/source/documentation_pages/visualization/streamlines_3D.rst +++ b/package/doc/sphinx/source/documentation_pages/visualization/streamlines_3D.rst @@ -1,2 +1,2 @@ -.. automodule:: MDAnalysis.visualization.streamlines_3D - +.. automodule:: MDAnalysis.visualization.streamlines_3D + diff --git a/package/doc/sphinx/source/documentation_pages/visualization_modules.rst b/package/doc/sphinx/source/documentation_pages/visualization_modules.rst index 54a11b7125f..6d52804862f 100644 --- a/package/doc/sphinx/source/documentation_pages/visualization_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/visualization_modules.rst @@ -1,37 +1,37 @@ -.. Contains the formatted docstrings from the visualization modules located in 'mdanalysis/MDAnalysis/visualization' - -********************* -Visualization modules -********************* - -The :mod:`MDAnalysis.visualization` namespace contains code to carry out -analyses which return data that is specifically-tailored for visualization. - -Please see the individual module documentation for additional references and -citation information. - -These modules are not imported by default; in order to use them one has to -import them from :mod:`MDAnalysis.visualization`, for instance: :: - - import MDAnalysis.visualization.streamlines - -.. Note:: - - Some of the modules require additional Python packages such as matplotlib_ or - scipy_. - -.. _matplotlib: http://matplotlib.org -.. _scipy: https://scipy.org/ - - -Visualization of Lipid Flow -=========================== - -.. toctree:: - :maxdepth: 1 - - visualization/streamlines - visualization/streamlines_3D - - - +.. Contains the formatted docstrings from the visualization modules located in 'mdanalysis/MDAnalysis/visualization' + +********************* +Visualization modules +********************* + +The :mod:`MDAnalysis.visualization` namespace contains code to carry out +analyses which return data that is specifically-tailored for visualization. + +Please see the individual module documentation for additional references and +citation information. + +These modules are not imported by default; in order to use them one has to +import them from :mod:`MDAnalysis.visualization`, for instance: :: + + import MDAnalysis.visualization.streamlines + +.. Note:: + + Some of the modules require additional Python packages such as matplotlib_ or + scipy_. + +.. _matplotlib: http://matplotlib.org +.. _scipy: https://scipy.org/ + + +Visualization of Lipid Flow +=========================== + +.. toctree:: + :maxdepth: 1 + + visualization/streamlines + visualization/streamlines_3D + + + diff --git a/package/doc/sphinx/source/index.rst b/package/doc/sphinx/source/index.rst index 9367a0bad89..d5d2d83852e 100644 --- a/package/doc/sphinx/source/index.rst +++ b/package/doc/sphinx/source/index.rst @@ -1,147 +1,147 @@ -.. -*- 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: https://www.lammps.org/ -.. _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/fetchers_modules - ./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` - +.. -*- 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: https://www.lammps.org/ +.. _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/fetchers_modules + ./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` + diff --git a/package/doc/sphinx/source/references.bib b/package/doc/sphinx/source/references.bib index 8fe33a1b64d..397de47c59c 100644 --- a/package/doc/sphinx/source/references.bib +++ b/package/doc/sphinx/source/references.bib @@ -1,809 +1,809 @@ -@book{Gray1984, - address = {Oxford ; New York}, - series = {The {International} series of monographs on chemistry}, - title = {Theory of molecular fluids}, - isbn = {978-0-19-855602-2}, - number = {9}, - publisher = {Oxford University Press}, - author = {Gray, C. G. and Gubbins, Keith E. and Joslin, C. G.}, - year = {1984}, - keywords = {Fluids, Molecular theory}, -} - -@article{MichaudAgrawal2011, - author = {Michaud-Agrawal, Naveen and Denning, Elizabeth J. and Woolf, Thomas B. and Beckstein, Oliver}, - title = {MDAnalysis: A toolkit for the analysis of molecular dynamics simulations}, - journal = {Journal of Computational Chemistry}, - volume = {32}, - number = {10}, - pages = {2319-2327}, - doi = {https://doi.org/10.1002/jcc.21787}, - year = {2011} -} - -@article{Gowers2016, - title = {{MDAnalysis}: {A} {Python} {Package} for the {Rapid} {Analysis} of {Molecular} {Dynamics} {Simulations}}, - shorttitle = {{MDAnalysis}}, - url = {https://conference.scipy.org/proceedings/scipy2016/oliver_beckstein.html}, - doi = {10.25080/Majora-629e541a-00e}, - urldate = {2020-02-05}, - journal = {Proceedings of the 15th Python in Science Conference}, - author = {Gowers, Richard J. and Linke, Max and Barnoud, Jonathan and Reddy, Tyler J. E. and Melo, Manuel N. and Seyler, Sean L. and Domański, Jan and Dotson, David L. and Buchoux, Sébastien and Kenney, Ian M. and Beckstein, Oliver}, - year = {2016}, - note = {00152}, - pages = {98--105}, -} - -@article{Alt1995, - author = {Alt, Helmut and Godau, Michael}, - title = {Computing the Frechet distance between two polygonal curves}, - journal = {International Journal of Computational Geometry \& Applications}, - volume = {05}, - number = {01n02}, - pages = {75-91}, - year = {1995}, - doi = {10.1142/S0218195995000064} -} - -@article{ArayaSecchi2014, - author = {Araya-Secchi, Raul and Perez-Acle, Tomas and Kang, Seung-gu and Huynh, Tien and Bernardin, Alejandro and Escalona, Yerko and Garate, Jose-Antonio and Mart{\'\i}nez, Agustin D. and Garc{\'\i}a, Isaac E. and S{\'a}ez, Juan C. and Zhou, Ruhong}, - doi = {10.1016/j.bpj.2014.05.037}, - journal = {Biophysical Journal}, - Number = {3}, - Pages = {599--612}, - Publisher = {Elsevier}, - Title = {Characterization of a Novel Water Pocket Inside the Human Cx26 Hemichannel Structure}, - Volume = {107}, - year = {2014} -} - -@article{BerkHess2002, - title = {Convergence of sampling in protein simulations}, - author = {Hess, Berk}, - journal = {Phys. Rev. E}, - volume = {65}, - issue = {3}, - pages = {031910}, - numpages = {10}, - year = {2002}, - month = {Mar}, - publisher = {American Physical Society}, - doi = {10.1103/PhysRevE.65.031910} -} - -@article{Best2013, - author = {Robert B. Best and Gerhard Hummer and William A. Eaton }, - title = {Native contacts determine protein folding mechanisms in atomistic simulations}, - journal = {Proceedings of the National Academy of Sciences}, - volume = {110}, - number = {44}, - pages = {17874-17879}, - year = {2013}, - doi = {10.1073/pnas.1311599110} -} - -@article{Brodka1994, - author = { Aleksander Bródka }, - title = {Diffusion in restricted volume}, - journal = {Molecular Physics}, - volume = {82}, - number = {5}, - pages = {1075-1078}, - year = {1994}, - publisher = {Taylor & Francis}, - doi = {10.1080/00268979400100764} -} - -@article{Bulow2020, - author = {von Bülow,Sören and Bullerjahn,Jakob Tómas and Hummer,Gerhard }, - title = {Systematic errors in diffusion coefficients from long-time molecular dynamics simulations at constant pressure}, - journal = {The Journal of Chemical Physics}, - volume = {153}, - number = {2}, - pages = {021101}, - year = {2020}, - doi = {10.1063/5.0008316} -} - -@article{Chang2003, - author = {Chang, Chia-En and Potter, Michael J. and Gilson, Michael K.}, - title = {Calculation of Molecular Configuration Integrals}, - journal = {The Journal of Physical Chemistry B}, - volume = {107}, - number = {4}, - pages = {1048-1055}, - year = {2003}, - doi = {10.1021/jp027149c} -} - -@Article{Chavent2014, - author = {Chavent, Matthieu and Reddy, Tyler and Goose, Joseph and Dahl, Anna Caroline E. and Stone, John E. and Jobard, Bruno and Sansom, Mark S. P.}, - title = {Methodologies for the analysis of instantaneous lipid diffusion in md simulations of large membrane systems}, - journal = {Faraday Discuss.}, - year = {2014}, - volume = {169}, - pages = {455-475}, - publisher = {The Royal Society of Chemistry}, - doi = {10.1039/C3FD00145H} -} - -@article{Clementi2011, - author = {Rohrdanz,Mary A. and Zheng,Wenwei and Maggioni,Mauro and Clementi,Cecilia }, - title = {Determination of reaction coordinates via locally scaled diffusion map}, - journal = {The Journal of Chemical Physics}, - volume = {134}, - number = {12}, - pages = {124116}, - year = {2011}, - doi = {10.1063/1.3569857} -} - -@article{Denning2011 - author = {Denning, Elizabeth J. and Priyakumar, U. Deva and Nilsson, Lennart and Mackerell Jr., Alexander D.}, - title = {Impact of 2-hydroxyl sampling on the conformational properties of RNA: Update of the CHARMM all-atom additive force field for RNA}, - journal = {Journal of Computational Chemistry}, - year = {2011}, - volume = {32}, - number = {9}, - pages = {1929-1943}, - doi = {https://doi.org/10.1002/jcc.21777} -} - -@article{Denning2012, - author = {Denning, Elizabeth J. and MacKerell, Alexander D.}, - title = {Intrinsic Contribution of the 2{\'}-Hydroxyl to RNA Conformational Heterogeneity}, - journal = {Journal of the American Chemical Society}, - volume = {134}, - number = {5}, - pages = {2800-2806}, - year = {2012}, - doi = {10.1021/ja211328g}, - note ={PMID: 22242623} -} - -@article{EiterMannila1994, - author = {Eiter, Thomas and Mannila, Heikki}, - year = {1994}, - month = {05}, - journal = {}, - title = {Computing Discrete Frechet Distance} -} - -@article{EiterMannila1997, - author = {Eiter, Thomas and Mannila, Heikki}, - doi = {10.1007/s002360050075}, - journal = {Acta Informatica}, - Number = {2}, - Pages = {109--133}, - Title = {Distance measures for point sets and their computation}, - Volume = {34}, - year = {1997} -} - -@article{Ferguson2011, - author = {Andrew L. Ferguson and Athanassios Z. Panagiotopoulos and Ioannis G. Kevrekidis and Pablo G. Debenedetti}, - title = {Nonlinear dimensionality reduction in molecular simulation: The diffusion map approach}, - journal = {Chemical Physics Letters}, - volume = {509}, - number = {1}, - pages = {1-11}, - year = {2011}, - issn = {0009-2614}, - doi = {https://doi.org/10.1016/j.cplett.2011.04.066}, - url = {https://www.sciencedirect.com/science/article/pii/S0009261411004957} -} - -@article{Franklin2007, - author = {Franklin, Joel and Koehl, Patrice and Doniach, Sebastian and Delarue, Marc}, - title = "{MinActionPath: maximum likelihood trajectory for large-scale structural transitions in a coarse-grained locally harmonic energy landscape}", - journal = {Nucleic Acids Research}, - volume = {35}, - number = {suppl_2}, - pages = {W477-W482}, - year = {2007}, - doi = {10.1093/nar/gkm342} -} - -@article{Frechet1906, - author = {Frèchet, M. Maurice}, - doi = {10.1007/BF03018603}, - journal = {Rendiconti del Circolo Matematico di Palermo (1884-1940)}, - Number = {1}, - Pages = {1--72}, - Title = {Sur quelques points du calcul fonctionnel}, - Volume = {22}, - year = {1906} -} - -@article{Gowers2015, - author = {Gowers,Richard J. and Carbone,Paola }, - title = {A multiscale approach to model hydrogen bonding: The case of polyamide}, - journal = {The journal of Chemical Physics}, - volume = {142}, - number = {22}, - pages = {224907}, - year = {2015}, - doi = {10.1063/1.4922445} -} - -@article{Gregoret1991, - author = {Gregoret, Lydia M. and Rader, Stephen D. and Fletterick, Robert J. and Cohen, Fred E.}, - title = {Hydrogen bonds involving sulfur atoms in proteins}, - journal = {Proteins: Structure, Function, and Bioinformatics}, - year = {1991}, - volume = {9}, - number = {2}, - pages = {99-107}, - doi = {https://doi.org/10.1002/prot.340090204} -} - -@article{Grigera1995, - author = {Grigera, J. Raul and Kalko, Susana G. and Fischbarg, Jorge}, - title = {Wall−Water Interface. A Molecular Dynamics Study}, - journal = {Langmuir}, - volume = {12}, - number = {1}, - pages = {154-158}, - year = {1996}, - doi = {10.1021/la9408681} -} - -@article{Gu2019, - author = {Gu, Ruo-Xu and Baoukina, Svetlana and Tieleman, D. Peter}, - title = {Cholesterol Flip-Flop in Heterogeneous Membranes}, - journal = {Journal of Chemical Theory and Computation}, - volume = {15}, - number = {3}, - pages = {2064-2070}, - year = {2019}, - doi = {10.1021/acs.jctc.8b00933} -} - -@article{Hall2007, - author = {Hall, Benjamin A. and Kaye, Samantha L. and Pang, Andy and Perera, Rafael and Biggin, Philip C.}, - title = {Characterization of Protein Conformational States by Normal-Mode Frequencies}, - journal = {Journal of the American Chemical Society}, - volume = {129}, - number = {37}, - pages = {11394-11401}, - year = {2007}, - doi = {10.1021/ja071797y}, - note ={PMID: 17715919} -} - -@article{Hikiri2016, - author = {Hikiri, Simon and Yoshidome, Takashi and Ikeguchi, Mitsunori}, - title = {Computational Methods for Configurational Entropy Using Internal and Cartesian Coordinates}, - journal = {Journal of Chemical Theory and Computation}, - volume = {12}, - number = {12}, - pages = {5990-6000}, - year = {2016}, - doi = {10.1021/acs.jctc.6b00563}, - note ={PMID: 27951672} -} - -@article{Janin1978, - author = {Joël Janin and Shoshanna Wodak and Michael Levitt and Bernard Maigret}, - title = {Conformation of amino acid side-chains in proteins}, - journal = {Journal of Molecular Biology}, - volume = {125}, - number = {3}, - pages = {357-386}, - year = {1978}, - issn = {0022-2836}, - doi = {https://doi.org/10.1016/0022-2836(78)90408-4}, - url = {https://www.sciencedirect.com/science/article/pii/0022283678904084} -} - -@article{Jorgensen1998, - author = {Jorgensen, William L. and Jenson, Corky}, - title = {Temperature dependence of TIP3P, SPC, and TIP4P water from NPT Monte Carlo simulations: Seeking temperatures of maximum density}, - journal = {Journal of Computational Chemistry}, - year = {1998}, - volume = {19}, - number = {10}, - pages = {1179-1186}, - doi = {https://doi.org/10.1002/(SICI)1096-987X(19980730)19:10<1179::AID-JCC6>3.0.CO;2-J} -} - -@article{Coifman-Lafon, - author = {Ronald R. Coifman and Stéphane Lafon}, - title = {Diffusion maps}, - journal = {Applied and Computational Harmonic Analysis}, - volume = {21}, - number = {1}, - pages = {5-30}, - year = {2006}, - note = {Special Issue: Diffusion Maps and Wavelets}, - issn = {1063-5203}, - doi = {https://doi.org/10.1016/j.acha.2006.04.006}, - url = {https://www.sciencedirect.com/science/article/pii/S1063520306000546} -} - -@article{LindorffLarsen2009, - doi = {10.1371/journal.pone.0004203}, - author = {Lindorff-Larsen, Kresten AND Ferkinghoff-Borg, Jesper}, - journal = {PLOS ONE}, - publisher = {Public Library of Science}, - title = {Similarity Measures for Protein Ensembles}, - year = {2009}, - month = {01}, - volume = {4}, - pages = {1-13}, - number = {1} -} - -@article{Liu2004 - author = {Liu, Pu and Harder, Edward and Berne, B. J.}, - title = {On the Calculation of Diffusion Coefficients in Confined Fluids and Interfaces with an Application to the Liquid−Vapor Interface of Water}, - journal = {The Journal of Physical Chemistry B}, - volume = {108}, - number = {21}, - pages = {6595-6602}, - year = {2004}, - doi = {10.1021/jp0375057} -} - -@article{Lovell2003, - author = {Lovell, Simon C. and Davis, Ian W. and Arendall III, W. Bryan and de Bakker, Paul I. W. and Word, J. Michael and Prisant, Michael G. and Richardson, Jane S. and Richardson, David C.}, - title = {Structure validation by C$/alpha$ geometry: $\psi$,$\phi$ and C$\beta$ deviation}, - journal = {Proteins: Structure, Function, and Bioinformatics}, - year = {2003}, - volume = {50}, - number = {3}, - pages = {437-450}, - doi = {https://doi.org/10.1002/prot.10286} -} - -@article{Lu2003, - author = {Lu, Xiang‐Jun and Olson, Wilma K.}, - title = "{3DNA: a software package for the analysis, rebuilding and visualization of three‐dimensional nucleic acid structures}", - journal = {Nucleic Acids Research}, - volume = {31}, - number = {17}, - pages = {5108-5121}, - year = {2003}, - month = {09}, - issn = {0305-1048}, - doi = {10.1093/nar/gkg680} -} - -@article{Lu2008, - author = {Lu, Xiang-Jun and Olson, Wilma K}, - doi = {10.1038/nprot.2008.104}, - Isbn = {1750-2799}, - journal = {Nature Protocols}, - Number = {7}, - Pages = {1213--1227}, - Title = {3DNA: a versatile, integrated software system for the analysis, rebuilding and visualization of three-dimensional nucleic-acid structures}, - Volume = {3}, - year = {2008}, -} - -@article{Lundborg2014, - author = {Lundborg, Magnus and Apostolov, Rossen and Spångberg, Daniel and Gärdenäs, Anders and van der Spoel, David and Lindahl, Erik}, - title = {An efficient and extensible format, library, and API for binary trajectory data from molecular simulations}, - journal = {Journal of Computational Chemistry}, - volume = {35}, - number = {3}, - pages = {260-269}, - doi = {https://doi.org/10.1002/jcc.23495}, - url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.23495}, - year = {2014} -} - -@article{Maginn2019, - author = {Maginn, Edward J. and Messerly, Richard A. and Carlson, Daniel J. and Roe, Daniel R. and Elliot, J. Richard}, - title = {Best Practices for Computing Transport Properties Self-Diffusivity and Viscosity from Equilibrium Molecular Dynamics}, - volume = {1}, - doi = {10.33011/livecoms.1.1.6324}, - number = {1}, - journal = {Living Journal of Computational Molecular Science}, - year = {2018}, - month = {Dec.}, - pages = {6324}, - url = {https://livecomsjournal.org/index.php/livecoms/article/view/v1i1e6324} -} - -@article{Milischuk2011, - author = {Milischuk,Anatoli A. and Ladanyi,Branka M. }, - title = {Structure and dynamics of water confined in silica nanopores}, - journal = {The Journal of Chemical Physics}, - volume = {135}, - number = {17}, - pages = {174709}, - year = {2011}, - doi = {10.1063/1.3657408} -} - -@article{Minh2020, - author = {Minh, David D. L.}, - title = {Alchemical Grid Dock (AlGDock): Binding Free Energy Calculations between Flexible Ligands and Rigid Receptors}, - journal = {Journal of Computational Chemistry}, - year = {2020}, - volume = {41}, - number = {7}, - pages = {715-730}, - doi = {https://doi.org/10.1002/jcc.26036} -} - -@article{Mull2018, - author = "Henry Mull and Oliver Beckstein", - title = "{Technical Report: - SPIDAL Summer REU 2018 Dihedral Analysis in MDAnalysis}", - year = "2018", - month = "8", - journal = {}, - url ="https://figshare.com/articles/journal_contribution/Technical_Report_SPIDAL_Summer_REU_2018_Dihedral_Analysis_in_MDAnalysis/6957296", - doi = "10.6084/m9.figshare.6957296.v1" -} - -@article{Ramachandran1963, - author = {G.N. Ramachandran and C. Ramakrishnan and V. Sasisekharan}, - title = {Stereochemistry of polypeptide chain configurations}, - journal = {Journal of Molecular Biology}, - volume = {7}, - number = {1}, - pages = {95-99}, - year = {1963}, - issn = {0022-2836}, - doi = {https://doi.org/10.1016/S0022-2836(63)80023-6}, - url = {https://www.sciencedirect.com/science/article/pii/S0022283663800236} -} - -@article{Rapaport1983, - author = { D.C. Rapaport}, - title = {Hydrogen bonds in water}, - journal = {Molecular Physics}, - volume = {50}, - number = {5}, - pages = {1151-1162}, - year = {1983}, - publisher = {Taylor & Francis}, - doi = {10.1080/00268978300102931} -} - -@article{Seyler2015, - doi = {10.1371/journal.pcbi.1004568}, - author = {Seyler, Sean L. AND Kumar, Avishek AND Thorpe, M. F. AND Beckstein, Oliver}, - journal = {PLOS Computational Biology}, - publisher = {Public Library of Science}, - title = {Path Similarity Analysis: A Method for Quantifying Macromolecular Pathways}, - year = {2015}, - month = {10}, - volume = {11}, - pages = {1-37}, - number = {10} -} - -@article{Smart1993, - title = {The pore dimensions of gramicidin A}, - journal = {Biophysical Journal}, - volume = {65}, - number = {6}, - pages = {2455-2460}, - year = {1993}, - issn = {0006-3495}, - doi = {https://doi.org/10.1016/S0006-3495(93)81293-1}, - author = {O.S. Smart and J.M. Goodfellow and B.A. Wallace} -} - -@article{Smart1996, - title = {HOLE: A program for the analysis of the pore dimensions of ion channel structural models}, - journal = {Journal of Molecular Graphics}, - volume = {14}, - number = {6}, - pages = {354-360}, - year = {1996}, - issn = {0263-7855}, - doi = {https://doi.org/10.1016/S0263-7855(97)00009-X}, - author = {Oliver S. Smart and Joseph G. Neduvelil and Xiaonan Wang and B.A. Wallace and Mark S.P. Sansom} -} - -@article{Stelzl2014, - title = {Flexible Gates Generate Occluded Intermediates in the Transport Cycle of LacY}, - journal = {Journal of Molecular Biology}, - volume = {426}, - number = {3}, - pages = {735-751}, - year = {2014}, - issn = {0022-2836}, - doi = {https://doi.org/10.1016/j.jmb.2013.10.024}, - author = {Lukas S. Stelzl and Philip W. Fowler and Mark S.P. Sansom and Oliver Beckstein}, - id = {Stelzl _et_ al.} -} - -@article{Taha2015, - author={Taha, Abdel Aziz and Hanbury, Allan}, - journal={IEEE Transactions on Pattern Analysis and Machine Intelligence}, - title={An Efficient Algorithm for Calculating the Exact Hausdorff Distance}, - year={2015}, - volume={37}, - number={11}, - pages={2153-2163}, - doi={10.1109/TPAMI.2015.2408351} -} - -@article{Theobald2005, -author = "Theobald, Douglas L.", -title = "{Rapid calculation of RMSDs using a quaternion-based characteristic polynomial}", -journal = "Acta Crystallographica Section A", -year = "2005", -volume = "61", -number = "4", -pages = "478--480", -month = "Jul", -doi = {10.1107/S0108767305015266} -} - -@article{Tiberti2015, - doi = {10.1371/journal.pcbi.1004415}, - author = {Tiberti, Matteo AND Papaleo, Elena AND Bengtsen, Tone AND Boomsma, Wouter AND Lindorff-Larsen, Kresten}, - journal = {PLOS Computational Biology}, - publisher = {Public Library of Science}, - title = {ENCORE: Software for Quantitative Ensemble Comparison}, - year = {2015}, - month = {10}, - volume = {11}, - pages = {1-16}, - number = {10} -} - -@article{Welford1962, - author = { B. P. Welford}, - title = {Note on a Method for Calculating Corrected Sums of Squares and Products}, - journal = {Technometrics}, - volume = {4}, - number = {3}, - pages = {419-420}, - year = {1962}, - publisher = {Taylor & Francis}, - doi = {10.1080/00401706.1962.10490022} -} - -@article{Yeh1999, - author = {Yeh, Yu-ling and Mou, Chung-Yuan}, - title = {Orientational Relaxation Dynamics of Liquid Water Studied by Molecular Dynamics Simulation}, - journal = {The Journal of Physical Chemistry B}, - volume = {103}, - number = {18}, - pages = {3699-3705}, - year = {1999}, - doi = {10.1021/jp984584r} -} - -@article{Yeh2004, - author = {Yeh, In-Chul and Hummer, Gerhard}, - title = {System-Size Dependence of Diffusion Coefficients and Viscosities from Molecular Dynamics Simulations with Periodic Boundary Conditions}, - journal = {The Journal of Physical Chemistry B}, - volume = {108}, - number = {40}, - pages = {15873-15879}, - year = {2004}, - doi = {10.1021/jp0477147} -} - -@inproceedings{deLaPorte2008, - author = {Porte, J and Herbst, Ben and Hereman, Willy and van der Walt, Stéfan}, - year = {2008}, - month = {11}, - title = {An Introduction to Diffusion Maps}, - booktitle = {} -} - -@incollection{Goldman1990, - author = {Goldman, Ronald}, - title = {Matrices and Transformations}, - booktitle = {Graphics Gems I}, - year = {1990}, - isbn = {0122861695}, - publisher = {Morgan Kaufmann}, - address = {USA}, - pages = {472–475}, - numpages = {3}, - id = {transformations} -} - -@incollection{Shoemake1992-Uniform, - author = {Ken Shoemake}, - title = {Uniform Random Rotations}, - booktitle = {Graphics Gems III}, - editor = {David Kirk}, - publisher = {Academic Press}, - year = {1992}, - pages = {124--132}, - id = {transformations} -} - -@article{Karney2007, - title = {Quaternions in molecular modeling}, - journal = {Journal of Molecular Graphics and Modelling}, - volume = {25}, - number = {5}, - pages = {595-604}, - year = {2007}, - issn = {1093-3263}, - doi = {https://doi.org/10.1016/j.jmgm.2006.04.002}, - author = {Charles F.F. Karney}, - id = {transformations} -} - -@article{Bar-Itzhack2000, - author = {Bar-Itzhack, Itzhack Y.}, - title = {New Method for Extracting the Quaternion from a Rotation Matrix}, - journal = {Journal of Guidance, Control, and Dynamics}, - volume = {23}, - number = {6}, - pages = {1085-1087}, - year = {2000}, - doi = {10.2514/2.4654}, - id = {transformations} -} - -@incollection{Goldman1991-shear - title = {VII.4 - MORE MATRICES AND TRANSFORMATIONS: SHEAR AND PSEUDO-PERSPECTIVE}, - editor = {JAMES ARVO}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {338-341}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50072-4}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500724}, - author = {Ronald N. Goldman}, - id = {transformations} -} - -@incollection{Thomas1991, - title = {VII.1 - DECOMPOSING A MATRIX INTO SIMPLE TRANSFORMATIONS}, - editor = {JAMES ARVO}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {320-323}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50069-4}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500694}, - author = {Spencer W. Thomas}, - id = {transformations} -} - -@incollection{Goldman1991-transformation, - title = {VII.2 - RECOVERING THE DATA FROM THE TRANSFORMATION MATRIX}, - editor = {James Arvo}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {324-331}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50070-0}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500700}, - author = {Ronald N. Goldman}, - id = {transformations} -} - -@incollection{Shoemake1994-Euler, - author = {Ken Shoemake}, - title = {Euler Angle Conversion}, - booktitle = {Graphics Gems IV}, - editor = {Paul S. Heckbert}, - publisher = {Morgan Kaufmann}, - year = {1994}, - pages = {222--229}, - id = {transformations} -} - -@incollection{Shoemake1991-Arcball, - author = {Ken Shoemake}, - title = {Arcball Rotation Control}, - booktitle = {Graphics Gems IV}, - editor = {Paul S. Heckbert}, - publisher = {Morgan Kaufmann}, - year = {1994}, - pages = {175--192}, - id = {transformations} -} - -@incollection{Shoemake1991-Quaternions, - author = {Ken Shoemake}, - title = {Quaternions}, - booktitle = {}, - year = {}, - url = {https://www.ljll.math.upmc.fr/~frey/papers/scientific%20visualisation/Shoemake%20K.,%20Quaternions.pdf}, - id = {transformations} -} - -@incollection{Diebel2006, - author = {Diebel, James}, - year = {2006}, - title = {Representing Attitude: Euler Angles, Unit Quaternions, and Rotation Vectors}, - booktitle = {}, - id = {transformations} -} - -@article{Kabsch1978, - author = "Kabsch, W.", - title = "{A discussion of the solution for the best rotation to relate two sets of vectors}", - journal = "Acta Crystallographica Section A", - year = "1978", - volume = "34", - number = "5", - pages = "827--828", - month = "Sep", - doi = {10.1107/S0567739478001680}, - url = {https://doi.org/10.1107/S0567739478001680}, - id = {transformations} -} - -@article{Horn1987, - author = {Horn, Berthold}, - year = {1987}, - month = {04}, - pages = {629-642}, - title = {Closed-Form Solution of Absolute Orientation Using Unit Quaternions}, - volume = {4}, - journal = {Journal of the Optical Society A}, - doi = {10.1364/JOSAA.4.000629}, - id = {transformations} -} - -@incollection{Waveren2005 - title = {From Quaternion to Matrix and Back}, - author = {JMP van Waveren}, - year = {2005}, - url = {http://www.intel.com/cd/ids/developer/asmo-na/eng/293748.htm}, - booktitle = {}, - id = {transformations} -} - -@article{Kulke2022, - title = {Reversible Unwrapping Algorithm for Constant-Pressure Molecular Dynamics Simulations}, - author = {Kulke, Martin and Vermaas, Josh V.}, - year = {2022}, - journal = {Journal of Chemical Theory and Computation}, - volume = {18}, - number = {10}, - pages = {6161--6171}, - doi = {10.1021/acs.jctc.2c00327} -} - -@article{Kabsch1983, -author = {Kabsch, Wolfgang and Sander, Christian}, -title = {Dictionary of protein secondary structure: Pattern recognition of hydrogen-bonded and geometrical features}, -journal = {Biopolymers}, -volume = {22}, -number = {12}, -pages = {2577-2637}, -doi = {https://doi.org/10.1002/bip.360221211}, -url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/bip.360221211}, -eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1002/bip.360221211}, -abstract = {Abstract For a successful analysis of the relation between amino acid sequence and protein structure, an unambiguous and physically meaningful definition of secondary structure is essential. We have developed a set of simple and physically motivated criteria for secondary structure, programmed as a pattern-recognition process of hydrogen-bonded and geometrical features extracted from x-ray coordinates. Cooperative secondary structure is recognized as repeats of the elementary hydrogen-bonding patterns “turn” and “bridge.” Repeating turns are “helices,” repeating bridges are “ladders,” connected ladders are “sheets.” Geometric structure is defined in terms of the concepts torsion and curvature of differential geometry. Local chain “chirality” is the torsional handedness of four consecutive Cα positions and is positive for right-handed helices and negative for ideal twisted β-sheets. Curved pieces are defined as “bends.” Solvent “exposure” is given as the number of water molecules in possible contact with a residue. The end result is a compilation of the primary structure, including SS bonds, secondary structure, and solvent exposure of 62 different globular proteins. The presentation is in linear form: strip graphs for an overall view and strip tables for the details of each of 10.925 residues. The dictionary is also available in computer-readable form for protein structure prediction work.}, -year = {1983} -} - -@article{Linke2018, - title = {Fully Anisotropic Rotational Diffusion Tensor from Molecular Dynamics Simulations}, - author = {Linke, Max and Köfinger, Jürgen and Hummer, Gerhard}, - year = {2018}, - journal = {The Journal of Physical Chemistry B}, - volume = {122}, - number = {21}, - pages = {5630--5639}, - doi = {10.1021/acs.jpcb.7b11988} -} - -@inproceedings{Fan2019, - title = {{PMDA} - {P}arallel {M}olecular {D}ynamics {A}nalysis}, - author = {Shujie Fan and Max Linke and Ioannis Paraskevakos and Richard J. Gowers and Michael Gecht and Oliver Beckstein}, - year = {2019}, - booktitle = {{P}roceedings of the 18th {P}ython in {S}cience {C}onference}, - editor = {{C}hris {C}alloway and {D}avid {L}ippa and {D}illon {N}iederhut and {D}avid {S}hupe}, - organization = {SciPy}, - address = {Austin, TX}, - pages = {134 - 142}, - doi = {10.25080/Majora-7ddc1dd1-013} -} +@book{Gray1984, + address = {Oxford ; New York}, + series = {The {International} series of monographs on chemistry}, + title = {Theory of molecular fluids}, + isbn = {978-0-19-855602-2}, + number = {9}, + publisher = {Oxford University Press}, + author = {Gray, C. G. and Gubbins, Keith E. and Joslin, C. G.}, + year = {1984}, + keywords = {Fluids, Molecular theory}, +} + +@article{MichaudAgrawal2011, + author = {Michaud-Agrawal, Naveen and Denning, Elizabeth J. and Woolf, Thomas B. and Beckstein, Oliver}, + title = {MDAnalysis: A toolkit for the analysis of molecular dynamics simulations}, + journal = {Journal of Computational Chemistry}, + volume = {32}, + number = {10}, + pages = {2319-2327}, + doi = {https://doi.org/10.1002/jcc.21787}, + year = {2011} +} + +@article{Gowers2016, + title = {{MDAnalysis}: {A} {Python} {Package} for the {Rapid} {Analysis} of {Molecular} {Dynamics} {Simulations}}, + shorttitle = {{MDAnalysis}}, + url = {https://conference.scipy.org/proceedings/scipy2016/oliver_beckstein.html}, + doi = {10.25080/Majora-629e541a-00e}, + urldate = {2020-02-05}, + journal = {Proceedings of the 15th Python in Science Conference}, + author = {Gowers, Richard J. and Linke, Max and Barnoud, Jonathan and Reddy, Tyler J. E. and Melo, Manuel N. and Seyler, Sean L. and Domański, Jan and Dotson, David L. and Buchoux, Sébastien and Kenney, Ian M. and Beckstein, Oliver}, + year = {2016}, + note = {00152}, + pages = {98--105}, +} + +@article{Alt1995, + author = {Alt, Helmut and Godau, Michael}, + title = {Computing the Frechet distance between two polygonal curves}, + journal = {International Journal of Computational Geometry \& Applications}, + volume = {05}, + number = {01n02}, + pages = {75-91}, + year = {1995}, + doi = {10.1142/S0218195995000064} +} + +@article{ArayaSecchi2014, + author = {Araya-Secchi, Raul and Perez-Acle, Tomas and Kang, Seung-gu and Huynh, Tien and Bernardin, Alejandro and Escalona, Yerko and Garate, Jose-Antonio and Mart{\'\i}nez, Agustin D. and Garc{\'\i}a, Isaac E. and S{\'a}ez, Juan C. and Zhou, Ruhong}, + doi = {10.1016/j.bpj.2014.05.037}, + journal = {Biophysical Journal}, + Number = {3}, + Pages = {599--612}, + Publisher = {Elsevier}, + Title = {Characterization of a Novel Water Pocket Inside the Human Cx26 Hemichannel Structure}, + Volume = {107}, + year = {2014} +} + +@article{BerkHess2002, + title = {Convergence of sampling in protein simulations}, + author = {Hess, Berk}, + journal = {Phys. Rev. E}, + volume = {65}, + issue = {3}, + pages = {031910}, + numpages = {10}, + year = {2002}, + month = {Mar}, + publisher = {American Physical Society}, + doi = {10.1103/PhysRevE.65.031910} +} + +@article{Best2013, + author = {Robert B. Best and Gerhard Hummer and William A. Eaton }, + title = {Native contacts determine protein folding mechanisms in atomistic simulations}, + journal = {Proceedings of the National Academy of Sciences}, + volume = {110}, + number = {44}, + pages = {17874-17879}, + year = {2013}, + doi = {10.1073/pnas.1311599110} +} + +@article{Brodka1994, + author = { Aleksander Bródka }, + title = {Diffusion in restricted volume}, + journal = {Molecular Physics}, + volume = {82}, + number = {5}, + pages = {1075-1078}, + year = {1994}, + publisher = {Taylor & Francis}, + doi = {10.1080/00268979400100764} +} + +@article{Bulow2020, + author = {von Bülow,Sören and Bullerjahn,Jakob Tómas and Hummer,Gerhard }, + title = {Systematic errors in diffusion coefficients from long-time molecular dynamics simulations at constant pressure}, + journal = {The Journal of Chemical Physics}, + volume = {153}, + number = {2}, + pages = {021101}, + year = {2020}, + doi = {10.1063/5.0008316} +} + +@article{Chang2003, + author = {Chang, Chia-En and Potter, Michael J. and Gilson, Michael K.}, + title = {Calculation of Molecular Configuration Integrals}, + journal = {The Journal of Physical Chemistry B}, + volume = {107}, + number = {4}, + pages = {1048-1055}, + year = {2003}, + doi = {10.1021/jp027149c} +} + +@Article{Chavent2014, + author = {Chavent, Matthieu and Reddy, Tyler and Goose, Joseph and Dahl, Anna Caroline E. and Stone, John E. and Jobard, Bruno and Sansom, Mark S. P.}, + title = {Methodologies for the analysis of instantaneous lipid diffusion in md simulations of large membrane systems}, + journal = {Faraday Discuss.}, + year = {2014}, + volume = {169}, + pages = {455-475}, + publisher = {The Royal Society of Chemistry}, + doi = {10.1039/C3FD00145H} +} + +@article{Clementi2011, + author = {Rohrdanz,Mary A. and Zheng,Wenwei and Maggioni,Mauro and Clementi,Cecilia }, + title = {Determination of reaction coordinates via locally scaled diffusion map}, + journal = {The Journal of Chemical Physics}, + volume = {134}, + number = {12}, + pages = {124116}, + year = {2011}, + doi = {10.1063/1.3569857} +} + +@article{Denning2011 + author = {Denning, Elizabeth J. and Priyakumar, U. Deva and Nilsson, Lennart and Mackerell Jr., Alexander D.}, + title = {Impact of 2-hydroxyl sampling on the conformational properties of RNA: Update of the CHARMM all-atom additive force field for RNA}, + journal = {Journal of Computational Chemistry}, + year = {2011}, + volume = {32}, + number = {9}, + pages = {1929-1943}, + doi = {https://doi.org/10.1002/jcc.21777} +} + +@article{Denning2012, + author = {Denning, Elizabeth J. and MacKerell, Alexander D.}, + title = {Intrinsic Contribution of the 2{\'}-Hydroxyl to RNA Conformational Heterogeneity}, + journal = {Journal of the American Chemical Society}, + volume = {134}, + number = {5}, + pages = {2800-2806}, + year = {2012}, + doi = {10.1021/ja211328g}, + note ={PMID: 22242623} +} + +@article{EiterMannila1994, + author = {Eiter, Thomas and Mannila, Heikki}, + year = {1994}, + month = {05}, + journal = {}, + title = {Computing Discrete Frechet Distance} +} + +@article{EiterMannila1997, + author = {Eiter, Thomas and Mannila, Heikki}, + doi = {10.1007/s002360050075}, + journal = {Acta Informatica}, + Number = {2}, + Pages = {109--133}, + Title = {Distance measures for point sets and their computation}, + Volume = {34}, + year = {1997} +} + +@article{Ferguson2011, + author = {Andrew L. Ferguson and Athanassios Z. Panagiotopoulos and Ioannis G. Kevrekidis and Pablo G. Debenedetti}, + title = {Nonlinear dimensionality reduction in molecular simulation: The diffusion map approach}, + journal = {Chemical Physics Letters}, + volume = {509}, + number = {1}, + pages = {1-11}, + year = {2011}, + issn = {0009-2614}, + doi = {https://doi.org/10.1016/j.cplett.2011.04.066}, + url = {https://www.sciencedirect.com/science/article/pii/S0009261411004957} +} + +@article{Franklin2007, + author = {Franklin, Joel and Koehl, Patrice and Doniach, Sebastian and Delarue, Marc}, + title = "{MinActionPath: maximum likelihood trajectory for large-scale structural transitions in a coarse-grained locally harmonic energy landscape}", + journal = {Nucleic Acids Research}, + volume = {35}, + number = {suppl_2}, + pages = {W477-W482}, + year = {2007}, + doi = {10.1093/nar/gkm342} +} + +@article{Frechet1906, + author = {Frèchet, M. Maurice}, + doi = {10.1007/BF03018603}, + journal = {Rendiconti del Circolo Matematico di Palermo (1884-1940)}, + Number = {1}, + Pages = {1--72}, + Title = {Sur quelques points du calcul fonctionnel}, + Volume = {22}, + year = {1906} +} + +@article{Gowers2015, + author = {Gowers,Richard J. and Carbone,Paola }, + title = {A multiscale approach to model hydrogen bonding: The case of polyamide}, + journal = {The journal of Chemical Physics}, + volume = {142}, + number = {22}, + pages = {224907}, + year = {2015}, + doi = {10.1063/1.4922445} +} + +@article{Gregoret1991, + author = {Gregoret, Lydia M. and Rader, Stephen D. and Fletterick, Robert J. and Cohen, Fred E.}, + title = {Hydrogen bonds involving sulfur atoms in proteins}, + journal = {Proteins: Structure, Function, and Bioinformatics}, + year = {1991}, + volume = {9}, + number = {2}, + pages = {99-107}, + doi = {https://doi.org/10.1002/prot.340090204} +} + +@article{Grigera1995, + author = {Grigera, J. Raul and Kalko, Susana G. and Fischbarg, Jorge}, + title = {Wall−Water Interface. A Molecular Dynamics Study}, + journal = {Langmuir}, + volume = {12}, + number = {1}, + pages = {154-158}, + year = {1996}, + doi = {10.1021/la9408681} +} + +@article{Gu2019, + author = {Gu, Ruo-Xu and Baoukina, Svetlana and Tieleman, D. Peter}, + title = {Cholesterol Flip-Flop in Heterogeneous Membranes}, + journal = {Journal of Chemical Theory and Computation}, + volume = {15}, + number = {3}, + pages = {2064-2070}, + year = {2019}, + doi = {10.1021/acs.jctc.8b00933} +} + +@article{Hall2007, + author = {Hall, Benjamin A. and Kaye, Samantha L. and Pang, Andy and Perera, Rafael and Biggin, Philip C.}, + title = {Characterization of Protein Conformational States by Normal-Mode Frequencies}, + journal = {Journal of the American Chemical Society}, + volume = {129}, + number = {37}, + pages = {11394-11401}, + year = {2007}, + doi = {10.1021/ja071797y}, + note ={PMID: 17715919} +} + +@article{Hikiri2016, + author = {Hikiri, Simon and Yoshidome, Takashi and Ikeguchi, Mitsunori}, + title = {Computational Methods for Configurational Entropy Using Internal and Cartesian Coordinates}, + journal = {Journal of Chemical Theory and Computation}, + volume = {12}, + number = {12}, + pages = {5990-6000}, + year = {2016}, + doi = {10.1021/acs.jctc.6b00563}, + note ={PMID: 27951672} +} + +@article{Janin1978, + author = {Joël Janin and Shoshanna Wodak and Michael Levitt and Bernard Maigret}, + title = {Conformation of amino acid side-chains in proteins}, + journal = {Journal of Molecular Biology}, + volume = {125}, + number = {3}, + pages = {357-386}, + year = {1978}, + issn = {0022-2836}, + doi = {https://doi.org/10.1016/0022-2836(78)90408-4}, + url = {https://www.sciencedirect.com/science/article/pii/0022283678904084} +} + +@article{Jorgensen1998, + author = {Jorgensen, William L. and Jenson, Corky}, + title = {Temperature dependence of TIP3P, SPC, and TIP4P water from NPT Monte Carlo simulations: Seeking temperatures of maximum density}, + journal = {Journal of Computational Chemistry}, + year = {1998}, + volume = {19}, + number = {10}, + pages = {1179-1186}, + doi = {https://doi.org/10.1002/(SICI)1096-987X(19980730)19:10<1179::AID-JCC6>3.0.CO;2-J} +} + +@article{Coifman-Lafon, + author = {Ronald R. Coifman and Stéphane Lafon}, + title = {Diffusion maps}, + journal = {Applied and Computational Harmonic Analysis}, + volume = {21}, + number = {1}, + pages = {5-30}, + year = {2006}, + note = {Special Issue: Diffusion Maps and Wavelets}, + issn = {1063-5203}, + doi = {https://doi.org/10.1016/j.acha.2006.04.006}, + url = {https://www.sciencedirect.com/science/article/pii/S1063520306000546} +} + +@article{LindorffLarsen2009, + doi = {10.1371/journal.pone.0004203}, + author = {Lindorff-Larsen, Kresten AND Ferkinghoff-Borg, Jesper}, + journal = {PLOS ONE}, + publisher = {Public Library of Science}, + title = {Similarity Measures for Protein Ensembles}, + year = {2009}, + month = {01}, + volume = {4}, + pages = {1-13}, + number = {1} +} + +@article{Liu2004 + author = {Liu, Pu and Harder, Edward and Berne, B. J.}, + title = {On the Calculation of Diffusion Coefficients in Confined Fluids and Interfaces with an Application to the Liquid−Vapor Interface of Water}, + journal = {The Journal of Physical Chemistry B}, + volume = {108}, + number = {21}, + pages = {6595-6602}, + year = {2004}, + doi = {10.1021/jp0375057} +} + +@article{Lovell2003, + author = {Lovell, Simon C. and Davis, Ian W. and Arendall III, W. Bryan and de Bakker, Paul I. W. and Word, J. Michael and Prisant, Michael G. and Richardson, Jane S. and Richardson, David C.}, + title = {Structure validation by C$/alpha$ geometry: $\psi$,$\phi$ and C$\beta$ deviation}, + journal = {Proteins: Structure, Function, and Bioinformatics}, + year = {2003}, + volume = {50}, + number = {3}, + pages = {437-450}, + doi = {https://doi.org/10.1002/prot.10286} +} + +@article{Lu2003, + author = {Lu, Xiang‐Jun and Olson, Wilma K.}, + title = "{3DNA: a software package for the analysis, rebuilding and visualization of three‐dimensional nucleic acid structures}", + journal = {Nucleic Acids Research}, + volume = {31}, + number = {17}, + pages = {5108-5121}, + year = {2003}, + month = {09}, + issn = {0305-1048}, + doi = {10.1093/nar/gkg680} +} + +@article{Lu2008, + author = {Lu, Xiang-Jun and Olson, Wilma K}, + doi = {10.1038/nprot.2008.104}, + Isbn = {1750-2799}, + journal = {Nature Protocols}, + Number = {7}, + Pages = {1213--1227}, + Title = {3DNA: a versatile, integrated software system for the analysis, rebuilding and visualization of three-dimensional nucleic-acid structures}, + Volume = {3}, + year = {2008}, +} + +@article{Lundborg2014, + author = {Lundborg, Magnus and Apostolov, Rossen and Spångberg, Daniel and Gärdenäs, Anders and van der Spoel, David and Lindahl, Erik}, + title = {An efficient and extensible format, library, and API for binary trajectory data from molecular simulations}, + journal = {Journal of Computational Chemistry}, + volume = {35}, + number = {3}, + pages = {260-269}, + doi = {https://doi.org/10.1002/jcc.23495}, + url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.23495}, + year = {2014} +} + +@article{Maginn2019, + author = {Maginn, Edward J. and Messerly, Richard A. and Carlson, Daniel J. and Roe, Daniel R. and Elliot, J. Richard}, + title = {Best Practices for Computing Transport Properties Self-Diffusivity and Viscosity from Equilibrium Molecular Dynamics}, + volume = {1}, + doi = {10.33011/livecoms.1.1.6324}, + number = {1}, + journal = {Living Journal of Computational Molecular Science}, + year = {2018}, + month = {Dec.}, + pages = {6324}, + url = {https://livecomsjournal.org/index.php/livecoms/article/view/v1i1e6324} +} + +@article{Milischuk2011, + author = {Milischuk,Anatoli A. and Ladanyi,Branka M. }, + title = {Structure and dynamics of water confined in silica nanopores}, + journal = {The Journal of Chemical Physics}, + volume = {135}, + number = {17}, + pages = {174709}, + year = {2011}, + doi = {10.1063/1.3657408} +} + +@article{Minh2020, + author = {Minh, David D. L.}, + title = {Alchemical Grid Dock (AlGDock): Binding Free Energy Calculations between Flexible Ligands and Rigid Receptors}, + journal = {Journal of Computational Chemistry}, + year = {2020}, + volume = {41}, + number = {7}, + pages = {715-730}, + doi = {https://doi.org/10.1002/jcc.26036} +} + +@article{Mull2018, + author = "Henry Mull and Oliver Beckstein", + title = "{Technical Report: + SPIDAL Summer REU 2018 Dihedral Analysis in MDAnalysis}", + year = "2018", + month = "8", + journal = {}, + url ="https://figshare.com/articles/journal_contribution/Technical_Report_SPIDAL_Summer_REU_2018_Dihedral_Analysis_in_MDAnalysis/6957296", + doi = "10.6084/m9.figshare.6957296.v1" +} + +@article{Ramachandran1963, + author = {G.N. Ramachandran and C. Ramakrishnan and V. Sasisekharan}, + title = {Stereochemistry of polypeptide chain configurations}, + journal = {Journal of Molecular Biology}, + volume = {7}, + number = {1}, + pages = {95-99}, + year = {1963}, + issn = {0022-2836}, + doi = {https://doi.org/10.1016/S0022-2836(63)80023-6}, + url = {https://www.sciencedirect.com/science/article/pii/S0022283663800236} +} + +@article{Rapaport1983, + author = { D.C. Rapaport}, + title = {Hydrogen bonds in water}, + journal = {Molecular Physics}, + volume = {50}, + number = {5}, + pages = {1151-1162}, + year = {1983}, + publisher = {Taylor & Francis}, + doi = {10.1080/00268978300102931} +} + +@article{Seyler2015, + doi = {10.1371/journal.pcbi.1004568}, + author = {Seyler, Sean L. AND Kumar, Avishek AND Thorpe, M. F. AND Beckstein, Oliver}, + journal = {PLOS Computational Biology}, + publisher = {Public Library of Science}, + title = {Path Similarity Analysis: A Method for Quantifying Macromolecular Pathways}, + year = {2015}, + month = {10}, + volume = {11}, + pages = {1-37}, + number = {10} +} + +@article{Smart1993, + title = {The pore dimensions of gramicidin A}, + journal = {Biophysical Journal}, + volume = {65}, + number = {6}, + pages = {2455-2460}, + year = {1993}, + issn = {0006-3495}, + doi = {https://doi.org/10.1016/S0006-3495(93)81293-1}, + author = {O.S. Smart and J.M. Goodfellow and B.A. Wallace} +} + +@article{Smart1996, + title = {HOLE: A program for the analysis of the pore dimensions of ion channel structural models}, + journal = {Journal of Molecular Graphics}, + volume = {14}, + number = {6}, + pages = {354-360}, + year = {1996}, + issn = {0263-7855}, + doi = {https://doi.org/10.1016/S0263-7855(97)00009-X}, + author = {Oliver S. Smart and Joseph G. Neduvelil and Xiaonan Wang and B.A. Wallace and Mark S.P. Sansom} +} + +@article{Stelzl2014, + title = {Flexible Gates Generate Occluded Intermediates in the Transport Cycle of LacY}, + journal = {Journal of Molecular Biology}, + volume = {426}, + number = {3}, + pages = {735-751}, + year = {2014}, + issn = {0022-2836}, + doi = {https://doi.org/10.1016/j.jmb.2013.10.024}, + author = {Lukas S. Stelzl and Philip W. Fowler and Mark S.P. Sansom and Oliver Beckstein}, + id = {Stelzl _et_ al.} +} + +@article{Taha2015, + author={Taha, Abdel Aziz and Hanbury, Allan}, + journal={IEEE Transactions on Pattern Analysis and Machine Intelligence}, + title={An Efficient Algorithm for Calculating the Exact Hausdorff Distance}, + year={2015}, + volume={37}, + number={11}, + pages={2153-2163}, + doi={10.1109/TPAMI.2015.2408351} +} + +@article{Theobald2005, +author = "Theobald, Douglas L.", +title = "{Rapid calculation of RMSDs using a quaternion-based characteristic polynomial}", +journal = "Acta Crystallographica Section A", +year = "2005", +volume = "61", +number = "4", +pages = "478--480", +month = "Jul", +doi = {10.1107/S0108767305015266} +} + +@article{Tiberti2015, + doi = {10.1371/journal.pcbi.1004415}, + author = {Tiberti, Matteo AND Papaleo, Elena AND Bengtsen, Tone AND Boomsma, Wouter AND Lindorff-Larsen, Kresten}, + journal = {PLOS Computational Biology}, + publisher = {Public Library of Science}, + title = {ENCORE: Software for Quantitative Ensemble Comparison}, + year = {2015}, + month = {10}, + volume = {11}, + pages = {1-16}, + number = {10} +} + +@article{Welford1962, + author = { B. P. Welford}, + title = {Note on a Method for Calculating Corrected Sums of Squares and Products}, + journal = {Technometrics}, + volume = {4}, + number = {3}, + pages = {419-420}, + year = {1962}, + publisher = {Taylor & Francis}, + doi = {10.1080/00401706.1962.10490022} +} + +@article{Yeh1999, + author = {Yeh, Yu-ling and Mou, Chung-Yuan}, + title = {Orientational Relaxation Dynamics of Liquid Water Studied by Molecular Dynamics Simulation}, + journal = {The Journal of Physical Chemistry B}, + volume = {103}, + number = {18}, + pages = {3699-3705}, + year = {1999}, + doi = {10.1021/jp984584r} +} + +@article{Yeh2004, + author = {Yeh, In-Chul and Hummer, Gerhard}, + title = {System-Size Dependence of Diffusion Coefficients and Viscosities from Molecular Dynamics Simulations with Periodic Boundary Conditions}, + journal = {The Journal of Physical Chemistry B}, + volume = {108}, + number = {40}, + pages = {15873-15879}, + year = {2004}, + doi = {10.1021/jp0477147} +} + +@inproceedings{deLaPorte2008, + author = {Porte, J and Herbst, Ben and Hereman, Willy and van der Walt, Stéfan}, + year = {2008}, + month = {11}, + title = {An Introduction to Diffusion Maps}, + booktitle = {} +} + +@incollection{Goldman1990, + author = {Goldman, Ronald}, + title = {Matrices and Transformations}, + booktitle = {Graphics Gems I}, + year = {1990}, + isbn = {0122861695}, + publisher = {Morgan Kaufmann}, + address = {USA}, + pages = {472–475}, + numpages = {3}, + id = {transformations} +} + +@incollection{Shoemake1992-Uniform, + author = {Ken Shoemake}, + title = {Uniform Random Rotations}, + booktitle = {Graphics Gems III}, + editor = {David Kirk}, + publisher = {Academic Press}, + year = {1992}, + pages = {124--132}, + id = {transformations} +} + +@article{Karney2007, + title = {Quaternions in molecular modeling}, + journal = {Journal of Molecular Graphics and Modelling}, + volume = {25}, + number = {5}, + pages = {595-604}, + year = {2007}, + issn = {1093-3263}, + doi = {https://doi.org/10.1016/j.jmgm.2006.04.002}, + author = {Charles F.F. Karney}, + id = {transformations} +} + +@article{Bar-Itzhack2000, + author = {Bar-Itzhack, Itzhack Y.}, + title = {New Method for Extracting the Quaternion from a Rotation Matrix}, + journal = {Journal of Guidance, Control, and Dynamics}, + volume = {23}, + number = {6}, + pages = {1085-1087}, + year = {2000}, + doi = {10.2514/2.4654}, + id = {transformations} +} + +@incollection{Goldman1991-shear + title = {VII.4 - MORE MATRICES AND TRANSFORMATIONS: SHEAR AND PSEUDO-PERSPECTIVE}, + editor = {JAMES ARVO}, + booktitle = {Graphics Gems II}, + publisher = {Morgan Kaufmann}, + address = {San Diego}, + pages = {338-341}, + year = {1991}, + isbn = {978-0-08-050754-5}, + doi = {https://doi.org/10.1016/B978-0-08-050754-5.50072-4}, + url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500724}, + author = {Ronald N. Goldman}, + id = {transformations} +} + +@incollection{Thomas1991, + title = {VII.1 - DECOMPOSING A MATRIX INTO SIMPLE TRANSFORMATIONS}, + editor = {JAMES ARVO}, + booktitle = {Graphics Gems II}, + publisher = {Morgan Kaufmann}, + address = {San Diego}, + pages = {320-323}, + year = {1991}, + isbn = {978-0-08-050754-5}, + doi = {https://doi.org/10.1016/B978-0-08-050754-5.50069-4}, + url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500694}, + author = {Spencer W. Thomas}, + id = {transformations} +} + +@incollection{Goldman1991-transformation, + title = {VII.2 - RECOVERING THE DATA FROM THE TRANSFORMATION MATRIX}, + editor = {James Arvo}, + booktitle = {Graphics Gems II}, + publisher = {Morgan Kaufmann}, + address = {San Diego}, + pages = {324-331}, + year = {1991}, + isbn = {978-0-08-050754-5}, + doi = {https://doi.org/10.1016/B978-0-08-050754-5.50070-0}, + url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500700}, + author = {Ronald N. Goldman}, + id = {transformations} +} + +@incollection{Shoemake1994-Euler, + author = {Ken Shoemake}, + title = {Euler Angle Conversion}, + booktitle = {Graphics Gems IV}, + editor = {Paul S. Heckbert}, + publisher = {Morgan Kaufmann}, + year = {1994}, + pages = {222--229}, + id = {transformations} +} + +@incollection{Shoemake1991-Arcball, + author = {Ken Shoemake}, + title = {Arcball Rotation Control}, + booktitle = {Graphics Gems IV}, + editor = {Paul S. Heckbert}, + publisher = {Morgan Kaufmann}, + year = {1994}, + pages = {175--192}, + id = {transformations} +} + +@incollection{Shoemake1991-Quaternions, + author = {Ken Shoemake}, + title = {Quaternions}, + booktitle = {}, + year = {}, + url = {https://www.ljll.math.upmc.fr/~frey/papers/scientific%20visualisation/Shoemake%20K.,%20Quaternions.pdf}, + id = {transformations} +} + +@incollection{Diebel2006, + author = {Diebel, James}, + year = {2006}, + title = {Representing Attitude: Euler Angles, Unit Quaternions, and Rotation Vectors}, + booktitle = {}, + id = {transformations} +} + +@article{Kabsch1978, + author = "Kabsch, W.", + title = "{A discussion of the solution for the best rotation to relate two sets of vectors}", + journal = "Acta Crystallographica Section A", + year = "1978", + volume = "34", + number = "5", + pages = "827--828", + month = "Sep", + doi = {10.1107/S0567739478001680}, + url = {https://doi.org/10.1107/S0567739478001680}, + id = {transformations} +} + +@article{Horn1987, + author = {Horn, Berthold}, + year = {1987}, + month = {04}, + pages = {629-642}, + title = {Closed-Form Solution of Absolute Orientation Using Unit Quaternions}, + volume = {4}, + journal = {Journal of the Optical Society A}, + doi = {10.1364/JOSAA.4.000629}, + id = {transformations} +} + +@incollection{Waveren2005 + title = {From Quaternion to Matrix and Back}, + author = {JMP van Waveren}, + year = {2005}, + url = {http://www.intel.com/cd/ids/developer/asmo-na/eng/293748.htm}, + booktitle = {}, + id = {transformations} +} + +@article{Kulke2022, + title = {Reversible Unwrapping Algorithm for Constant-Pressure Molecular Dynamics Simulations}, + author = {Kulke, Martin and Vermaas, Josh V.}, + year = {2022}, + journal = {Journal of Chemical Theory and Computation}, + volume = {18}, + number = {10}, + pages = {6161--6171}, + doi = {10.1021/acs.jctc.2c00327} +} + +@article{Kabsch1983, +author = {Kabsch, Wolfgang and Sander, Christian}, +title = {Dictionary of protein secondary structure: Pattern recognition of hydrogen-bonded and geometrical features}, +journal = {Biopolymers}, +volume = {22}, +number = {12}, +pages = {2577-2637}, +doi = {https://doi.org/10.1002/bip.360221211}, +url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/bip.360221211}, +eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1002/bip.360221211}, +abstract = {Abstract For a successful analysis of the relation between amino acid sequence and protein structure, an unambiguous and physically meaningful definition of secondary structure is essential. We have developed a set of simple and physically motivated criteria for secondary structure, programmed as a pattern-recognition process of hydrogen-bonded and geometrical features extracted from x-ray coordinates. Cooperative secondary structure is recognized as repeats of the elementary hydrogen-bonding patterns “turn” and “bridge.” Repeating turns are “helices,” repeating bridges are “ladders,” connected ladders are “sheets.” Geometric structure is defined in terms of the concepts torsion and curvature of differential geometry. Local chain “chirality” is the torsional handedness of four consecutive Cα positions and is positive for right-handed helices and negative for ideal twisted β-sheets. Curved pieces are defined as “bends.” Solvent “exposure” is given as the number of water molecules in possible contact with a residue. The end result is a compilation of the primary structure, including SS bonds, secondary structure, and solvent exposure of 62 different globular proteins. The presentation is in linear form: strip graphs for an overall view and strip tables for the details of each of 10.925 residues. The dictionary is also available in computer-readable form for protein structure prediction work.}, +year = {1983} +} + +@article{Linke2018, + title = {Fully Anisotropic Rotational Diffusion Tensor from Molecular Dynamics Simulations}, + author = {Linke, Max and Köfinger, Jürgen and Hummer, Gerhard}, + year = {2018}, + journal = {The Journal of Physical Chemistry B}, + volume = {122}, + number = {21}, + pages = {5630--5639}, + doi = {10.1021/acs.jpcb.7b11988} +} + +@inproceedings{Fan2019, + title = {{PMDA} - {P}arallel {M}olecular {D}ynamics {A}nalysis}, + author = {Shujie Fan and Max Linke and Ioannis Paraskevakos and Richard J. Gowers and Michael Gecht and Oliver Beckstein}, + year = {2019}, + booktitle = {{P}roceedings of the 18th {P}ython in {S}cience {C}onference}, + editor = {{C}hris {C}alloway and {D}avid {L}ippa and {D}illon {N}iederhut and {D}avid {S}hupe}, + organization = {SciPy}, + address = {Austin, TX}, + pages = {134 - 142}, + doi = {10.25080/Majora-7ddc1dd1-013} +}