Ctrl+K

easyunfold.plotting

easyunfold.plotting#

Plotting utilities

Module Contents#

Classes#

UnfoldPlotter

A collection plotting tools for unfolded band structures

Functions#

interpolate_colors

Interpolate colours at a number of points within a colorspace.

adjust_lightness

Lightens the given color by multiplying (1-luminosity) by the given amount. Input can be matplotlib color string, hex string, or RGB tuple.

API#

class easyunfold.plotting.UnfoldPlotter(unfold: easyunfold.unfold.UnfoldKSet)#

A collection plotting tools for unfolded band structures

Initialization

Instantiate the plotter object

Parameters:

unfold – UnfoldKSet object to be plotted.

static plot_dos(ax, dos_plotter, dos_label, dos_options, ylim, eref, atoms=None, colours=None, orbitals_subplots=None)#

Prepare and plot the density of states.

plot_spectral_function(engs: numpy.ndarray, sf: numpy.ndarray, dos_plotter=None, dos_label=None, dos_options=None, zero_line=False, eref=None, figsize=(4, 3), ylim=(-5, 5), dpi=300, vscale=1.0, contour_plot=False, alpha=1.0, save=False, ax=None, vmin=None, vmax=None, cmap='PuRd', show=False, title=None, intensity=1.0)#

Plot the spectral function.

Parameters:

  • engs – The energies of the spectral functions.

  • sf – An array of the spectral function.

  • eref – Reference energy to be used - this energy will be set as zero.

  • figsize – Size of the figure.

  • ylim – Plotting limit for the y-axis, with respect to eref.

  • dpi – DPI of the generated graph.

  • vscale – A normalisation/scaling factor for the colour map. Smaller values will increase the colour intensity.

  • contour_plot – Whether to use contour plot instead of normal meshed color map.

  • alpha – Color map transparency factor.

  • save – The file to save the generated figure to.

  • ax – An existing plotting axis to be used.

  • vmin – Min value for the colour map.

  • vmax – Max value for the colour map.

  • cmap – Name of the color map to be used.

Returns:

The figure generated containing the spectral function.

_plot_spectral_function_rgba(engs: numpy.ndarray, sf: numpy.ndarray, eref: Union[None, float] = None, figsize=(4, 3), ylim=(-3, 3), dpi: float = 150, vscale: float = 1.0, save: bool = False, ax: Union[None, matplotlib.pyplot.Axes] = None, show: bool = False, title: Union[None, str] = None, vmin: Union[None, float] = None, vmax: Union[None, float] = None, intensity: float = 1.0)#

Plot spectral function defined as RGBA colours

Parameters:

  • engs (np.ndarray) – The energies of the spectral functions.

  • sf – An array of the spectral function.

  • eref (float) – Reference energy to be used - this energy will be set as zero.

  • figsize – Size of the figure.

  • ylim – Plotting limit for the y-axis, with respect to eref.

  • dpi – DPI of the generated graph.

  • save – The file where the generated figure is saved.

  • ax – An existing plotting axis to be used.

  • vmin – Lower bound for constructing the alpha channel.

  • vmax – Upper bound for constructing the alpha channel.

  • vscale – Scaling factor for the alpha channel.

  • title – Title for the plot.

Returns:

the figure generated containing the spectral function.

_add_kpoint_labels(ax: matplotlib.pyplot.Axes, x_is_kidx=False)#

Add labels to the k-points for a given axes

plot_effective_mass(eff: easyunfold.effective_mass.EffectiveMass, engs: numpy.ndarray, sf: numpy.ndarray, eref: Union[None, float] = None, save: Union[None, str] = None, show: bool = False, effective_mass_data: dict = None, **kwargs)#

Plot the effective masses on top of the spectral function.

Parameters:

  • eff – An EffectiveMass object used for plotting.

  • engs – The energies of the spectral functions.

  • sf – An array of the spectral function.

  • eref – Reference energy to be used - this energy will be set as zero.

  • effective_mass_data – Calculated data of the effective masses.

Returns:

A figure with the data used for fitting effective mass plotted on top of the spectral function.

plot_spectral_weights(figsize=(4, 3), ylim=(-3, 3), dpi: float = 150, factor: float = 3.0, eref: Union[None, float] = None, color: str = 'C1', alpha: float = 0.5, save: Union[None, str] = None, ax: Union[None, matplotlib.pyplot.Axes] = None, show: bool = False, title: Union[None, str] = None)#

Plot the spectral weights.

Note

The reduction of symmetry means there can be multiple supercell kpoints for each primitive cell kpoint. When using this scattering plot representation, the markers can overlap each other leading to misrepresentations of the actual effective band structure.

However, this function is still useful when: 1. the symmetry splitting is turned off. 2. direct visualization of the underlying spectral weight is needed. 3. Check the correctness of effective mass extraction.

Parameters:

  • eref – Reference energy to be used - this energy will be set as zero.

  • figsize – Size of the figure.

  • ylim – Plotting limit for the y-axis, with respect to eref.

  • dpi – DPI of the generated graph.

  • alpha – Alpha for the markers.

  • save – Name of the file where the generated figure is saved.

  • ax – Existing plotting axes to be used (list if having two spin channels).

  • factor – Scaling factor for the marker size.

  • color – Color of the markers.

  • title – Title for the generated plot.

Returns:

A Figure with the spectral weights plotted as a scatter plot.

plot_projected(procar: Union[str, list] = 'PROCAR', dos_plotter=None, dos_label=None, dos_options=None, zero_line=False, eref=None, gamma=False, npoints=2000, sigma=0.2, ncl=False, symm_average=True, figsize=(4, 3), ylim=(-5, 5), dpi=300, vscale=1.0, contour_plot=False, alpha=1.0, save=False, ax=None, cmap='PuRd', show=False, title=None, atoms=None, poscar='POSCAR', atoms_idx=None, orbitals=None, use_subplot=False, colours=None, colorspace='lab', intensity=1.0)#

Plot projected spectral function onto multiple subplots or a single plot with color mapping.

This simply computes the spectral function at each orbital/atoms sites and plot them onto multiple subplots. The columns are for each orbital and the rows are for each spin channel.

Parameters:

  • procar – Name(s) of the PROCAR(.gz) file(s).

  • colours – Default is pastel red, green, blue if <=3 projections, else red, green, blue, purple, orange, yellow.

Returns:

Generated plot.

static plot_effective_mass_fit(efm: easyunfold.effective_mass.EffectiveMass, npoints: int = 3, carrier: str = 'electrons', idx: int = 0, ax: Union[matplotlib.pyplot.Axes, None] = None, save: Union[None, str] = None, dpi: float = 120)#

Plot detected band edges and the fitted effective masses.

Parameters:

  • efm – EffectiveMass object for plotting.

  • npoints – The number of points to be used for fitting.

  • carrier – Type of the charge carrier, e.g. electrons or holes.

  • idx – Index for the detected effective mass of the same kind.

  • ax – plt.Axes used for plotting.

  • save – Name of the file used for saveing.

  • dpi – DPI of the figure when saving.

Returns:

A figure with plotted data.

easyunfold.plotting.interpolate_colors(colours: Sequence, weights: list, colorspace='lab', normalize=True)#

Interpolate colours at a number of points within a colorspace.

Parameters:

  • colours – A list of colours specified in any way supported by matplotlib.

  • weights – A list of weights with the shape (n, N). Where the N values of the last axis give the amount of N colours supplied in colours.

  • colorspace – The colorspace in which to perform the interpolation. The allowed values are rgb, hsv, lab, luvlch, lablch, and xyz.

Returns:

A list of colours, specified in the rgb format as a (n, 3) array.

easyunfold.plotting.adjust_lightness(color, amount=0.5)#

Lightens the given color by multiplying (1-luminosity) by the given amount. Input can be matplotlib color string, hex string, or RGB tuple.

Examples:

adjust_lightness(‘g’, 1.1) # slightly lighter adjust_lightness(‘r’, 0.6) # significantly darker adjust_lightness(‘#F034A3’, 0.6) # slightly darker adjust_lightness((.3,.55,.1), 1.2) # slightly lighter

Contents