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 3.1
  11  * Copyright (c) 1991-2001, University of Groningen, The Netherlands
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * If you want to redistribute modifications, please consider that
  18  * scientific software is very special. Version control is crucial -
  19  * bugs must be traceable. We will be happy to consider code for
  20  * inclusion in the official distribution, but derived work must not
  21  * be called official GROMACS. Details are found in the README & COPYING
  22  * files - if they are missing, get the official version at www.gromacs.org.
  23  *
  24  * To help us fund GROMACS development, we humbly ask that you cite
  25  * the papers on the package - you can find them in the top README file.
  26  *
  27  * For more info, check our website at http://www.gromacs.org
  28  *
  29  * And Hey:
  30  * Green Red Orange Magenta Azure Cyan Skyblue
  31  */
  32
  33 #include "typedefs.h"
  34
  35 #define FLAG_DOTS       01
  36 #define FLAG_VOLUME     02
  37 #define FLAG_ATOM_AREA  04
  38
  39 #define NSC nsc_dclm
  40
  41 extern int NSC(
  42   real * ,      /* atom coordinates xyz0, xyz1, ... */
  43   real * ,      /* atom radii r0, r1, r2, ... */
  44   int ,         /* number of atoms */
  45   int ,         /* number of dots per fully accessible sphere */
  46   int ,         /* flag : dots, volume and/or area per atom */
  47   real * ,      /* 1 output: overall area */
  48   real ** ,     /* 2 output: pointer to list of areas per atom */
  49   real * ,      /* 3 output: overall volume */
  50   real ** ,     /* 4 output: pointer to list of surface dots x0, y0, z0, ... */
  51   int *         /* 5 output: number of surface dots */
  52   );
  53
  54 extern int nsc_dclm2(rvec *coords, real *radius, int nat, atom_id index[],
  55                      int  densit, int mode,
  56                      real *value_of_area, real **at_area,
  57                      real *value_of_vol,
  58                      real **lidots, int *nu_dots,
  59                      matrix box);
  60
  61 /*
  62     User notes :
  63 The input requirements :
  64   The arrays with atom coordinates and radii are thought to start
  65   with index 0, i.e., places 0, 1, and 2 are the x-, y-, and z-
  66   coordinates of the zero-th atom and place 0 in the other array
  67   is its radius.
  68
  69   PLEASE TAKE INTO ACCOUNT THAT THE RADII GIVEN HERE ARE DIRECTLY
  70   USED FOR SURFACE CALCULATION. NSC does not increment with a probe
  71   radius.
  72
  73   The user can define any number of dots. The program selects a
  74   dot density that is the lowest possible with at least the required
  75   number of dots. The points are distributed in accordance with the
  76   icosahedron-based or the dodecahedron-based method as described in
  77   ref. 1.
  78
  79 The output requirements are :
  80   1 and 3 :  pointer to an existing real
  81   2 and 4 :  pointer to an existing pointer to real
  82              NSC allocates memory for an array
  83   5       :  pointer to an existing integer
  84
  85 The subroutine NSC makes use of variant 2 described in reference 1.
  86 By selecting the necessary output via flags, the requirements for
  87 cpu-time and computer memory can be adapted to the actual needs.
  88
  89 Example : flag = FLAG_VOLUME | FLAG_ATOM_AREA | FLAG_DOTS
  90           The routine calculates the area, volume and the dot surface. The
  91           program allocates arrays for the atomwise areas and for the surface
  92           dots. The addresses are returned in the pointers to pointers to
  93           real.
  94           This variant is not recommended because normally the dot surface
  95           is needed for low point density (e.g.42) at which area and volume
  96           are inaccurate. The sign "|" is used as binary AND !
  97
  98           flag = FLAG_VOLUME | FLAG_ATOM_AREA
  99           In this case the large arrays for storing the surface dots
 100           are not allocated. A large point number of the fully accessible
 101           sphere can be selected. Good accuracy is already achieved with
 102           600-700 points per sphere (accuracy of about 1.5 square Angstrem
 103           per atomic sphere).
 104           Output pointers 4 and 5 may be NULL.
 105
 106           flag = FLAG_DOTS
 107           Only the dot surface is produced.
 108           Output pointers 2 and 3 may be NULL.
 109
 110 The output pointer 1 cannot be set to NULL in any circumstances. The
 111 overall area value is returned in every mode.
 112
 113 All files calling NSC should include nsc.h !!
 114
 115
 116 Example for calling NSC (contents of user file):
 117
 118   ...
 119 #include "nsc.h"
 120
 121 int routine_calling_NSC(int n_atom, real *coordinates, real *radii) {
 122   real area, volume, *atomwise_area, *surface_dots;
 123   int    i, density = 300, n_dots;
 124
 125   ...
 126
 127   for (i=0; i<n_atom; i++) {
 128    radii[i]  += 1.4      /# add the probe radius if necessary #/
 129
 130   if (NSC(coordinates, radii, n_atom, density,
 131           FLAG_AREA | FLAG_VOLUME | FLAG_DOTS,
 132           &area, &atomwise_area, &volume, &surface_dots, &n_dots))
 133     printf("error occured\n");
 134     return 1;
 135     }
 136
 137   ...
 138
 139 /# do something with areas, volume and surface dots #/
 140
 141   ...
 142
 143   return 0;
 144   }
 145
 146 */