Home   Legal Note   Contact

Methodical Background

NSC is an implementation of the DCLM variant of the Shrake's and Rupley's algorithm for surface calculation.

Please refer to the article:

F.Eisenhaber, P.Lijnzaad, P.Argos, C.Sander, and M.Scharf
"The Double Cubic Lattice Method: Efficient Approaches to Numerical Integration of Surface Area and Volume and to Dot Surface Contouring of Molecular Assemblies"
Journal of Computational Chemistry (1995) v.16, N3, pp.273-284

The subroutine NSC makes use of variant 2 described in the reference. By selecting the necessary output via flags, the requirements for cpu-time and computer memory can be adapted to the actual needs.

!! All files calling NSC should include "nsc.h" !!

Syntax and Usage

int NSC(
  double * ,	/* a atom coordinates xyz0, xyz1, ... */
  double * ,	/* b atom radii r0, r1, r2, ... */
  int ,         /* c number of atoms */
  int ,		/* d number of dots per fully accessible sphere */
  int ,		/* e flag : dots, volume and/or area per atom */
  double * ,	/* 1 output: overall area */
  double ** ,   /* 2 output: pointer to list of areas per atom */
  double * ,	/* 3 output: overall volume */
  double ** ,	/* 4 output: pointer to list of surface dots x0, y0, z0, ... */
  int *		/* 5 output: number of surface dots */
  );

Items "a-e" are input data and refer to user-defined sections of memory (arrays or single numbers).

Items "a", "b", and "c":

The arrays with atom coordinates and radii are thought to start with index 0, i.e., places 0, 1, and 2 are the x-, y-, and z-coordinates of the zero-th atom and place 0 in the other array is its radius.

PLEASE TAKE INTO ACCOUNT THAT THE RADII GIVEN HERE ARE DIRECTLY USED FOR SURFACE CALCULATION. NSC does not increment with a probe radius !!

The user can define any number of dots. The program selects a dot density that is the lowest possible with at least the required number of dots.

The points are distributed in accordance with the icosahedron-based or the dodecahedron-based method as described in the reference in section (B). This selection is the most even triangulation of a unit sphere known to the author.

At this place, the user can define the mode of operation. I advise to use the predefined (in "nsc.h") values FLAG_DOTS, FLAG_VOLUME, and FLAG_ATOM_AREA.

flag = NULL
Only the overall area is calculated. Pointers 2-5 may be set equal to NULL.

flag = FLAG_VOLUME | FLAG_ATOM_AREA | FLAG_DOTS
The routine calculates the area, volume and the dot surface. The program allocates arrays for the atomwise areas and for the surface dots. The addresses are returned in the pointers to pointers to double.
This variant is not recommended because normally the dot surface is needed for low point density (e.g.42) at which area and volume are inaccurate. The sign "|" is used as binary AND !

flag = FLAG_VOLUME | FLAG_ATOM_AREA
In this case the large arrays for storing the surface dots are not allocated. A large point number of the fully accessible sphere can be selected. Good accuracy is already achieved with 600-700 points per sphere (accuracy of about 1.5 square Angstrem per atomic sphere).
Output pointers 4 and 5 may be NULL.

flag = FLAG_DOTS
Only the dot surface is produced in addition to the overall area.
Output pointers 2 and 3 may be NULL.

The output pointer 1 cannot be set to NULL in any circumstances. The overall area value is returned in every mode.

Items

1. pointer to an existing double
   
2. pointer to an existing pointer to double NSC allocates memory for an array
3. pointer to an existing double
   
4. pointer to an existing pointer to double NSC allocates memory for an array
5. pointer to an existing integer

Example for Calling NSC (contents of the user source file)

#include "nsc.h"

int routine_calling_NSC(int n_atom, double *coordinates, double *radii) {

double area, volume, *atomwise_area, *surface_dots;
int i, density = 300, n_dots;

.....

for (i=0; i < n_atom; i++) {


radii[i] += 1.4 /* add the probe radius if necessary */

}

if (NSC(coordinates, radii, n_atom, density,FLAG_AREA | FLAG_VOLUME | FLAG_DOTS,&area, &atomwise_area, &volume, &surface_dots, &n_dots)) {


printf("NSC: premature completion with error\n");
return 1;

}

.....

/* do something with areas, volume and surface dots */

.....

return 0;
}