[gmx-developers] g_spatial man page

[Chris Neale]

I have updated the following pages:
http://wiki.gromacs.org/index.php/Manual:g_spatial_3.3.2
http://wiki.gromacs.org/index.php/Manual:g_spatial_3.3.99_development_20070612

These pages link to a new page that I created:
http://wiki.gromacs.org/index.php/micelle_clustering

However, a [[g_spatial]] back-link from that page doesn't connect 
properly. I don't know how to fix that. This
appears to be a general problem. Perhaps we should create a page called 
e.g. trjconv that links to whatever is the
current stable version of e.g. trjconv is?

Also, the first time that I made the change it was soon overwritten back 
to g_cluster. In case that happens again, here is the text for the 
g_spatial page.

== Description ==

g_spatial calculates the spatial distribution function (SDF) and outputs 
it in a
form that can be read by VMD as Gaussian98 cube format. This was developed
from template.c (gromacs-3.3). For a system of 32K atoms and a 50ns
trajectory, the SDF can be generated in about 30 minutes, with most of the
time dedicated to the two runs through [[trjconv]] that are required to 
center
everything properly. This also takes a whole bunch of space (3 copies of the
xtc file). Still, the pictures are pretty and very informative when the
fitted selection is properly made. 3-4 atoms in a widely mobile group like a
free amino acid in solution works well, or select the protein backbone in a
stable folded structure to get the SDF of solvent and look at the
time-averaged solvation shell. It is also possible using this program to
generate the SDF based on some arbitrary Cartesian coordinate. To do that,
simply omit the preliminary [[trjconv]] steps.

== Usage ==
1. Use make_ndx to create a group containing the atoms around which you want
the SDF
2. [[trjconv]] -s a.[[tpr]] -f a.[[xtc]] -o b.[[xtc]] -center tric 
<code>-ur</code> compact <code>-pbc</code> none
3. [[trjconv]] -s a.[[tpr]] -f b.[[xtc]] -o c.[[xtc]] -fit rot+trans
4. run g_spatial on the xtc output of step #3.
5. Load grid.cube into VMD and view as an isosurface.
Note: Systems such as micelles will require [[micelle clustering]] 
between steps 1 and 2

== Warnings ==
The SDF will be generated for a cube that contains all bins that have some
non-zero occupancy. However, the preparatory -fit rot+trans option to 
trjconv
implies that your system will be rotating and translating in space (in order
that the selected group does not). Therefore the values that are returned
will only be valid for some region around your central group/coordinate that
has full overlap with system volume throughout the entire translated/rotated
system over the course of the trajectory. It is up to the user to ensure
that this is the case.

== Bugs ==
When the allocated memory is not large enough, a segmentation fault may
occur. This is usually detected and the program is halted prior to the fault
while displaying a warning message suggesting the use of the 
<code>-nab</code> option.
However, the program does not detect all such events. If you encounter a
segmentation fault, run it again with an increased <code>-nab</code> value.

== Risky Options ==
To reduce the amount of space and time required, you can output only the
coordinates that are going to be used in the first and subsequent run 
through
trjconv. However, be sure to set the -nab option to a sufficiently high 
value
since memory is allocated for cube bins based on the initial coordinates 
and the
-nab (Number of Additional Bins) option value.

== Alternatives ==
g_sdf also produces spatial distribution functions. g_spatial differs 
from g_sdf in that g_spatial
gives the user full control of the alignment procedure. The downside is 
that g_spatial requires
more time and more disk space.

== Files ==
 Option     Filename     Type         Description
 -----------------------------------------------------
  -s      topol.[[tpr]]  Input        Structure+mass(db): [[tpr]] 
[[tpb]] [[tpa]] [[gro]] [[g96]] [[pdb]]
                                   xml
  -f       traj.[[xtc]]  Input        Generic trajectory: [[xtc]] 
[[trr]] [[trj]] [[gro]] [[g96]] [[pdb]]
  -n      index.[[ndx]]  Input, Opt.  Index file

== Options ==
 Option     Filename     Type         Description
 -----------------------------------------------------
      -[no]h   bool    yes  Print help info and quit
       -nice    int      0  Set the nicelevel
          -b   time      0  First frame (ps) to read from trajectory
          -e   time      0  Last frame (ps) to read from trajectory
         -dt   time      0  Only use frame when t MOD dt = first time (ps)
      -[no]w   bool     no  View output [[xvg]], [[xpm]], [[eps]] and 
[[pdb]] files
    -[no]pbc   bool     no  Use periodic boundary conditions for computing
                            distances
    -[no]div   bool    yes  Calculate and apply the divisor for bin
                            occupancies based on atoms/minimal cube 
size. Set
                            as TRUE for visualization and as FALSE (-nodiv)
                            to get accurate counts per frame
        -ign    int     -1  Do not display this number of outer cubes
                            (positive values may reduce boundary 
speckles; -1
                            ensures outer surface is visible)
        -bin   real   0.05  Width of the bins in nm
        -nab    int      4  Number of additional bins to ensure proper 
memory
                            allocation


Mark Abraham wrote:
> 'm forwarding a GROMACS Wiki query here
> http://wiki.gromacs.org/index.php/Manual_talk:g_spatial_3.3.99_development_20070612
> -  it seems that the cvs source for the manpage of g_spatial is a copy of
> g_cluster. Presumably this should change at some stage.
>
> Mark
>
> _______________________________________________
> gmx-developers mailing list
> gmx-developers at gromacs.org
> http://www.gromacs.org/mailman/listinfo/gmx-developers
> Please don't post (un)subscribe requests to the list. Use the 
> www interface or send it to gmx-developers-request at gromacs.org.
>