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

CRYSTALpytools.base.plotbase module

Base functions for plotting 2D and 3D figures

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.

For None input, generate nsystem*2 list default values
For string/float inputs, generate nsystem*2 list same values
For nsystem*1 inputs, generate nsystem*2 list, spin-up and down states share the same style.
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

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.
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

_manipulate_2D_grid(data, base, a_range, b_range, rectangle)

Repeat 2D grid data and get rectangle region

Parameters:

data (array) – 2D map data.
base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.
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\).

Returns:

X (array) – nY*nX mesh grid.
Y (array) – nY*nX mesh grid.
data (array) – nY*nX mesh grid data.
a_range (array) – 1*2 fractional coordinate of plot range along vector BC.
b_range (array) – 1*2 fractional coordinate of plot range along vector BA.

_get_2D_base_frame(base, a_range, b_range)

Get the 2D parallelogram plot boundary. Useful when the plot is extended. The frame is always shifted to the origin, or positive side of the plot and close to the origin.

Parameters:

base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.
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.

Returns:

xpath (array) – 1*3 array of x coordinates of parallelogram plot boundary.
ypath (array) – 1*3 array of y coordinates of parallelogram plot boundary.

_get_operation(base)

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

Returns:

rot (Rotation) – The Scipy rotation object.
disp (array) – Displacement along x, y, z axes