PlotCube_mayavi.py is a collection of functions that plot data from cube files.

Requirements

An easy way to obtain mayavi is by installing Canopy.

Open Canopy $\to$ Tools $\to$ Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

Instructions

Running the code

The plotting functions can be run from the Canopy terminal window by typing:

python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...

Interacting with the plot

Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

Changing the colour scheme

Find the desired layer within the list, click on Colors and legends $\to$ Scalar LUT $\to$ Out mode

Changing the transparency

Click on the desired element in the list $\to$ Actor $\to$ Actor $\to$ Opacity

Showing/Hiding an element

This can be done either by changing the opacity or by right-clicking on the desired element $\to$ Hide/Show

Displaying the value of a point

Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

Functions

PlotSurface

This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

Required arguments

fpath (string) = path for a cube file

Optional arguments

factor (float, default=1) = factor by which to multiply the VdW radii
alpha (float, default=1) = transparency value (between 0 and 1)
size (float, default=1) = marker size
axes (boolean, default=False) = if True, show axes; if False, hide axes
colour (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list here
bkg (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
minmax (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
minmax_range (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
cb_lim (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
atoms (boolean, default=True) = if True, show atoms; if False, hide atoms
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
curvature (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
cv_lim (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
cv_pts (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
save (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)

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/Å³.
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)
log (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
logfile (string, default=None) = the name of the log file (if log is True); by default the file name is the input file name followed by the function name
min_colour (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
max_colour (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
cb_sym (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (cb_lim, if specified, overrides cb_sym)

Calls

ExtractData (from ReadCube.py)
Axes (from ReadCube.py)
ValuesAsDictionary (from ReadCube.py)
GetVdWPoints (from ReadCube.py)
VdWLaplacian (from CalculateCube.py)

Example

python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube

The resulting plot is shown in figure 1.

PlotIsoVdW

This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within iso±iso_range in their corresponding colours and the others in grey.

Required arguments

fpath (string) = path for a cube file

Optional arguments

factor (float, default=1) = factor by which to multiply the VdW radii
alpha (float, default=1) = transparency value (between 0 and 1)
size (float, default=4) = marker size
axes (boolean, default=False) = if True, show axes; if False, hide axes
colour (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list here
cb_lim (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
atoms (boolean, default=True) = if True, show atoms; if False, hide atoms
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³)
iso (float, default=None) = the value of the points to be plotted in colour
iso_range (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)

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/Å³.
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)
log (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
logfile (string, default=None) = the name of the log file (if log is True); by default the file name is the input file name followed by the function name
cb_sym (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (cb_lim, if specified, overrides cb_sym)

Calls

ExtractData (from ReadCube.py)
Axes (from ReadCube.py)
ValuesAsDictionary (from ReadCube.py)
GetVdWPoints (from ReadCube.py)

Sliders

Iso slider

Example

python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5

The resulting plot is shown in figure 2.

PlotIsosurface

This function creates an interactive plot of all the points which are within a specified value range from a given value.

Required arguments

fpath (string) = path for a cube file

Optional arguments

factor (float, default=1) = factor by which to multiply the VdW radii
alpha (float, default=1) = transparency value (between 0 and 1)
size (float, default=4) = marker size
axes (boolean, default=False) = if True, show axes; if False, hide axes
colour (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list here
minmax (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
minmax_range (float, default=0) = the value range to consider for the minima and maxima
cb_lim (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
atoms (boolean, default=True) = if True, show atoms; if False, hide atoms
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³)
iso (float, default=None) = the value of the points to be plotted in colour
iso_range (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)

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/Å³.
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)
log (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
logfile (string, default=None) = the name of the log file (if log is True); by default the file name is the input file name followed by the function name
min_colour (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
max_colour (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
cb_sym (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (cb_lim, if specified, overrides cb_sym)

Calls

ExtractData (from ReadCube.py)
Axes (from ReadCube.py)
ValuesAsDictionary (from ReadCube.py)
GetVdWPoints (from ReadCube.py)

Sliders

Iso slider

Example

python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2

The resulting plot is shown in figure 3.

PlotSlice

This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

Required arguments

fpath (string) = path for a cube file

Optional arguments

factor (float, default=1) = factor by which to multiply the VdW radii
alpha (float, default=1) = transparency value (between 0 and 1)
size (float, default=4) = marker size
axes (boolean, default=True) = if True, show axes; if False, hide axes
colour (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list here
minmax (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
minmax_range (float, default=0) = the value range to consider for the minima and maxima
cb_lim (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
atoms (boolean, default=False) = if True, show atoms; if False, hide atoms
au (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and units for values
a (float, default=0) = the x component of the normal vector defining the plane
b (float, default=0) = the y component of the normal vector defining the plane
c (float, default=1) = the z component of the normal vector defining the plane
x0 (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
y0 (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
z0 (float, default=None) = the z coordinate of the origin for the normal vector defining the plane

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³)
contour (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
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/Å³.
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)
log (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
logfile (string, default=None) = the name of the log file (if log is True); by default the file name is the input file name followed by the function name
min_colour (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
max_colour (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
cb_sym (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (cb_lim, if specified, overrides cb_sym)

Calls

ExtractData (from ReadCube.py)
Axes (from ReadCube.py)
ValuesAsDictionary (from ReadCube.py)
GetVdWPoints (from ReadCube.py)

Sliders

a
b
c
x₀
y₀
z₀

Example

python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3

The resulting plot is shown in figure 4.