Analysis plugins

The plugins were removed from GromacsWrapper in release 0.7.0 (see issue #82) and now live in the unmaintained repository https://github.com/Becksteinlab/gromacswrapper.analysis

---

Trajectory Analysis

Trajectory analysis follows the same philosophy as the rest of GromacsWrapper: use native Gromacs tools to do all the work and just provide some glue to run these tools and read in the data produced by these tools. Gromacs tools typically produce ASCII data files in the multi-column xmgrace format (read with xmgrace -nxy). Therefore, GromacsWrapper uses the XVG class to access these files. The advantage of the XVG class are that data is available via NumPy arrays and a number of plotting tools are available as methods including ways for coarse graining data.

Plugin system

GromacsWrapper contains a prototype of an analysis plugin system. The system assumes a workflow whereby the trajectory is produced and stored somewhere (TPR, XTC, EDR files at a minimum) and then analyzed. The simulation is described by an instance of the Simulation class. Analysis capabilities are added to the simulation class as plugins. The plugins use the data stored in the Simulation as they need it. Each plugin produces output in its own directory (under Simulation.analysis_dir). (The details for how plugins need to be written are described in the Programming API for Plugins.)

Simulation class

See the introduction to the Simulation class.

Basically:

from gromacs.analysis import Simulation
S = Simulation(tpr=TPR, xtc=XTC, edr=EDR, ndx=NDX, analysisdir="./analysis/run314")

Using plugins

The list of plugins shows what is currently implemented in GromacsWrapper (but of course it is possible to write one's own plugins — that was the whole idea of a plugin system).

Each plugin instance "belongs" to a Simulation object. One can

1. add plugins to an existing Simulation with the Simulation.add_plugin() method.
2. include the plugins in the constructor for the Simulation with the keyword plugins.

A plugin instance can often be customized, which translates into setting different arguments for the underlying Gromacs tool. For instance, the Distances plugin takes multiple index groups to define the atoms to compute distances between. The documentation for each plugin should be consulted.

Typical analysis

1. run() the analysis (that is, running the underlying Gromacs tool on the trajectories). This typically takes a long time. These primary data are saved in files.
2. analyze() the data that was produced; this might not do anything or it might carry out further complex analysis tasks. Either way, all "final" results are stored in the dict-like attribute Plugin.results.
3. plot() the data. Not all plugins implement the plot method, though.

Typically, if the primary data already exist, running step 1 (Simulation.run(plugin=PluginName)) will not do anything; the behaviour can be changed with the force=True flag.

Learning more

The examples below are not fully fleshed out but should give you an idea how to proceed. In general, I suggest you play around in ipython and use the introspection feature (e.g. try TAB completion S.<TAB>) together with the docs in order to find out what data is available in the plugins.

Examples

Single plugin: Energies

Like the previous example but uses the energy plugin, which does not need to be customized (if you're happy with the default energy terms — see the docs).

from gromacs.analysis import Simulation
from gromacs.analysis.plugins import Energy

S = Simulation(tpr="md.tpr", xtc="md.xtc", edr="md.edr", plugins=[Energy])
S.set_plugin("Energy")
S.run()
S.analyze()
S.plot()

If you set the current plugin then you don't have to provide the plugin name for run(), analyze(), and plot().

All data is stored with the plugin; you can get the actual object with

p = S.get_plugin('energy') 

or as the Simulation.current_plugin

p = S.current_plugin

Then look into the dict S.current_plugin.results — all plugins store their data in this place. In the case of Energy plugin it only contains a single item with key "Energy" that consists of an instance of the XVG class, which makes the contents of the xvg file available that is produced by g_energy.

Multiple plugins

See the plugin example in the docs.