\(\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

The class for electron band projected along high symmetry lines. For ‘3D band structures’, please refer to the electronics.FermiSurface class. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

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

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

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

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

  • bands (array) – nBand*nKpoint*nSpin array of energy of band structure. Aligned to \(E_{F}=0\). Unit: eV.

  • k_path (array) – 1D coordinates of k points for band structure. Unit: \(\AA\).

  • geometry (Structure) – Pymatgen structure

  • reciprocal_latt (array) – 3*3 array of reciprocal lattice matrix.

  • 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 ElectronBand object from CRYSTAL BAND.DAT / fort.25 file. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

  • band (str) – Name of BAND.DAT / fort.25 file.

  • output (str) – Properties output file.

Returns:

cls (ElectronBand)

plot(**kwargs)

For band structure plotting, it is a wrapper of plot.plot_electron_bands() with option ‘single’ (i.e., single system). For input arguments or plotting multiple systems, check documentations there.

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. Unit is consistent with the self.unit attribute.

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. Unit is consistent with the self.unit attribute.

Returns:

  • self.gap (float) – Band gap.

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

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

  • self.gap_pos (array) – Coordinates of vbm (1st element) and cbm (2nd element) 3D coordinates are returned if self.k_path3d is available. For spin-polarized cases, self.gap_pos[0] are vbm and cbm of \(\alpha\) state.

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 = \(\AA^{-1}\); ‘a.u.’: Energy unit = Hartree. Length unit = Bohr:math:^{-1}

class FermiSurface(geometry, bands, efermi=0.0, unit='eV')

Bases: object

The class for electron band sampled across the first brillouin zone (1BZ), aka \(E(k)\). For ‘normal’ band structures, please refer to the electronics.ElectronBand class. Energy unit: eV. Fermi energy is aligned to 0. For 3D and 2D systems only.

Note

The data grid is defined and saved in reciprocal unit cell, rather than 1BZ.

Parameters:

  • geometry (array|CStructure) – Matrix of reciprocal lattice, or an extended pymatgen Structure object.

  • bands (array) – nBand*nZ*nY*nX*nSpin of band energy aligned to \(E_{F}=0\). The non-periodic direction must have the dimension of 1. Unit: eV.

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

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

Returns:

  • self (FermiSurface) – Attributes listed below.

  • self.rlattice (array) – Reciprocal lattice.

  • self.dimension (int) – 2 or 3

  • self.spin (int) – 1 or 2

  • self.bands (array) – Bands

  • self.efermi (float)

  • self.BZ (list) – Cartesian coordinates of vertices of 1BZ. Arranged in planes (i.e., the element of 4*3 array represents a plane of 4 vertices).

  • self.unit (str) – ‘eV’ or ‘a.u.’

classmethod from_file(band, output=None)

Generate FermiSurface object from CRYSTAL fort.35 file. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

  • band (str) – Name of fort.35 files.

  • output (str) – Properties output file.

Returns:

cls (FermiSurface)

property bandgap

A shortcut for band gap. Unit is consistent with the self.unit attribute.

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. Unit is consistent with the self.unit attribute.

Returns:

  • self.gap (float) – Band gap.

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

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

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

plot(band_index='vb', isovalue=0.0, interp='no interp', interp_size=1, colormap='jet', opacity=1.0, transparent=False, BZ_plot=True, BZ_scale=1.0, BZ_color=(0.0, 0.0, 0.0), BZ_linewidth=1.0, tick_pos=[], tick_label=[], **kwargs)

Plot \(E(k)\) in the first brillouin zone (1BZ).

Note

MayaVi is used to display \(E(k)\), which is not installed by default.

  • For 3D systems, it is displayed as isosurfaces of \(E(k)\).

  • For 2D systems, the distribution is displayed, so isovalue is

    disabled.

For 3D systems, displaying multiple bands is discouraged. But the user can still visualize the isosurfaces of multiple bands and the same isovalue and colormap applies to all the bands.

Note

Too large interp_size might be very memory and cpu demanding!

Parameters:

  • band_index (list|str|int) – Indices of bands to plot. Starting from 1. For spin-polarized cases, one can specify ‘4a’ for the \(\alpha\) state of band 4. Use ‘vb’ and ‘cb’ to display the highest valance or the lowest conduction band.

  • isovalue (float|list) – 3D system only Isovalue of surfaces.

  • interp (str) –

    Interpolate data to smoothen the plot. ‘no interp’ or ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’. please refer to scipy.interpolate.interpn

    The interpolated data is not saved.

  • interp_size (list[int]|int) – The new size of interpolated data (list) or a scaling factor. Valid only when ``interp`` is not ‘no interp’.

  • colormap (str) – Mayavi colormap.

  • opacity (float) – See Mayavi mlab.

  • transparent (bool) –

    See Mayavi mlab.

  • BZ_plot (bool) – Whether to plot the boundary of 1BZ.

  • BZ_scale (float) – Must be between 1 and 2. Do not truncate data grid at the boundary of 1BZ, slightly expanding it by the scaling factor. This does not change the 1BZ frame plotted.

  • BZ_color (array) –

    Color of the 1BZ plot. See Mayavi colormap.

  • BZ_linewidth (float) – Linewidth of the 1BZ plot.

  • tick_pos (array) – Not implemented

  • tick_label (list) – Not implemented

  • **kwargs – Other keywords passed to the mlab.view() command to adjust views. By default only distance='auto' is used.

Returns:

None

to_bxsf(filename, band_index=[])

3D data only

Write data into the XCrySDen BXSF file format. Unit: \(\AA^{-1}\) and eV. Band labels:

  • [0:-2]: Band index strating from 1;

  • -2: Useless, 0;

  • -1: Spin. Alpha / No spin, 1; Beta, 2

Parameters:

  • filename (str) – The output xsf filename.

  • band_index (list|str|int) – Indices of bands to be saved. Same as the band_index option of the plot() method. ‘[]’ for all bands.

Returns:

None

classmethod _get_band_index(band, index)

The method to process band indices.

Parameters:

  • band (array) – nBand*nZ*nY*nX*nSpin array.

  • index (list|str|int) – See the plot() method.

Returns:

  • iband (array) – 1*nIndex indices of band, starting from 0.

  • ispin (array) – 1*nIndex indices of spin, 0 or 1.

_set_unit(unit)

Set units of data of FermiSurface object. Internal method.

Parameters:

unit (str) – ‘eV’: Energy unit = eV, Length unit = \(\AA^{-1}\); ‘a.u.’: Energy unit = Hartree. Length unit = Bohr:math:^{-1}

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}\).

Parameters:

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

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

  • 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 and 3D).

Note

The standard screen output is required to identify the indices of corresponding 2D data maps. Otherwise the code only reads the first 1 (2) 2D data maps for spin = 1 (2).

Available methods are:

  • ‘normal’: Normal. For 2D fort.25 files, 1 entry. For 3D cube files,

    2 entries for charge and spin if needed.

  • ‘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\)). For 2D fort.25 files, 1 entry. For 3D cube files, 2 entries for charge and spin if needed.

Parameters:

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

  • output (str) – Screen output file.

  • method (str) – See above.

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

to_xsf(filename)

2D / 3D data only

Write data into the XCrySDen XSF file format. The code writes into either 2D or 3D data grids depending on the dimension attribute. For spin-polarized cases, 2 maps will be written with the title ‘alpha+beta’ and ‘alpha-beta’ and into 2 data blocks. Objects updated by the alpha_beta() method will get grids with the same titles, which needs extra attention.

Note

Geometry information is mandatory.

Note

For 3D data grid, if CUBE file(s) are read without output, the XSF file output has the 3D ‘CRYSTAL’ periodicity. As far as the authors have been aware of, this only causes Segmentation Fault of XCrySDen 1.6.2 when dealing with low dimensional systems. Available solution includes 1. including output file 2. using other software such as VESTA 3. Changing the keyword manually.

Parameters:

filename (str) – The output xsf filename.

Returns:

None

_set_unit(unit)

Set units of data of ChargeDensity object.

Parameters:

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