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

CRYSTALpytools.electronics module

A post-processing module for electronic properties

class ElectronBand(spin, tick_pos, tick_label, efermi, bands, k_path, geometry=None, reciprocal_latt=None, tick_pos3d=None, k_path3d=None, unit='eV')

Bases: object

Electron band object. Energy unit: eV. E Fermi is aligned to 0.

Parameters:

  • spin (int) – 1, closed shell; 2, open shell

  • tick_pos (array) – 1*nTick array of 1D tick coordinates. Unit: Angstrom

  • tick_label (list) – 1*nTick of default tick labels

  • efermi (float) – Fermi energy. Unit: eV.

  • bands (array) – nBand*nKpoint*nSpin array of energy. Unit: eV

  • k_path (array) – 1D coordinates of k points. Unit: Angstrom

  • geometry (Structure) – Pymatgen structure

  • reciprocal_latt (array) – 3*3 array of reciprocal lattice matrix. Not valid if geometry is specified.

  • tick_pos3d (array) – 1*nTick 3D fractional tick coordinates

  • k_path3d (array) – nKpoints*3 3D fractional coordinates of k points

  • unit (str) – In principle, should always be ‘eV’: eV-Angstrom.

classmethod from_file(band, output=None)

Generate an ElectronBand object from fort.25 / BAND.DAT file. Optional 3D space data is read from the output file of ‘properties’.

Parameters:

  • band (str) – ‘fort.25’ or ‘BAND.DAT’

  • output (str) – Properties output file

Returns:

cls (ElectronBand)

plot(**kwargs)

A wrapper to plot band structure of a single system using matplotlib. For input arguments or plotting multiple systems, check plot.plot_electron_bands().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for ElectronBand object). Check documents for plot.plot_electron_bands().

Returns:

fig (Figure) – Matplotlib figure object

property bandgap

A shortcut for band gap only.

get_bandgap()

Get band gap. For spin-polarized systems, 2*1 arrays are used for \(\alpha\) and \(\beta\) states. Data is rounded to 6 decimal places.

Returns:

  • self.gap (float) – Band gap. Default unit: eV

  • self.vbm (flat) – Valence band maximum, with reference to Fermi level. Default unit: eV

  • self.cbm (float) – Conduction band minimum, with reference to Fermi level. Default unit: eV

  • self.gap_pos (array) – 1D coordinates of vbm (1st element) and cbm (2nd element). For spin-polarized cases, self.gap_pos[0, :] are vbm and cbm of \(\alpha\) state. Default unit: Angstrom

to_pmg(labels=None)

Get Pymatgen BandStructureSymmLine object (inherited from BandStructure). No projection is available for now.

Note

3D information for output file is mandatory here.

Parameters:

labels (list[str]) – K point labels to display in the band structure.

Returns:

BandStructureSymmLine – Pymatgen band structure.

_set_unit(unit)

Set units of data of ElectronBand object. Internal method.

Parameters:

unit (str) – ‘eV’: Energy unit = eV, Length unit = Angstrom; ‘a.u.’: Energy unit = Hartree. Length unit = Bohr

class ElectronDOS(spin, efermi, doss, energy, unit='eV')

Bases: object

Electron DOS object. Energy unit: eV. E Fermi is aligned to 0.

Parameters:

  • spin (int) – 1, closed shell; 2, open shell

  • efermi (float) – Fermi energy. Unit: eV.

  • doss (array) – n_proj*n_energy*spin array of DOS. Positive values for both spin up and spin down states

  • energy (array) – Positions of DOS peaks (x axis)

  • unit (str) – In principle, should always be ‘eV’: eV-Angstrom.

classmethod from_file(dos)

Generate an ElectronDOS object from fort.25 / DOSS.DAT file.

Parameters:

band (str) – ‘fort.25’ or ‘DOSS.DAT’

Returns:

cls (ElectronDOS)

plot(**kwargs)

A wrapper to plot density of states of a single system with matplotlib. For input arguments or plotting multiple systems, check plot.plot_electron_doss().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for ElectronDOS object). Check documents for plot.plot_electron_doss().

Returns:

fig (Figure) – Matplotlib figure object

_set_unit(unit)

Set units of data of ElectronDOS object.

Parameters:

unit (str) – ‘eV’: Energy unit = eV; ‘a.u.’: Energy unit = Hartree

class ElectronBandDOS(band, dos)

Bases: object

Electron band + dos object. Energy unit: eV. E Fermi is aligned to 0.

Parameters:
classmethod from_file(*files, output=None)

Get ElectronBandDOS object from files

Parameters:

  • *files (str) – 2 files, the first one is for band, ‘fort.25’ or ‘BAND.DAT’; the second one is for DOS, ‘fort.25’ or ‘DOSS.DAT’. Or a single ‘fort.25’ file with both band and DOS.

  • output (str) – Property output file

Returns:

cls (ElectronBandDOS)

plot(**kwargs)

A wrapper to plot electron band structure + density of states of a single system with matplotlib. For input arguments, check plot.plot_electron_banddos().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for ElectronBandDOS object). Check documents for plot.plot_electron_banddos().

Returns:

fig (Figure) – Matplotlib figure object

_set_unit()

Set units of data of ElectronBandDOS object.

Parameters:

unit (str) – ‘eV’: Energy unit = eV, length unit = Angstrom ‘a.u.’: Energy unit = Hartree, length unit = Bohr

class ChargeDensity(data, base, spin, dimen, struc=None, unit='Angstrom')

Bases: object

Charge (spin) density object. Unit: \(e.\AA^{-3}\). 3D plot under developing.

Parameters:

  • data (array) – Plot data. nY*nX*nSpin (2D).

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)

  • spin (int) – 1 or 2.

  • dimen (int) – Dimensionality of the plot.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(*files, output=None, method='normal')

Generate a ChargeDensity object from a single file, or from multiple files by substracting values from the first entry. Can be used for multiple dimensions (2D only now. 3D under development.)

Note

The standard screen output is required to identify the indices of corresponding 2D data maps. Otherwise the code only reads the first 2D data map.

Available methods are:

  • ‘substact’: Substracting data from the first entry based on following

    entries. Multiple entries only.

  • ‘alpha_beta’: Save spin-polarized data in \(\alpha\) /

    \(\beta\) states, rather than charge(\(\alpha+\beta\)) / spin(\(\alpha-\beta\)). Single entry only.

Parameters:

*files (str) – Path to the charge density / spin density file(s). All the entries must be in the same file format.

Returns:

cls (ChargeDensity)

substract(*args)

Substracting data of the same type from the object.

Parameters:

*args (str|ChargeDensity) – File names or ChargeDensity objects.

Returns:

self (ChargeDensity) – spin dimension, if there is, is not kept. Only charge density difference is substracted.

alpha_beta()

Get the \(\alpha\) / \(\beta\) state density, rather than charge(\(\alpha+\beta\)) / spin(\(\alpha-\beta\)). spin=2 only.

Returns:

self (ChargeDensity) – The first entry of self.data is \(\alpha\) state density and the second is \(\beta\) state.

plot_2D(unit='Angstrom', option='both', levels=150, lineplot=False, linewidth=1.0, isovalues=None, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D charge/spin density map. A wrapper of plot.plot_dens_ECHG and plot.plot_spin_ECHG.

3 styles are available:

  1. lineplot=True and colorplot=True: The color-filled contour

    map with black contour lines. Dotted lines for negative values and solid lines for positive values. The solid line twice in width for 0.

  2. lineplot=False and colorplot=True: The color-filled contour

    map.

  3. lineplot=True and colorplot=False: The color coded contour

    line map. Blue dotted line for negative values and red solid lines for positive values. The balck solid line twice in width for 0.

Available options:

  • ‘both’If spin polarized, plot both charge and spin densities.

    Otherwise plot charge densities.

  • ‘charge’: Plot charge density.

  • ‘spin’: Plot spin density.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • option (str) – Available options see above.

  • levels (int|array) – Set levels of contour plot. A number for linear scaled plot colors or an array for user-defined levels, must be consistent with ``unit``. 2*nLevel can be defined when option='both'.

  • lineplot (bool) – Plot contour lines.

  • linewidth (float) – Contour linewidth. Useful only if lineplot=True. Other properties are not editable. Solid black lines for positive values and 0, dotted for negative.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. 1*2 list of colorbar titles can be set for spin-polarized systems. ‘default’ for unit and symbol. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 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\) (i.e., expansion first).

  • edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Titles for both charge and spin densities. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (list[int]) – Developer Only, indices of axes in fig.axes.

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

Returns:

  • fig (Figure) – Matplotlib figure object

  • ax (Axes) – Matplotlib axes object

_set_unit(unit)

Set units of data of ChargeDensity object.

Parameters:

unit (str) – ‘Angstrom’, \(e.\AA^{-3}\). ‘a.u.’, \(e.Bohr^{-3}\).