CubePy is under CC BY-NC-SA license

ReadCube.py is a collection of functions that extract data from cube files and return it in convenient python formats. These are the main functions used by PlotCube.py, PlotCube_mayavi.py, SaveCube.py and CalculateCube.py.

Requirements

Python

An easy way to obtain Python is by installing Anaconda.

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications $\to$ Anaconda Navigator $\to$ spyder $\to$ Launch)

Instructions

If you want to use the functions in ReadCube.py to extract data from cube files in Python, you will need to write a Python script:

import ReadCube as rc
var1 = rc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>

The Python script can be written and ran in different ways:

as a new .py file using Spyder (Spyder $\to$ File $\to$ New file... $\to$ [write the file] $\to$ Save As... [make sure you save the file in the same directory as ReadCube.py] $\to$ Run $\to$ Run [the file will be run in the iPython console]
in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing ReadCube.py
in the terminal window: type ipython, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing ReadCube.py

Example

import ReadCube as rc
at = rc.Atoms(fpath='test_emim_oac_esp.cube')
print([i[0] for i in at])

This example prints the atomic numbers of all the constituent atoms:

[7, 6, 1, 1, 1, 6, 1, 7, 6, 1, 1, 6, 1, 1, 1, 6, 6, 1, 1, 6, 8, 8, 6, 1, 1, 1]

Functions

ExtractData

This function extracts all the data from the cube file.

Required parameters

fpath (string) = path for a cube file

Optional parameters

au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Returns

a list of: the number of atoms, a list of the coordinates of the origin, the number of values recorded at each point, the number of voxels along x axis, a list of the coordinates of the increment vector for the x axis, the number of voxels along y axis, a list of the coordinates of the increment vector for the y axis, the number of voxels along z axis, a list of the coordinates of the increment vector for the z axis, a list of lists containing the atomic number, the nuclear charge and coordinates for each atom, a list of MO indices, a 3D array of all the values in the cube file, a list of all the values in the cube file, value units (in order)

Atoms

Parameters

fpath (string, default=None) = path for a cube file
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
value_type (string, default='esp') = value type
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData

Returns

a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom

Axes

Parameters

fpath (string, default=None) = path for a cube file
origin (list, default=None) = a list of the x, y and z coordinates of the origin
n_x (integer, default=None) = number of voxels along x axis
x_vector (list, default=None) = increment vector in the x direction
n_y (integer, default=None) = number of voxels along y axis
y_vector (list, default=None) = increment vector in the y direction
n_z (integer, default=None) = number of voxels along z axis
z_vector (list, default=None) = increment vector in the z direction
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData (if fpath is specified)

Returns

a list of three lists representing the x, y and z coordinates, respectively of the grid points

Observations

called with either fpath, au, density, value_type, units or origin, n_x, x_vector, n_y, y_vector, n_z, z_vector
if specified, fpath takes priority over the other arguments and [ExtractData] is called (i.e. the script reads and goes through the whole cube file).

ValuesAsMatrix

Parameters

fpath (string, default=None) = path for a cube file
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData

Returns

a 3D array of all the values in the cube file

ValuesAsList

Parameters

fpath (string, default=None) = path for a cube file
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData

Returns

a list of all the values in the cube file (in the order in which they appear)

ValuesAsDictionary

Parameters

fpath (string, default=None) = path for a cube file
vals (list, default=None) = a list of all the values in the cube file
axes_list (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by Axes)
origin (list, default=None) = a list of the x, y and z coordinates of the origin
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData (if fpath is specified)

Returns

a list of an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value and an ordered dictionary of each grid point (represented through a tuple of its indices) and its corresponding value

Observations

called with either fpath, au, density, value_type, units or vals, axes_list, origin
if specified, fpath takes priority over the other arguments and [ExtractData] is called (i.e. the script reads and goes through the whole cube file).

Minimum

Parameters

fpath (string, default=None) = path for a cube file
gridpts (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by ValuesAsDictionary)
vals (list, default=None) = a list of all the values in the cube file
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData (if fpath is specified)
Axes (if fpath is specified)
ValuesAsDictionary (if fpath is specified)

Returns

a list the coordinates of all the grid points that have the minimum value

Observations

called with either fpath, au, density, value_type, units or gridpts, vals
if specified, fpath takes priority over the other arguments and [ExtractData] is called (i.e. the script reads and goes through the whole cube file).

Maximum

fpath (string, default=None) = path for a cube file
gridpts (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by ValuesAsDictionary)
vals (list, default=None) = a list of all the values in the cube file
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.

Calls

ExtractData (if fpath is specified)
Axes (if fpath is specified)
ValuesAsDictionary (if fpath is specified)

Returns

a list the coordinates of all the grid points that have the maximum value

Observations

called with either fpath, au, density, value_type, units or gridpts, vals
if specified, fpath takes priority over the other arguments and [ExtractData] is called (i.e. the script reads and goes through the whole cube file).

GetVdWPoints

This function returns all the points that are close to the surface defined in terms of the Van der Waals radii of the constituent atoms.

Parameters

fpath (string, default=None) = path for a cube file
axes_list (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by Axes)
gridpts (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by ValuesAsDictionary)
atoms_list (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by Atoms)
x_vector (list, default=None) = increment vector in the x direction
y_vector (list, default=None) = increment vector in the y direction
z_vector (list, default=None) = increment vector in the z direction
origin (list, default=None) = a list of the x, y and z coordinates of the origin
factor (float, default=1) = factor by which to multiply the VdW radii
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
density (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n³)
value_type (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords au and units in order to convert the values to the appropriate units
units (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords value_type and au override units. If au is True, the values will be in atomic units regardless of the value passed for units. If value_type is ‘dens’, the values will be read as density values even if the units argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å³.
cat (boolean, default=False) = if True, it only selects the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside the code)
an (boolean, default=False) = if True, it only selects the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside the code; the atoms belonging to the anion are the remaining ones)
thickness (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

Calls

ExtractData (if fpath is specified)
Axes (if fpath is specified)
ValuesAsDictionary (if fpath is specified)

Returns

a list of three lists: the first one contains the x, y, z coordinates and the value of each point on the VdW surface, the second one contains the indices and the value of each point on the VdW surface and the third one contains the coordinates and values of all the points that are on or inside the VdW surface

Observations

called with either fpath, au, density, value_type, units, factor or axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, origin, factor
if specified, fpath takes priority over the other arguments and [ExtractData] is called (i.e. the script reads and goes through the whole cube file).
the points that reside on the VdW surface are chosen to be within plus/minus a distance of the surface defined by the Van der Waals radii of the constituent atoms (the distance is given by the distance between two diagonally adjacent points in the grid multiplied by thickness)
if you want to only select certain points from the van der Waals surface, you can change this manually inside the code; this also applies for only selecting points which belong to either the cation or the anion (for which there are the parameters cat and an, respectively)