src/tools/nsc.h

   1 /*
   2  * $Id$
   3  *
   4  *       This source code is part of
   5  *
   6  *        G   R   O   M   A   C   S
   7  *
   8  * GROningen MAchine for Chemical Simulations
   9  *
  10  *               VERSION 2.0
  11  *
  12  * Copyright (c) 1991-1999
  13  * BIOSON Research Institute, Dept. of Biophysical Chemistry
  14  * University of Groningen, The Netherlands
  15  *
  16  * Please refer to:
  17  * GROMACS: A message-passing parallel molecular dynamics implementation
  18  * H.J.C. Berendsen, D. van der Spoel and R. van Drunen
  19  * Comp. Phys. Comm. 91, 43-56 (1995)
  20  *
  21  * Also check out our WWW page:
  22  * http://md.chem.rug.nl/~gmx
  23  * or e-mail to:
  24  * gromacs@chem.rug.nl
  25  *
  26  * And Hey:
  27  * Great Red Oystrich Makes All Chemists Sane
  28  */
  29 static char *SRCID_nsc_h = "$Id$";
  30
  31 #include "typedefs.h"
  32
  33 #define FLAG_DOTS       01
  34 #define FLAG_VOLUME     02
  35 #define FLAG_ATOM_AREA  04
  36
  37 #define NSC nsc_dclm
  38
  39 extern int NSC(
  40   real * ,      /* atom coordinates xyz0, xyz1, ... */
  41   real * ,      /* atom radii r0, r1, r2, ... */
  42   int ,         /* number of atoms */
  43   int ,         /* number of dots per fully accessible sphere */
  44   int ,         /* flag : dots, volume and/or area per atom */
  45   real * ,      /* 1 output: overall area */
  46   real ** ,   /* 2 output: pointer to list of areas per atom */
  47   real * ,      /* 3 output: overall volume */
  48   real ** ,     /* 4 output: pointer to list of surface dots x0, y0, z0, ... */
  49   int *         /* 5 output: number of surface dots */
  50   );
  51
  52 /*
  53     User notes :
  54 The input requirements :
  55   The arrays with atom coordinates and radii are thought to start
  56   with index 0, i.e., places 0, 1, and 2 are the x-, y-, and z-
  57   coordinates of the zero-th atom and place 0 in the other array
  58   is its radius.
  59
  60   PLEASE TAKE INTO ACCOUNT THAT THE RADII GIVEN HERE ARE DIRECTLY
  61   USED FOR SURFACE CALCULATION. NSC does not increment with a probe
  62   radius.
  63
  64   The user can define any number of dots. The program selects a
  65   dot density that is the lowest possible with at least the required
  66   number of dots. The points are distributed in accordance with the
  67   icosahedron-based or the dodecahedron-based method as described in
  68   ref. 1.
  69
  70 The output requirements are :
  71   1 and 3 :  pointer to an existing real
  72   2 and 4 :  pointer to an existing pointer to real
  73              NSC allocates memory for an array
  74   5       :  pointer to an existing integer
  75
  76 The subroutine NSC makes use of variant 2 described in reference 1.
  77 By selecting the necessary output via flags, the requirements for
  78 cpu-time and computer memory can be adapted to the actual needs.
  79
  80 Example : flag = FLAG_VOLUME | FLAG_ATOM_AREA | FLAG_DOTS
  81           The routine calculates the area, volume and the dot surface. The
  82           program allocates arrays for the atomwise areas and for the surface
  83           dots. The addresses are returned in the pointers to pointers to
  84           real.
  85           This variant is not recommended because normally the dot surface
  86           is needed for low point density (e.g.42) at which area and volume
  87           are inaccurate. The sign "|" is used as binary AND !
  88
  89           flag = FLAG_VOLUME | FLAG_ATOM_AREA
  90           In this case the large arrays for storing the surface dots
  91           are not allocated. A large point number of the fully accessible
  92           sphere can be selected. Good accuracy is already achieved with
  93           600-700 points per sphere (accuracy of about 1.5 square Angstrem
  94           per atomic sphere).
  95           Output pointers 4 and 5 may be NULL.
  96
  97           flag = FLAG_DOTS
  98           Only the dot surface is produced.
  99           Output pointers 2 and 3 may be NULL.
 100
 101 The output pointer 1 cannot be set to NULL in any circumstances. The
 102 overall area value is returned in every mode.
 103
 104 All files calling NSC should include nsc.h !!
 105
 106
 107 Example for calling NSC (contents of user file):
 108
 109   ...
 110 #include "nsc.h"
 111
 112 int routine_calling_NSC(int n_atom, real *coordinates, real *radii) {
 113   real area, volume, *atomwise_area, *surface_dots;
 114   int    i, density = 300, n_dots;
 115
 116   ...
 117
 118   for (i=0; i<n_atom; i++) {
 119    radii[i]  += 1.4      /# add the probe radius if necessary #/
 120
 121   if (NSC(coordinates, radii, n_atom, density,
 122           FLAG_AREA | FLAG_VOLUME | FLAG_DOTS,
 123           &area, &atomwise_area, &volume, &surface_dots, &n_dots))
 124     printf("error occured\n");
 125     return 1;
 126     }
 127
 128   ...
 129
 130 /# do something with areas, volume and surface dots #/
 131
 132   ...
 133
 134   return 0;
 135   }
 136
 137 */