Module core

source code

:mod:`analysis.core` -- Core classes for analysis of Gromacs trajectories
=========================================================================

This documentation is mostly of interest to programmers who want to write
analysis plugins.


Programming API for plugins
---------------------------

Additional analysis capabilities are added to a
:class:`gromacs.analysis.Simulation` class with *plugin* classes. For
an example see :mod:`gromacs.analysis.plugins`.


API description
...............

Analysis capabilities can be added with plugins to the simulation class. Each
plugin is registered with the simulation class and provides at a minimum
:meth:`~Worker.run`, :meth:`~Worker.analyze`, and :meth:`~Worker.plot` methods.

A plugin consists of a subclass of :class:`Plugin`  and an associated :class:`Worker`
instance. The former is responsible for administrative tasks and documentation,
the latter implements the analysis code.

A plugin class must be derived from :class:`Plugin` and typically bears the
name that is used to access it. A plugin instance must be *registered* with a
:class:`Simulation` object. This can be done implicitly by passing the
:class:`Simulation` instance in the ``simulation`` keyword argument to the
constructor or by explicitly calling the :meth:`Plugin.register` method with
the simulation instance. Alternatively, one can also register a plugin via the
:meth:`Simulation.add_plugin` method.

Registering the plugin means that the actual worker class is added to the
:attr:`Simulation.plugins` dictionary.

A plugin must eventually obtain a pointer to the :class:`Simulation` class in
order to be able to access simulation-global parameters such as top directories
or input files.

See :class:`analysis.plugins.CysAccessibility` and
:class:`analysis.plugins._CysAccessibility` in
``analysis/plugins/CysAccessibility.py`` as examples.


API requirements
................

* Each plugin is contained in a separate module in the
  :mod:`gromacs.analysis.plugins` package. The name of the module *must* be the
  name of the plugin class in all lower case.

* The plugin name is registered in
  :const:`gromacs.analysis.plugins.__plugins__`. (Together with the file naming
  convention this allows for automatic and consistent loading.)

* The plugin itself is derived from :class:`Plugin`; the only changes are the
  doc strings and setting the :attr:`Plugin.worker_class` class attribute to a
  :class:`Worker` class.

* The corresponding worker class is derived from :class:`Worker` and must implement 
  
  - :meth:`Worker.__init__` which can only use keyword arguments to initialize
    the plugin. It must ensure that init methods of super classes are also
    called. See the existing plugins for details.

  - :meth:`Worker.run` which typically generates the data by analyzing a
    trajectory, possibly multiple times. It should store results in files.

  - :meth:`Worker.analyze` analyzes the data generated by :meth:`Worker.run`.

  - :meth:`Worker.plot` plots the analyzed data.

  - :meth:`Worker._register_hook` (see below)

* The worker class can access parameters of the simulation via the
  :attr:`Worker.simulation` attribute that is automatically set when the plugin
  registers itself with :class:`Simulations`. However, the plugin should *not*
  rely on :attr:`~Worker.simulation` being present during initialization
  (__init__) because registration of the plugin might occur *after* init.

  This also means that one cannot use the directory methods such as
  :meth:`Worker.plugindir` because they depend on :meth:`Simulation.topdir` and
  :meth:`Simulation.plugindir`. 

  Any initialization that requires access to the :class:`Simulation` instance
  should be moved into the :meth:`Worker._register_hook` method. It is called
  when the plugin is actually being registered. Note that the hook *must* also
  call the hook of the super class before setting any values. The hook should
  pop any arguments that it requires and ignore everything else.

* Parameters of the plugin are stored in :attr:`Worker.parameters` (either as
  attributes or as key/value pairs, see the container class
  :class:`gromacs.utilities.AttributeDict`).

* Results are stored in :attr:`Worker.results` (also a :class:`gromacs.utilities.AttributeDict`).


Classes
-------

.. autoclass:: Simulation
   :members: add_plugin, set_plugin, get_plugin, run,
             analyze, plot, run_all, analyze_all, _apply_all,
             topdir, plugindir, check_file, has_plugin,
             check_plugin_name, current_plugin
   :show-inheritance:

.. autoclass:: Plugin
   :members: worker_class, register

   .. attribute:: Plugin.plugin_name

      Name of the plugin; this must be a *unique* identifier across
      all plugins of a :class:`Simulation` object. It should also be
      human understandable and must be a valid python identifier as it
      is used as a dict key.

   .. attribute:: Plugin.simulation

      The :class:`Simulation` instance who owns the plugin. Can be
      ``None`` until a successful call to :meth:`~Plugin.register`.

   .. attribute:: Plugin.worker

      The :class:`Worker` instance of the plugin.
            

.. autoclass:: Worker   
   :members: topdir, plugindir, savefig, _register_hook
   :show-inheritance: