Gaussian Cube Files

Written by Paul Bourke
December 2003

Swedish translation by Weronika Pawlak
Portuguese translation by Diana Gomes
Macedonian translation by Jimmy Anastasovski
Danish translation by Nastasya Zemina
Ukrainian translation by Anna Matesh
Hungarian translation by Elana Pavlet
Indonesian translation by Jordan Silaen.


Introduction

The cube file describes volumetric data as well as atom positions, it originates from the Gaussian software package. The file consists of a header which includes the atom information and the size as well as orientation of the volumetric data. This is followed by the volumetric data, one scalar per voxel element. All aspects of the file are text (human readable), originally the numerical values were 5 wide for integers that started each header line (after the first) and floating point values were formatted 12.6, that is, 12 characters wide with 6 decimal places.

Header

The first two lines of the header are comments, they are generally ignored by parsing packages or used as two default labels.

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. Note this means the volume need not be aligned with the coordinate axis, indeed it also means it may be sheared although most volumetric packages won't support that. The length of each vector is the length of the side of the voxel thus allowing non cubic volumes. If the sign of the number of voxels in a dimension is positive then the units are Bohr, if negative then Angstroms.

The last section in the header is one line for each atom consisting of 5 numbers, the first is the atom number, second (?), the last three are the x,y,z coordinates of the atom center.

Volumetric data

The volumetric data is straightforward, one floating point number for each volumetric element. The original Gaussian format arranged the values in the format shown below in the example, most parsing programs can read any white space separated format. Traditionally the grid is arranged with the x axis as the outer loop and the z axis as the inner loop, for example, written as

   for (ix=0;ix<NX;ix++) {
      for (iy=0;iy<NY;iy++) {
         for (iz=0;iz<NZ;iz++) {
            printf("%g ",data[ix][iy][iz]);
            if (iz % 6 == 5)
               printf("\n");
         }
         printf("\n");
      }
   }
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
      :             :             :           :            :            :
      :             :             :           :            :            :
      :             :             :           :            :            :