MDAnalysis 1.0 paper initial notes

Oliver Beckstein edited this page Sep 18, 2018 · 14 revisions

We are slowly moving towards MDAnalysis 1.0. This release will freeze the API (until MDAnalysis 2.0) and guarantee backwards compatibility throughout 1.x. We want to write a paper that describes the library and gives the more recent contributors also a chance to get proper academic credit. This paper should also be suitable to replace the current 2011+2016 papers as the sole citation for MDAnalysis in published work.

This wiki page should act as initial starting point for gathering ideas and hashing out the broad structure. Once we get started in earnest, we will create a separate repository.

  1. Paper content
  2. Authorship model
  3. Journal

Paper content


  • domain description
    • challenges and requirements
  • history and other similar packages

Design and Structure of the library


Philosophy and what lessons did we learn between initial release and 1.0 and how did they impact the design?

  • object oriented
  • pythonic
  • interactive
  • interoperable


Understanding the code base

  • core data structures
  • library structure
    • core, topology system, "lib"
    • coordinates and topology readers/writers (+ maybe briefly selection writers); note on random access in trajectories
      • trajectory formats, topology formats (table)
      • special topics
        • MemoryReader
        • download from PDB with fetch_mmtf()
    • analysis: overview


This should answer the reader's question "What can MDAnalysis do for me?"

(Ordering of topics? First the "developer" oriented ones on AtomGroup etc or rather "user" oriented with analysis first?)


Ready-made building blocks with a common API

  • mention anything already published (ENCORE, water analysis, ...)
  • highlights? – add anything here that you'd like to write about

Working with MD data: trajectories, topologies, etc

Dealing with MD data in a unified is the core task in MDAnalysis, therefore we support many commonly used formats (and some uncommonly used ones, too):

  • topology formats
  • trajectory formats
    • special topics
      • MemoryReader
      • ChainReader
      • download from PDB with fetch_mmtf()
    • possibly some benchmarks on reading/writing?
  • selection writers (brief)
  • auxiliaries
  • on-the-fly transformations

Atom selection and working with AtomGroups

  • hierarchy of containers (Atom, AtomGroup, Residue, ResidueGroup, Segment, SegmentGroup) + fragments; indexing, slicing, groupby
  • selection language
  • set operations with groups
  • updating AtomGroup
  • highlighting some AtomGroup or Residue methods

Enabling algorithms

What do we use under the hood?

  • distance calculations
    • choose optimal algorithms (eg PR #2035 and much of @ayushsuhane's work — see also his notebooks and his GSOC summary)
  • RMSD (just mention QCPROT)
  • PBC treatment (hopefully consistent...)
    • user interface
    • algorithms (and perhaps benchmarks to show why we chose what we chose)

Development process and Community

  • development (CI, testing, PR/review/merge)
  • broad community (mailing lists, issue tracker), conferences, workshops
  • code of conduct

Example uses

Highlights from the literature

  • something that was accomplished with the help of MDAnalysis, e.g., scientific question answered
  • other packages/tools that use MDAnalysis

@richardjgowers - I think this is where MDA has really changed recently. I'm increasingly seeing cool applications built on top of MDA, which is hopefully because we've made a nice format-agnostic API. So I'd be interested in making this section prominent, a mini-review of MDA apps?


summary and future work and plans

Authorship model

We need to decide on how we want to deal with authorship. A few potential models:

  1. recent core developers (core developers with recent contributions; example: SciPy papers such as the SciPy 1.0 major paper draft)
  2. all core developers (past and present) (e.g. MDAnalysis 2011 paper)
  3. anyone who has contributed (example: Astropy 2.0 paper (arXiv:1801.02634, see also Khmer 2.0 and C. Titus Brown's rationale Pubwication of software papers, and authorship on them)

Notes on authorship

@orbeckst feels that authorship should require at a minimum

  1. code contributions (commits to develop/master)
  2. participation in paper writing
  3. approving the paper and committing to be accountable for the work (e.g., if you're the author of an analysis module, commit to fixing any issues that might come up)

The widely used ICMJE guidelines on authorship suggests that authorship be based on

  1. Substantial contributions to the conception or design of the work; or the acquisition, analysis, or interpretation of data for the work; AND
  2. Drafting the work or revising it critically for important intellectual content; AND
  3. Final approval of the version to be published; AND
  4. Agreement to be accountable for all aspects of the work in ensuring that questions related to the accuracy or integrity of any part of the work are appropriately investigated and resolved.

@orbeckst feels that for software, almost all contributions are important and it is not straightforward to always measure the impact of code contributions; certainly not by line of codes or number of PRs. See also Pubwication of software papers, and authorship on them.


The journal prescribes the length of the article.

Some suggestions

Project Information

GNU GPL v2 code license
Labels: python, molecular dynamics, analysis, DCD, CHARMM, LAMMPS, NAMD, Gromacs, computer simulation, atoms, coordinates, trajectory, XTC, Library, object-oriented
Core Developers


Release Notes
Guide for Developers
Google Summer of Code

Code of Conduct


@mdanalysis on Twitter
Downloads (PyPi)
Mailing Lists:
User discussion group
Developer mailing list

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.