Grid counter g_ri3Dc and analysis tools
Copyright (C) 2003-2011 Oliver Beckstein <[email protected]>
Published under the GNU General Public License version 2 (or higher)
(see the file LICENCE)

-------------------------------------------------------------------
UNSUPPORTED AND DEPRECATED

Development and support for this tool has been discontinued.
If you have questions/bugs please put them in the issue tracker
https://github.com/orbeckst/gridcount/issues to keep a record.

If you are fixing bugs please send PULL REQUESTS.

For more modern/universal approaches to accomplishing similar
analysis look at https://www.mdanalysis.org and there are now
also some Gromacs tools that do similar things.
--------------------------------------------------------------------


Short introduction
==================

g_ri3Dc counts occurrences of molecules on a 3D grid over a MD
trajectory. A typical application is to choose the water index group
as the molecules to be counted. This creates (after proper
normalisation) a 3D density map. The map is written in a
system-independent (xdr) grid file (format defined in grid3D.h) for
once and all.

Note that for most practical purposes you should center your
trajectory on your molecule of interest so that it does not diffuse
through the grid. This is especially important for pore proteins,
carbon nano tubes and the like when you want to calculate
cylindrically averaged densities with the analysis program.

The grid file is read in by a_ri3Dc, the analysis and converter
tool. At the moment it is mainly useful to calculate cylindrical and
slice averages and convert the density map into gOpenMol's plt format,
which can also be read by VMD (from version 1.8.2
onwards). Alternatively, it also outputs the whole grid in ASCII
format.

It outputs 1D graphs (can be displayed with xmgrace
http://plasma-gate.weizmann.ac.il/Grace/) and 2D data and parameter
files which are suitable for xfarbe (A. Preusser,
http://www.fhi-berlin.mpg.de/~grz/pub/xfarbe.html).

a_gridcalc can be used to average densities. The plan is to extend it
into a more versatile grid calculator (but then again, it may be
easier using numeric python, dx, or any other software already written
for such purposes.)

As an example I added a Makefile (examples/Makefile.grid) that I use
to create a whole bunch of graphics, including eps from the 2D plots
(see the top of Makefile.grid for instructions). examples/slicer.pl is
a small script to generate a succession of 2D density slices of a
given width.


Citing
======

When you use gridcount in published work, please cite

  O. Beckstein and Mark S. P. Sansom, Liquid-vapor oscillations of
  water in hydrophobic nanopores, Proc. Natl. Acad. Sci. USA. 100
  (2003), 7063-7068. doi:10.1073/pnas.1136844100



Documentation
=============

Please bear in mind that this is not a finished product. It is
provided in the hope that it might be useful to others but it might
require some work on your part to figure out how to put it to best
use.

Please read the output of -h to get started; the source code has also
some documentation (apart from the 'self-documenting code'
itself...). The examples/Makefile.grid shows real-life usage and has
instructions for usage in the comments at the top.

Examples of figures created with these programs can be found on
http://sbcb.bioch.ox.ac.uk/oliver/research/pores/hyphobpores.html#liquidvapourosc,
Beckstein and Sansom, PNAS 100 (2003), 7063 and Beckstein and Sansom,
Phys Biol 1 (2004), 43, http://stacks.iop.org/1478-3975/1/42 or
http://arxiv.org/abs/q-bio/0402041. 


The latest released version of gridcount is available at 

   http://sbcb.bioch.ox.ac.uk/oliver/software/#gridcount

The current source code (including development version) can be found
at 

   https://github.com/orbeckst/gridcount/

Note that the various versions are maintained in different git
branches. For instance, the version for Gromacs 4.5 is to be found in
the `gromacs_4.5` branch, e.g.

  https://github.com/orbeckst/gridcount/tree/gromacs_4.5

You would get the source code with

  git clone -b gromacs_4.5 https://github.com/orbeckst/gridcount.git

A version history can be found in the file CHANGELOG.

Questions from users and (more or less) helpful answers are in the
file FAQ.



Additional software
===================

Gromacs   http://www.gromacs.org (version 4.x) 
xfarbe    http://www.fhi-berlin.mpg.de/~grz/pub/xfarbe.html
VMD       http://www.ks.uiuc.edu/Research/vmd/
gOpenMol  http://www.csc.fi/gopenmol/



BUGs and such
=============

Note: bugs will only be fixed if someone submits a Pull Request.

-------------------------------------------------------------------
UNSUPPORTED AND DEPRECATED

Development and support for this tool has been discontinued.
If you have questions/bugs please put them in the issue tracker
https://github.com/orbeckst/gridcount/issues to keep a record.

If you are fixing bugs please send PULL REQUESTS.
-------------------------------------------------------------------

* See https://github.com/orbeckst/gridcount/issues for known bugs.

* Problems during compilation/installation: see INSTALL

* PLEASE read the documentation produced by running the programs with
  the '-h' flag and in particular note the 'BUGs and known limitation'
  section of the output.

* The analysis tool is fairly limited. I use it to generate densities
  in channels and pores (that's why it only does cylindrical
  averages). If you need spherical spatial distribution functions look
  into Christoph Freudenberger's g_sdf.

* When the box size or shape changes over time (for instance, due to
  pressure coupling or centering of a trajectory on a protein) then
  the outer regions of the density are necessarily ill defined and
  need to be discarded.

* Only works with rectangular boxes.


See Also
========

* MDAnalysis Volumetric Analysis: 
  https://www.mdanalysis.org/docs/documentation_pages/analysis_modules.html#volumetric-analysis
* g_densmap, g_spatial and g_rdf in the standard Gromacs source
  distribution
* load density data into NumPy arrays and use the power of Python
  (e.g. https://github.com/orbeckst/GridDataFormats )


Missing features
================

(Note: features will only be added if someone submits a Pull Request.)

* The native density format should be something like OpenDX because
  then it would be more interoperable and easier to manipulate with
  existing tools.

* Triclinic box support should be added.

* Currently only atoms can be counted, not molecules.