\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.base.plotbase module

Basic utility functions for plotting 2D and 3D figures.

Note

3D plotting functions are based on MayaVi, which is not included in the default dependences of CRYSTALpytools.

plot_overlap_bands(ax, bands, k_xax, k_path, k_label, energy_range, k_range, band_label, band_color, band_linestyle, band_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, **kwargs)

The plotting function for overlapped band structures of electron or phonon. Also can be used to get a single band.

Note

You must specify colors in string. List of RGB values are not allowed and might lead to unexpected errors.

Parameters:

  • ax (Axes) – Matplotlib Axes object. To be passed from wrapper functions.

  • bands (list) – Band structure, 1*nSystem list of nBand*nKpoint*nSpin numpy arrays.

  • k_xax (list) – Coordinates of x axis. 1*nSystem list.

  • k_path (list) – Coordinates of high-symmetric k points, 1*nSystem list of 1*nTick numpy arrays. Unit: \(\AA^{-1}\).

  • k_label (list[str] | None) – 1*nTick list of strings of the label for high symmetry points along the path. mathtext experssions can also be used as in matplotlib.

  • energy_range (list) – 1*2 list of plotting energy range.

  • k_range (list) – 1*2 list of plotting k range. Can either be length (float) or k label (str). Must be used with not_scaled=False and the same set of k_label.

  • band_label (list) – 1*nSystem or nSystem*2 (spin) plot legend. If spin>1 and 1*nSystem list is used, they are marked with the same label.

  • band_color (list) – 1*nSystem or nSystem*2 (spin) plot color. If spin >1 and 1*nSystem list is used, they are in the same color.

  • band_linestyle (list) – 1*nSystem or nSystem*2 (spin) linestyle string. If spin>1 and 1*nSystem list is used, they are in the same style.

  • band_linewidth (list) – 1*nSystem or nSystem*2 (spin) width of the plot lines. If spin>1 and 1*nSystem list is used, they are in the same width.

  • fermi (float | None) – Fermi energy. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str) – Color of the Fermi level.

  • fermi_linestyle (str) – Line style of Fermi level.

  • fermi_linewidth (float) – Width of the Fermi level.

  • legend (str|None) – Loc parameter passed to axes.legend() None for not adding legend.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib Axes object.

plot_compare_bands(ax, bands, k_xax, k_path, k_label, not_scaled, energy_range, k_range, band_label, band_color, band_linestyle, band_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, **kwargs)

The plotting function for band structures of electron or phonon in different panels.

Note

You must specify colors in string. List of RGB values are not allowed and might lead to unexpected errors.

Parameters:

  • ax (Axes) – Matplotlib Axes object or a flatted list of them. To be passed from wrapper functions.

  • bands (list) – Band structure, 1*nSystem list of nBand*nKpoint*nSpin numpy arrays.

  • k_xax (list) – Coordinates of x axis. 1*nSystem list.

  • k_path (list) – Coordinates of high-symmetric k points, 1*nSystem list of 1*nTick numpy arrays. Unit: \(\AA^{-1}\).

  • k_label (list) –

    nSystem*nTick or 1*nTick list of strings of the label for high symmetry points along the path. If a 1D list is given, the same labels are used for all the systems. mathtext experssions can also be used as in matplotlib.

  • not_scaled (bool) – Whether to scale the x-axis for different volumes.

  • energy_range (list) – 1*2 list of plotting energy range.

  • k_range (list) – 1*2 list of plotting k range. Can either be length (float) or k label (str). Must be used with not_scaled=False and the same set of k_label.

  • band_label (list) – 1*nSystem or nSystem*2 (spin) plot legend. If spin>1 and 1*nSystem list is used, they are marked with the same label.

  • band_color (list|str) – A color string or 1*2 color list for spin. If nSpin>1 but a string is given, same color for both spins.

  • band_linestyle (list|str) – A linestyle string or 1*2 linestyle list for spin. If nSpin>1 but a string is given, same linestyle for both spins.

  • band_linewidth (list|float) – A linewidth number or 1*2 linewidth list for spin. If nSpin>1 but a string is given, same linewidth for both spins.

  • fermi (float | None) – Fermi energy. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str) – Color of the Fermi level.

  • fermi_linestyle (str) – Line style of Fermi level.

  • fermi_linewidth (float) – Width of the Fermi level.

  • legend (str|None) –

    Loc parameter passed to axes.legend() None for not adding legend.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib Axes object or a flatted list of them.

_plot_bands_preprocess(bands, k_path, k_label, not_scaled, energy_range, k_range, band_label, band_color, band_linestyle, band_linewidth)

Do the boring parameters checking jobs for band structures. For the meanings of parameters, refer to plot_overlap_bands() (plot_compare_bands has less strict requirements).

not_scaled is a flag to set whether to set the same length of k pathes of different systems.

_plot_label_preprocess(bands, band_label, band_color, band_linestyle, band_linewidth)

Do the boring parameters checking jobs for plots (both band and dos). For the meanings of parameters, refer to plot_compare_bands. The same rule is applied to DOS.

  1. For None input, generate nsystem*2 list default values

  2. For string/float inputs, generate nsystem*2 list same values

  3. For nsystem*1 inputs, generate nsystem*2 list, spin-up and down states share the same style.

  4. For nsystem*2 inputs, do nothing.

return to a bigger command variable of [label, color, linestyle, linewidth].

plot_doss(ax, doss, energy, beta, prj, energy_range, dos_range, dos_label, dos_color, dos_linestyle, dos_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, plot_vertical, **kwargs)

The base function to plot electron / phonon density of states on one axes.

Parameters:

  • ax (Axes) – Matplotlib Axes object.

  • doss (numpy.ndarray) – nProj*nEnergy*nSpin array of DOS. Positive values for both spin up and spin down states.

  • energy (numpy.ndarray) – 1*nEnergy array of energy.

  • beta (str) – Plot settings for \(eta\) states (‘up’ or ‘down’).

  • prj (list) – Index of selected projections, consistent with the first dimension of the doss, starting from 1.

  • energy_range (list) – 1*2 list of energy range.

  • dos_range (list) – 1*2 list of DOS range.

  • dos_label (list) – 1*nProj or nProj*2 (spin) plot legend. If spin>1 and 1*nProj list is used, they are marked with the same label.

  • dos_color (list) – 1*nProj or nProj*2 (spin) plot color. If spin>1 and 1*nProj list is used, they are in the same color.

  • dos_linestyle (list) – 1*nProj or nProj*2 (spin) linestyle string. If spin>1 and 1*nProj list is used, they are in the same style.

  • dos_linewidth (list) – 1*nProj or nProj*2 (spin) width of the plot lines. If spin>1 and 1*nSystem list is used, they are in the same width.

  • fermi (float|None) – Fermi energy in eV. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str|None) – Color of the Fermi level.

  • fermi_linestyle (str|None) – Line style of Fermi level.

  • fermi_linewidth (float|None) – Width of the Fermi level.

  • legend (str|None) –

    Loc parameter passed to axes.legend() None for not adding legend.

  • plot_vertical (bool) – Developer Only Get vertical (DOS-Energy) DOS plots.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib axes object

plot_banddos(bands, doss, k_label, beta, overlap, prj, energy_range, k_range, dos_range, band_width, band_label, band_color, band_linestyle, band_linewidth, dos_label, dos_color, dos_linestyle, dos_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, figsize, legend, **kwargs)

The base function to plot electron / phonon band structure + DOS. A single system only.

Input arguments not in the list are consistent with plot_doss and plot_compare_bands.

Parameters:

  • bands (ElectronBand) – A electronics.ElectronBand object.

  • doss (ElectronDOS) – A electronics.ElectronDOS object

  • band_width (int|float) – Relative width of band structure, times of the width of a DOS subplot.

  • overlap (bool) – Plot DOS projections into the same axes or multiple axes.

Returns:

fig (Figure) – Matplotlib figure object

GridCoordinates(base, shape, meshgrid)

Get cartesian coordinates by equally spaced grid data.

Parameters:

  • base (array) – 4(3)*3 Cartesian coordinates of points O, A, B(, C) to define a 3(2)D map. Vectors OA, OB(, OC) are used.

  • shape (array) – 1*nDimen array, nX, nY(, nZ) of data array

  • meshgrid (bool) – Get nD mesh grids or 1D array of coordinates.

Returns:

coords (list) – 1*3 list of x, y(, z) coordinates, either in nA*nB(*nC) mesh grids or in 1D arrays, depending on meshgrid.

GridExpand(base, data, display_range)

Expand 2D/3D data grid.

Parameters:

  • base (array) – 4(3)*3 Cartesian coordinates of points O, A, B(, C) to define a 3(2)D map. Vectors OA, OB(, OC) are used.

  • data (array) – nX*nY(*nZ) array of data.

  • display_range (array) – 3(2)*2 array of fractional display range, in [amin, amax].

Returns:

  • newbase (array) – Expanded base vectors.

  • newdata (array) – Expanded data grid.

GridInterpolate(base, data, method, size)

Interpolate 2D/ 3D grid data by scipy.interpolate.interpn.

Parameters:

  • base (array) – 3(4)*3 Cartesian coordinates of the 3(4) points defining base vectors BA, BC (2D) or OA, OB, OC (3D). The sequence is (O), A, B, C.

  • data (array) – nX*nY(*nZ) data grid.

  • method (str) – ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’.

  • size (int) – The new size of interpolated data (list) or a scaling factor.

Returns:

  • DATA (array) – nX*nY(*nZ) data grid.

  • CRDS (array) – (nX*nY*nZ)*3 or (nX*nY)*3 cartesian coordinates. Sequence is consistent with the flattened DATA.

GridRectangle2D(base, data)

Get 2D grid data on a rectangle regular grid by manipulating the data matrix and orient it to xOy plane.

Parameters:

  • base (array) – 3*3 Cartesian coordinates of points O, A, B to define a 2D map. Vectors OA, OB are used.

  • data (array) – Grid data in nX*nY.

Returns:

  • basenew (array)

  • data (array)

  • X (array) – nX*nY mesh grid of x coordinates

  • Y (array) – nX*nY mesh grid of y coordinates

GridRotation2D(base)

Get the rotation object and translational movement to align surface norm (to z) and OA axis (to x) of 3D reference frame to the plotting frame. The translational movement is used to move O (plot origin) to z=0. The plotting referance frame is defined by the base vector OA (x) and OB (y).

Returns:

  • rot (Rotation) – The Scipy rotation object.

  • disp (array) – Displacement along x, y, z axes

tvtkGrid(base, data, CenterOrigin, InterpGridSize, **kwargs)

Define a 3D/2D tvtk Grid for MayaVi. Only for representing 3D/2D scalar field defined in the periodic, uniform mesh.

  • For orthogonal data grid aligned to x, y and z axes, return to the

    ImageData class.

  • For non-orthogonal data grid or not aligned data grid, return to the

    StructuredGrid classes, or interpolated ImageData class by the scipy.interpolate.griddata() method and linear interpolation. Might be very time consuming.

Note

For generality, the input data grid is a non-periodic one.

Parameters:

  • base (array) – Base vectors, 3(4)*3 array of origin and point A, B(, C)

  • data (array) – Scalar field data in column-major order, i.e., nA*nB*nC.

  • CenterOrigin (bool) – Put origin of base vectors in the center. Usually for reciprocal space visualization.

  • InterpGridSize (array|int|None) – Interpolate non-orthogonal data into orthogonal grid. ‘None’ for no interpolation. Integer input for interpolation sizes. For volume data representation.

  • **kwargs – Passed to scipy.interpolate.griddata.

Returns:

grid (ImageData|StructuredGrid) – vtk grid classes.

plot_2Dscalar(fig, ax, data, base, levels, contourline, isovalue, colormap, cbar_label, a_range, b_range, rectangle, edgeplot, xticks, yticks, **kwargs)

Plot 2D scalar field map.

Parameters:

  • fig (Figure) – Matplotlib Figure object

  • ax (Axes) – Matplotlib Axes object

  • data (array) – 2D map data, in nY*nX,

  • base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.

  • levels (array|None) – Contour line / color isovalues. It also defines the range of data.

  • contourline (list|None) – If not None, set line styles and colors of every contourline. nLevel*3 list of matplotlib plot color, linestyle and linewidth.

  • isovalue (str|None) – If not None, set the format of isovalues added to contourlines. Useful only when contourline is not None.

  • colormap (str|None) – If not None, set the colormap of color-filled contour plots.

  • cbar_label (str) – Title of colorbar. Useful only when colormap is not None.

  • a_range (list) – Range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – Range of \(b\) axis (x, or AB) in fractional coordinate.

  • rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\).

  • edgeplot (bool) – Whether to plot plane edges

  • xticks (int) – Number of ticks in the x direction.

  • yticks (int) – Number of ticks in the y direction.

  • **kwargs – Other arguments passed to axes.contour() function to set contour lines.

Returns:

fig (Figure) – Matplotlib Figure object

plot_2Dvector(fig, ax, data, base, scale, colorquiver, levels, colormap, cbar_label, a_range, b_range, rectangle, edgeplot, xticks, yticks, **kwargs)

Plot 2D vector field map.

Parameters:

  • fig (Figure) – Matplotlib Figure object

  • ax (Axes) – Matplotlib Axes object

  • data (array) – 2D vector map data, in nY*nX*3.

  • base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.

  • scale (float) – Tune the length of arrows.

  • colorquiver (str) – Specify the color of arrows or ‘colored’ for color- coded quiver plots.

  • levels (array) – Contour color isovalues. It also defines the range of data. Useful only if colorquiver='colored'.

  • colormap (str|None) – Set the colormap of color-filled contour plots. Useful only if colorquiver='colored'.

  • cbar_label (str) – Title of colorbar. Useful only if colorquiver='colored'.

  • a_range (list) – Range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – Range of \(b\) axis (x, or AB) in fractional coordinate.

  • rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\).

  • edgeplot (bool) – Whether to plot plane edges

  • xticks (int) – Number of ticks in the x direction.

  • yticks (int) – Number of ticks in the y direction.

  • **kwargs – Other arguments passed to axes.quiver() function to set contour lines.

Returns:

fig (Figure) – Matplotlib Figure object

plot_3Dscalar(fig, base, data, isovalue, volume_3d, interp, interp_size, display_range, **kwargs)

Plot 3D scalar field.

Parameters:

  • fig – MayaVi scence object

  • base (array) – 4*3 array of base vectors defining O, A, B, C.

  • data (array) – nZ*nY*nX array of plot data.

  • isovalue (float|array) – Isovalues of 3D/2D contour plots. A number or an array for user-defined values of isosurfaces, must be consistent with ``unit``.

  • volume_3d (bool) – Display 3D volumetric data instead of isosurfaces.

  • interp (str) – Interpolation method. ‘no interp’, ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’.

  • interp_size (list[int]|int) – The new size of interpolated data (list) or a scaling factor.

  • display_range (array) – 3*2 array defining the displayed region. Fractional coordinates a, b, c are used.

  • **kwargs – Optional keywords passed to MayaVi, listed below.

  • colormap (turple|str) – Colormap of isosurfaces/heatmaps. Or a 1*3 RGB turple from 0 to 1 to define colors. Not for volume_3d=True.

  • opacity (float) – Opacity from 0 to 1. For volume_3d=True, that defines the opacity of the maximum value. The opacity of the minimum is half of it.

  • transparent (bool) – Scalar-dependent opacity. Not for volume_3d=True.

  • vmax (float) – Maximum value of colormap.

  • vmin (float) – Minimum value of colormap.

  • title (str) – Colorbar title.

  • orientation (str) – Orientation of colorbar, ‘horizontal’ or ‘vertical’.

  • nb_labels (int) – The number of labels to display on the colorbar.

  • label_fmt (str) – The string formater for the labels, e.g., ‘%.1f’.

Returns:

fig – MayaVi scence object

plot_3Dplane(fig, base, data, levels, contour_2d, interp, interp_size, display_range, **kwargs)

Plot oriented 2D scalar fields in 3D structure.

Parameters:

  • fig – MayaVi scence object

  • base (array) – 3*3 array of base vectors defining A, B, C.

  • data (array) – nY*nX array of plot data.

  • levels (float|array) – Number of Isovalues of 2D contour plots, equally spaced between vmin and vmax, or an array for user-define values of contour lines, ‘contour_2d=True’ only.

  • contour_2d (bool) – Display black contour lines over the colored surface.

  • interp (str) – Interpolation method. ‘no interp’, ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’.

  • interp_size (list[int]|int) – The new size of interpolated data (list) or a scaling factor.

  • display_range (array) – 2*2 array defining the displayed region. Fractional coordinates a, b are used.

  • **kwargs – Optional keywords passed to MayaVi, listed below.

  • colormap (turple|str) – Colormap of heatmaps. Or a 1*3 RGB turple from 0 to 1 to define colors.

  • color (turple) – Color of contour lines. ‘contour_2d=True’ only.

  • line_width (float) – Line width of contour plots. ‘contour_2d=True’ only.

  • opacity (float) – Opacity from 0 to 1. For volume_3d=True, that defines the opacity of the maximum value. The opacity of the minimum is half of it.

  • transparent (bool) – Scalar-dependent opacity. Not for volume_3d=True.

  • vmax (float) – Maximum value of colormap.

  • vmin (float) – Minimum value of colormap.

  • title (str) – Colorbar title.

  • orientation (str) – Orientation of colorbar, ‘horizontal’ or ‘vertical’.

  • nb_labels (int) – The number of labels to display on the colorbar.

  • label_fmt (str) – The string formater for the labels, e.g., ‘%.1f’.

Returns:

fig – MayaVi scence object