# pymatgen.io.cube module

Module for reading Gaussian cube files, which have become one of the standard file formats for volumetric data in quantum chemistry and solid state physics software packages (VASP being an exception).

Some basic info about cube files (abridged info from http://paulbourke.net/dataformats/cube/ by Paul Bourke)

The file consists of a header which includes the atom information and the size as well as orientation of the volumetric data. The first two lines of the header are comments. The third line has the number of atoms included in the file followed by the position of the origin of the volumetric data. The next three lines give the number of voxels along each axis (x, y, z) followed by the axis vector. The last section in the header is one line for each atom consisting of 5 numbers, the first is the atom number, the second is the charge, and the last three are the x,y,z coordinates of the atom center. The volumetric data is straightforward, one floating point number for each volumetric element.

Example In the following example the volumetric data is a 40 by 40 by 40 grid, each voxel is 0.283459 units wide and the volume is aligned with the coordinate axis. There are three atoms.

> CPMD CUBE FILE. OUTER LOOP: X, MIDDLE LOOP: Y, INNER LOOP: Z

> > > 3 0.000000 0.000000 0.000000

> > 40 0.283459 0.000000 0.000000 40 0.000000 0.283459 0.000000 40 0.000000 0.000000 0.283459

> > > 8 0.000000 5.570575 5.669178 5.593517 1 0.000000 5.562867 5.669178 7.428055 1 0.000000 7.340606 5.669178 5.111259

> -0.25568E-04 0.59213E-05 0.81068E-05 0.10868E-04 0.11313E-04 0.35999E-05

>   : : : : : : : : : : : : : : : : : :

>   > In this case there will be 40 x 40 x 40 floating point values

>   : : : : : : : : : : : : : : : : : :

class Cube(fname)

  Bases: `object`

  Class to read Gaussian cube file formats for volumetric data.

  Cube files are, by default, written in atomic units, and this class assumes that convention.

  Initialize the cube object and store the data as self.data

  Parameters

    fname (str) – filename of the cube to read

  get_atomic_site_averages(atomic_site_radii)

    Get the average value around each atomic site.

    Parameters

      atomic_site_radii (dict) – dictionary determining the cutoff radius (in Angstroms) for averaging around atomic sites (e.g. {‘Li’: 0.97, ‘B’: 0.77, …}. If not provided, then the

    Returns

      Array of site averages, [Average around site 1, Average around site 2, …]

  get_atomic_site_totals(atomic_site_radii)

    Get the integrated total in a sphere around each atomic site.

    Parameters

      atomic_site_radii (dict) – dictionary determining the cutoff radius (in Angstroms) for averaging around atomic sites (e.g. {‘Li’: 0.97, ‘B’: 0.77, …}. If not provided, then the

    Returns

      Array of site averages, [Average around site 1, Average around site 2, …]

  get_average_along_axis(ind)

    Modified from pymatgen.io.vasp.outputs

    Get the averaged total of the volumetric data a certain axis direction. For example, useful for visualizing Hartree Potentials.

    Parameters

      ind (int) – Index of axis.

    Returns

      Average total along axis

  get_axis_grid(ind)

    Modified from pymatgen.io.vasp.outputs

    Returns the grid for a particular axis.

    Parameters

      ind (int) – Axis index.

  mask_sphere(radius, cx, cy, cz)

    Create a mask for a sphere with radius=radius, centered at cx, cy, cz.

    Parameters

      - radius – (flaot) of the mask (in Angstroms)

      - cx – (float) the fractional coordinates of the center of the sphere

      - cy – (float) the fractional coordinates of the center of the sphere

      - cz – (float) the fractional coordinates of the center of the sphere