Quickstart guide

[lilyminium]

Story: As a molecular dynamics user, I want to set up MDAnalysis quickly and easily, so that I can move onto further analysis.

Story: As a molecular dynamics user, I want to convert my AMBER trajectory into a GROMACS format, so that I can use the GROMACS analysis tools on it.

Acceptance criteria:

• [x] I know how to load in a coordinate file / simulation and write it out almost immediately
• [x] I understand the arguments necessary to create ('set up') a Universe, basic atom selection, basic analysis, and writing out coordinates.
• [ ] I understand where to look for less general knowledge (e.g. complex selection).
• [ ] I have links to an index of examples, available analyses, and a tutorial for developing custom analyses.

Current state

A survey of recent mdnalysis-discussion group questions found few questions about absolute basic MDAnalysis, although there is general confusion in how to write out trajectory coordinates. This suggests that the current MDAnalysis tutorial is doing a decent job. Many of the analysis-related questions were really asking whether a particular analysis had been implemented, or how to use it, likely because the tutorial only shows RMSD and the current docs can be confusing.

Proposal

A Jupyter notebook tutorial so that users can follow online or download and modify the resource. This will pull liberally from the existing MDAnalysis tutorial, as an express version without exercises.

Sections:

1. Link to page on installation.
2. Load in a Universe.
3. Writing out coordinates.
4. Basic introduction to AtomGroups, ResidueGroups, SegmentGroups.
5. Selecting atoms.
6. Trajectories and positions.
7. Universe persistence.
8. Introduction to Analysis and modules.

[richardjgowers]

Re coordinate writing: I suspect that some people might just be using MDA to go from one traj format to another (ie using it like openbabel). This might be so they can take their X format results and use it in Y format's analysis tools. I think we once floated ideas of having a little command line utility for doing this sort of conversion. Maybe this is a story in itself? I.e. I don't want to actually use MDAnalysis, just turn my TRR into a DCD.

[lilyminium]

Thanks @richardjgowers, I added that to the issue and rearranged the order of the guide to suit. mdtraj has a similar tool called mdconvert but the available formats look quite a bit more limited. Passing in selection strings and strides could make that utility really useful -- even within GROMACS trajectories, putting together an index file to process them can be annoying.

[orbeckst]

If we want scripts/mini-tools then we would likely put them into a separate package & repo. A simple converter would be a good start to prototype the whole thing.

(Writing this code is not really part of GSoD but we can certainly discuss it here...)

[orbeckst]

Btw, there's a FAQ https://github.com/MDAnalysis/mdanalysis/wiki/FAQ#how-can-i-convert-a-dcd-file-to-a-trr-file

[orbeckst]

Stupid question: shouldn't this issue be closed, given that you created a Quickstart Guide? Or is something missing?

[lilyminium]

I left it open so I'd remember to go through and link to pages that didn't exist when I made the guide, e.g. the formats overview, topology system, and so on.