Scalar Grids

A grid is a data container that holds a value at every point in a three dimensional lattice. The simplest type of value to hold is a floating point value. In OEChem TK, these are called OEScalarGrids. OEScalarGrids are inherently cubic.

The following fundamental parameters define a grid:

Dimension

The number of grid points per axis

Midpoint

The center of the grid in Cartesian space

Spacing

The length between grid points

Fundamental Grid Parameters

Listing 1 demonstrates how to construct a grid with 64 points in each direction, a midpoint at the origin, and a spacing of 0.5 between each point in the grid.

Listing 1: Constructing a scalar grid

#include "openeye.h"
#include "oegrid.h"
    
using namespace OESystem;

int main(int, char **)
{
  OEScalarGrid grid(64, 64, 64, 0.0f, 0.0f, 0.0f, 0.5f);

  return 0;
}

Note

The memory footprint of the grid is determined by the dimensions. It is easy to create grids that are too large for memory. For example, the grid in Listing 1 will consume \(64^3 * sizeof(float) = 1048576 bytes = 1 MB\) of memory for this nominally sized grid.

Minimum and maximum

Every grid can have its maximum and minimum vales reported by GetXMax, GetXMin etc. The image Grid coordinates shows a 2D representation for simplicity. It shows 4 grid points centered at (0,0), with a spacing of 1.0. Each grid point will have spatial coordinates (0.5,0.5), (-0.5,0.5) etc. However each grid point lies at the center of a pixel (or rather a voxel in 3D). Any property that falls into the area (volume) of that grid point is mapped to that grid point. This means that the maximum value of x is the extent of the grid, not just the maximum value of the grid point coordinates. In this case that value is 1.0.

Grid coordinates

Data Access

Grids provide three ways to index data inside the grid. They are ordered here by speed of access, i.e., grid elements perform simple pointer arithmetic where spatial coordinates require floating point computation.

Grid Element

Index into the underlying data array

Grid Indices

Unsigned integers less than the dimension for that axis

Spatial Coordinates

Cartesian coordinates of any point inside the grid, the grid will determine the closest grid point

Spatial Coordinates

Assuming grid is already filled with relevant values, Listing 2 demonstrates how to retrieve the grid value closest to the atoms in the molecule mol.

Listing 2: Getting values associated with coordinates

for (OEIter<OEAtomBase> atom = mol.GetAtoms(); atom; ++atom)
{
  float xyz[3];
  mol.GetCoords(atom, xyz);
  if (grid.IsInGrid(xyz[0], xyz[1], xyz[2]))
    std::cout << std::fixed << "value = " << grid(xyz[0], xyz[1], xyz[2]) << std::endl;
}

Spatial coordinates can also be used to set data on the grid. Listing 3 demonstrates how to assign an atom’s partial charge to the grid point it is closest to.

Listing 3: Setting values associated with coordinates

for (OEIter<OEAtomBase> atom = mol.GetAtoms(); atom; ++atom)
{
  float xyz[3];
  mol.GetCoords(atom, xyz);
  if (grid.IsInGrid(xyz[0], xyz[1], xyz[2]))
    grid(xyz[0], xyz[1], xyz[2]) = (float)atom->GetPartialCharge();
}

Note

In the preceding two code fragments bounds checking was explicitly performed using the IsInGrid method. Accessing data outside the grid is undefined behavior (usually a segmentation fault). However, IsInGrid can become an expensive operation if performed excessively. One way to avoid this cost is to make sure your grid is big enough to enclose the object being worked on. See OEMakeGridFromCenterAndExtents for an example of constructing a grid that covers the entire molecule to ensure no spatial coordinate access is outside the bounds of the grid.

Grid Indices

Grid indices are faster than spatial coordinates because there is no floating point arithmetic to perform. Grid indices make it easy to iterate over the neighbors of any particular point in the grid. Listing 4 demonstrates iterating over all 27 grid points adjacent to and including the grid point given by the grid indices: ix, iy, iz.

Listing 4: Iterating over neighbor points

float xyz[3];
mol.GetCoords(atom, xyz);

unsigned int ix, iy, iz;
grid.SpatialCoordToGridIdx(xyz[0], xyz[1], xyz[2], ix, iy, iz);

// Make sure not to go past grid bounds
unsigned int mini = (ix == 0 ? 0 : ix - 1);
unsigned int minj = (iy == 0 ? 0 : iy - 1);
unsigned int mink = (iz == 0 ? 0 : iz - 1);
unsigned int maxi = std::min(ix + 1, grid.GetXDim());
unsigned int maxj = std::min(iy + 1, grid.GetYDim());
unsigned int maxk = std::min(iz + 1, grid.GetZDim());

std::cout.precision(5);
for (unsigned int k = mink; k < maxk; k++)
  for (unsigned int j = minj; j < maxj; j++)
    for (unsigned int i = mini; i < maxi; i++)
      std::cout << std::fixed << "value = " << grid(i, j, k) << std::endl;

Grid Elements

Grid values are actually stored in a large one dimensional block of memory. The fastest way to access all the data is to linearly scan through memory. Listing 5 demonstrates how to square every value in the grid.

Listing 5: Squaring every grid value

for (unsigned int i = 0; i < grid.GetSize(); ++i)
  grid[i] = grid[i] * grid[i];

Direct access to the memory is given by the GetValues method. This allows faster memory functions, e.g., memset and memcpy, to be applied to grid values. The following code is the quickest way to zero out all the grid values.

Clearing all grid data

memset(grid.GetValues(), 0, grid.GetSize()*sizeof(float));

Input and Output

The following grid file formats are supported:

OEChem TK grid file format support

Grid File Type (or reader)	File Extension(s)	Description	Read	Write
OEGridFileType::Grasp	.phi	GRASP	Yes	Yes
OEGridFileType::GRD	.grd	OpenEye Binary format	Yes	Yes
OEGridFileType::Ascii	.agd	OpenEye ASCII format	Yes	Yes
OEGridFileType::CCP4	.map .ccp .ccp4	CCP4 format	Yes	Yes
OEGridFileType::XPLOR	.xplor .xplmap	XPLOR format	Yes	No
OEReadMTZ	.mtz	MTZ crystallographic reflection format	Yes	No

The ASCII format (.agd) was developed by OpenEye to allow for easy integration with other software. The following is an example of the ASCII output for a grid centered at the origin, 2 points along each axis, a spacing of 0.5, and every value zero.

Title: Example Grid
Mid:     0.000000     0.000000     0.000000
Dim:      2      2      2
Spacing:     0.500000
Values:
0.000000e+00
0.000000e+00
0.000000e+00
0.000000e+00
0.000000e+00
0.000000e+00
0.000000e+00
0.000000e+00

Listing 6 is the code used to write the ASCII format out. It is provided here to leave no doubt as to how to inter-operate with the format.

Listing 6: Writing the ASCII format

#include "openeye.h"
#include "oegrid.h"
    
using namespace OESystem;

int main(int, char **)
{
  OEScalarGrid grid(2, 2, 2, 0.0f, 0.0f, 0.0f, 0.5f);
  grid.SetTitle("Simple Grid");

  std::cout << "Title: " << grid.GetTitle() << std::endl;
  
  char buffer[80];
  snprintf(buffer, 80, "Mid: %12.6f %12.6f %12.6f", grid.GetXMid(), grid.GetYMid(), 
  grid.GetZMid());
  std::cout << buffer << std::endl;
  
  unsigned int xdim = grid.GetXDim();
  unsigned int ydim = grid.GetYDim();
  unsigned int zdim = grid.GetZDim();
  
  snprintf(buffer, 80, "Dim: %6d %6d %6d", xdim, ydim, zdim);
  std::cout << buffer << std::endl;
  
  snprintf(buffer, 80, "Spacing: %12.6f", grid.GetSpacing());
  std::cout << buffer << std::endl;
  
  std::cout << "Values:" << std::endl;
  for (unsigned int iz=0; iz<zdim; ++iz)
    for (unsigned int iy=0; iy<ydim; ++iy)
      for (unsigned int ix=0; ix<xdim; ++ix)
      {
        printf("%-12.6e\n", grid.operator()(ix,iy,iz));
      }

  return 0;
}

Grid as Generic Data

Grids can also be attached to molecules and then written out to OEBinary (.oeb) files. A visualizer can then read in the molecule and grid without any other means of making the association. Listing 7 demonstrates how to attach a Gaussian grid to the molecule it was created from.

The grid is attached to a molecule using the ‘generic data’ interface provided by the OEBase base class. This allows an arbitrary number of grids (or any type of data) to be attached to molecules. Since all grids also derive from OEBase generic data can be attached to grids as well allowing for arbitrarily complex data hierarchies.

Listing 7: Attaching a grid to a molecule

OEScalarGrid grid;
OEMakeMolecularGaussianGrid(grid, mol, 0.5f);

mol.SetData<OEScalarGrid>("Gaussian Grid", grid);

OEWriteMolecule(ofs, mol);

See also

• Generic Data chapter