doc example for crafting hbond autocorrelation groups

[orbeckst]

Expected behavior

Creating the input atomgroups (donors, hydrogens, acceptors) for hbond autocorrel should be easy/self explanatory.

Actual behavior

It is rather difficult with recurring questions on the mailing list (eg https://groups.google.com/d/msg/mdnalysis-discussion/-gwmJANsSXM/g-oD1byEFAAJ and issue tracker eg #1563), especially when it comes to water: It is not clear to most users how to generate donor and hydrogen atomgroups that correspond to each other

Three AtomGroup selections representing the hydrogens, donors and acceptors that you wish to analyse. Note that the hydrogens and donors selections must be aligned, that is hydrogens[0] and donors[0] must represent a bonded pair. If a single donor therefore has two hydrogens, it must feature twice in the donors AtomGroup.

Proposed action
Add an example to the docs that shows how to use the module with one of our test systems (e.g., with something from MDAnalysisData) and in particular, water.

Currently version of MDAnalysis

All recent (~0.18 - 0.19) versions of MDA (but really since 0.9).

[orbeckst]

@richardjgowers – I think you answered this question before. Can you find your answer(s) from the mailinglist or issue tracker and link them here? This would be a good starting point for the doc fix.

[richardjgowers]

Will do. Another option is to allow this to be more automatic based on bonding... will check what’s possible

…

On Mon, Jan 21, 2019 at 2:10 PM, Oliver Beckstein ***@***.***> wrote: @richardjgowers <https://github.com/richardjgowers> – I think you answered this question before. Can you find your answer(s) from the mailinglist or issue tracker and link them here? This would be a good starting point for the doc fix. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2181 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AI0jB5KwLyUY9i4RZowus2T27o5nb8Kiks5vFh6ZgaJpZM4aLdU5> .

[orbeckst]

Related:

Further I noted there are two utilities for hydrogen bond lifetime calculation.
https://www.mdanalysis.org/docs/documentation_pages/analysis/hbond_autocorrel.html
https://www.mdanalysis.org/docs/documentation_pages/analysis/waterdynamics.html

Is there any difference in between them. Both are based on time-correlation defination of hydrogen bonds?

You need to read the papers in detail. I don't know the answer. The waterdynamics module is primarily for water and calculates a whole bunch of properties in a consistent manner. The hbond_autocorrel module is very flexible in what input it can take and has been used for, e.g., polymers. However, I wish I had a better and more concise answer for you – if the original authors (@richardjgowers and @alejob ) read this then it would be great if they could come up with a better answer that we can include in the docs.

[orbeckst]

Another option is to allow this to be more automatic based on bonding... will check what’s possible

That's nice when we have bonding information. But it's also very valuable that in principle you can fully determine what should be considered donor/hydrogen.

I tried to give an answer on the mailing list but it's pretty clunky and not very elegant. I don't know how to do flatten(zip(ag, ag)) to construct a new AG.

[orbeckst]

@richardjgowers The formatting is garbled, please see https://www.mdanalysis.org/mdanalysis/documentation_pages/analysis/hbond_autocorrel.html

[orbeckst]

The other thing that I overlooked was that we should not use

Examples
--------

anywhere outside classes/functions. Call it "Example for xxx"