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, 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

#!/usr/bin/env python
from openeye.oegrid import *

grid = OEScalarGrid(64, 64, 64, 0.0, 0.0, 0.0, 0.5)

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 of memory for this nominally sized grid.

Data Access

Grids provide three ways to index data inside the grid. They are ordered here by speed of access, ie, 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 atom in mol.GetAtoms():
    x, y, z = mol.GetCoords(atom)
    if grid.IsInGrid(x, y, z):
        print "value =", grid.GetValue(x, y, z)

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 atom in mol.GetAtoms():
    x, y, z = mol.GetCoords(atom)
    if grid.IsInGrid(x, y, z):
        grid.SetValue(x, y, z, 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 behaviour (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

x, y, z = mol.GetCoords(atom)

ix, iy, iz = grid.SpatialCoordToGridIdx(x, y, z)

# Make sure not to go past grid bounds
mini = max(ix - 1, 0)
minj = max(iy - 1, 0)
mink = max(iz - 1, 0)
maxi = min(ix + 1, grid.GetXDim())
maxj = min(iy + 1, grid.GetYDim())
maxk = min(iz + 1, grid.GetZDim())

for k in xrange(mink, maxk):
    for j in xrange(minj, maxj):
        for i in xrange(mini, maxi):
            print "value =", grid.GetValue(i, j, k)

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 i in xrange(grid.GetSize()):
    val = grid.GetValue(i)
    grid.SetValue(i, val * val)

Input and Output

The following grid file formats are supported:

.phi:GRASP format .grd:OpenEye Binary format .agd:OpenEye ASCII format .map OR .ccp OR .ccp4:  CCP4 format .xplor OR .xplmap:  XPLOR format

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

#!/usr/bin/env python
from openeye.oegrid import *

grid = OEScalarGrid(2, 2, 2, 0.0, 0.0, 0.0, 0.5)

print "Title:", grid.GetTitle()

print "Mid: %12.6f %12.6f %12.6f" % grid.GetMid()
  
print "Dim: %6d %6d %6d" % grid.GetDim()
  
print "Spacing: %12.6f" % grid.GetSpacing()
  
print "Values:"
for iz in xrange(grid.GetZDim()):
    for iy in xrange(grid.GetYDim()):
        for ix in xrange(grid.GetXDim()):
            print "%-12.6e" % grid.GetValue(ix,iy,iz)

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 a 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 heirarchies.

Listing 7: Attaching a grid to a molecule

grid = OEScalarGrid()
OEMakeMolecularGaussianGrid(grid, mol, 0.5)

mol.SetData("Gaussian Grid", grid)

OEWriteMolecule(ofs, mol)