electrons Package

electrons Package

This module provides classes and functions for the analysis of electronic properties.

eskw Package

Interface to the ESKW.nc file storing the (star-function) interpolated band structure produced by Abinit.

class abipy.electrons.eskw.EskwFile(filepath)

Bases: AbinitNcFile, Has_Structure, Has_ElectronBands, NotebookWriter

This file contains the (star-function) interpolated band structure produced by Abinit. It’s similar to the GSR file but it does not contain the header and energies.

Usage example:

with EskwFile("foo_ESKW.nc") as eskw:
    eskw.ebands.plot()

Inheritance Diagram

classmethod from_file(filepath: str)

Initialize the object from a netcdf file.

einterp()

band_block()

to_string(verbose=0)

String representation.

close()

Close the file.

property ebands

abipy.electrons.ebands.ElectronBands object.

property structure

abipy.core.structure.Structure object.

params()

OrderedDict with parameters that might be subject to convergence studies.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

bse Module

Classes for the analysis of BSE calculations

class abipy.electrons.bse.DielectricFunction(structure, qpoints, wmesh, emacros_q, info)

Bases: object

This object stores the frequency-dependent macroscopic dielectric function computed for different q-directions in reciprocal space.

to_string(verbose=0, with_info=False) → str

String representation.

property num_qpoints: int

Number of q-points.

property qfrac_coords: ndarray

numpy.ndarray with the fractional coordinates of the q-points.

plot(ax=None, **kwargs) → Any

Plot the MDF.

Parameters:

ax – matplotlib.axes.Axes or None if a new figure should be created.

kwargs	Meaning
only_mean	True if only the averaged spectrum is wanted (default True)

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_ax(ax, qpoint=None, **kwargs) → list

Helper function to plot data on the axis ax.

Parameters:

• ax – matplotlib.axes.Axes

• qpoint – index of the q-point or abipy.core.kpoints.Kpoint object or None to plot emacro_avg.

• kwargs –

  Keyword arguments passed to matplotlib. Accepts also:

  cplx_mode:

  string defining the data to print (case-insensitive). Possible choices are

  • ”re” for real part

  • ”im” for imaginary part only.

  • ”abs’ for the absolute value

  Options can be concated with “-“.

class abipy.electrons.bse.MdfFile(filepath: str)

Bases: AbinitNcFile, Has_Structure, NotebookWriter

Usage example:

with MdfFile("foo_MDF.nc") as mdf:
    mdf.plot_mdfs()

Inheritance Diagram

classmethod from_file(filepath: str) → MdfFile

Initialize the object from a Netcdf file

to_string(verbose=0) → str

String representation.

close() → None

Close the file.

structure()

abipy.core.structure.Structure object.

exc_mdf()

Excitonic macroscopic dieletric function.

rpanlf_mdf()

RPA dielectric function without local-field effects.

gwnlf_mdf()

RPA-GW dielectric function without local-field effects.

property qpoints

List of q-points.

property qfrac_coords: ndarray

numpy.ndarray with the fractional coordinates of the q-points.

params()

Dictionary with the parameters that are usually tested for convergence. Used to build Pandas dataframes in Robots.

get_mdf(mdf_type='exc')

” Returns the macroscopic dielectric function.

plot_mdfs(cplx_mode='Im', mdf_type='all', qpoint=None, **kwargs) → Any

Plot the macroscopic dielectric function.

Parameters:

• cplx_mode –

  string defining the data to print (case-insensitive). Possible choices are

  • ”re” for real part

  • ”im” for imaginary part only.

  • ”abs’ for the absolute value

  Options can be concated with “-“.

• mdf_type –

  Select the type of macroscopic dielectric function. Possible choices are

  • ”exc” for the MDF with excitonic effects.

  • ”rpa” for RPA with KS energies.

  • ”gwrpa” for RPA with GW (or KS-corrected) results

  • ”all” if all types are wanted.

  Options can be concated with “-“.

• qpoint – index of the q-point or Kpoint object or None to plot emacro_avg.

get_tensor(mdf_type='exc')

Get the macroscopic dielectric tensor from the MDF.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.bse.MdfReader(path)

Bases: ETSF_Reader

This object reads data from the MDF.nc file produced by ABINIT.

Inheritance Diagram

property structure: Structure

abipy.core.structure.Structure object.

qpoints()

List of q-points (ndarray).

wmesh()

The frequency mesh in eV.

read_params() → dict

Dictionary with the parameters of the run.

read_exc_mdf()

Returns the excitonic MDF.

read_rpanlf_mdf()

Returns the KS-RPA MDF without LF effects.

read_gwnlf_mdf()

Returns the GW-RPA MDF without LF effects.

class abipy.electrons.bse.MdfPlotter

Bases: object

Class for plotting Macroscopic dielectric functions.

Usage example:

plotter = MdfPlotter()
plotter.add_mdf("EXC", exc_mdf)
plotter.add_mdf("KS-RPA", rpanlf_mdf)
plotter.plot()

add_mdf(label, mdf)

Adds a DielectricFunction for plotting.

Parameters:

• name – name for the MDF. Must be unique.

• mdf – DielectricFunction object.

plot(ax=None, cplx_mode='Im', qpoint=None, xlims=None, ylims=None, fontsize=8, **kwargs) → Any

Get a matplotlib plot showing the MDFs.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• cplx_mode – string defining the data to print (case-insensitive). Possible choices are re for the real part, im for imaginary part only. abs for the absolute value. Options can be concated with “-“.

• qpoint – index of the q-point or Kpoint object or None to plot emacro_avg.

• xlims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Same meaning as ylims but for the y-axis

• fontsize – Legend and label fontsize.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

class abipy.electrons.bse.MultipleMdfPlotter

Bases: object

Class for plotting multipe macroscopic dielectric functions extracted from several MDF.nc files

Usage example:

plotter = MultipleMdfPlotter()
plotter.add_mdf_file("file1", mdf_file1)
plotter.add_mdf_file("file2", mdf_file2)
plotter.plot()

MDF_TYPES = ('exc', 'rpa', 'gwrpa')

MDF_TYPECPLX2TEX = {'exc': {'abs': '$|\\varepsilon_{exc}|$', 'im': '$\\Im(\\varepsilon_{exc}$)', 're': '$\\Re(\\varepsilon_{exc})$'}, 'gwrpa': {'abs': '$|\\varepsilon_{gw-rpa}|$', 'im': '$\\Im(\\varepsilon_{gw-rpa})$', 're': '$\\Re(\\varepsilon_{gw-rpa})$'}, 'rpa': {'abs': '$|\\varepsilon_{rpa}|$', 'im': '$\\Im(\\varepsilon_{rpa})$', 're': '$\\Re(\\varepsilon_{rpa})$'}}

to_string(**kwargs) → str

String representation.

add_mdf_file(label, obj)

Extract dielectric functions from object obj, store data for plotting.

Parameters:

• label – label associated to the MDF file. Must be unique.

• mdf – filepath or MdfFile object.

plot(mdf_type='exc', qview='avg', xlims=None, ylims=None, fontsize=8, **kwargs) → Any

Plot all macroscopic dielectric functions (MDF) stored in the plotter

Parameters:

• mdf_type – Selects the type of dielectric function. “exc” for the MDF with excitonic effects. “rpa” for RPA with KS energies. “gwrpa” for RPA with GW (or KS-corrected) results.

• qview – “avg” to plot the results averaged over q-points. “all” to plot q-point dependence.

• xlims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Same meaning as ylims but for the y-axis

• fontsize – fontsize for titles and legend.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_mdftype_cplx(mdf_type, cplx_mode, qpoint=None, ax=None, xlims=None, ylims=None, with_legend=True, with_xlabel=True, with_ylabel=True, fontsize=8, **kwargs) → Any

Helper function to plot data corresponds to mdf_type, cplx_mode, qpoint.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• mdf_type

• cplx_mode – string defining the data to print (case-insensitive). Possible choices are re for the real part, im for imaginary part only. abs for the absolute value.

• qpoint – index of the q-point or Kpoint object or None to plot emacro_avg.

• xlims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Same meaning as ylims but for the y-axis

• with_legend – True if legend should be added

• with_xlabel

• with_ylabel

• fontsize – Legend and label fontsize.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

ipw_select_plot()

Return an ipython widget with controllers to select the plot.

charges Module

Hirshfeld Charges.

class abipy.electrons.charges.HirshfeldCharges(electron_charges, structure, reference_charges=None)

Bases: Charges

Class representing the charges obtained from the Hirshfeld analysis. The charges refer to the total charges for each atom (i.e. Z-n_electrons). An eccess of electron has a negative charge

Inheritance Diagram

classmethod from_cut3d_outfile(filepath, structure)

Generates a HirshfeldCharges object from the outputfile of cut3d and a structure.

class abipy.electrons.charges.BaderCharges(electron_charges, structure, reference_charges=None)

Bases: Charges

Class representing the charges obtained from the Bader analysis. TThe charges refer to the total charges for each atom (i.e. Z-n_electrons). An eccess of electron has a negative charge

Inheritance Diagram

classmethod from_files(density_path, pseudopotential_paths, with_core=True, workdir=None, **kwargs)

Uses the abinit density files and the bader executable from Henkelmann et al. to calculate the bader charges of the system. If pseudopotentials are given, the atomic charges will be extracted as well. See also [Henkelman2006].

The extraction of the core charges may be a time consuming calculation, depending on the size of the system. A tuning of the parameters may be required (see Density.ae_core_density_on_mesh).

Parameters:

• density_path – Path to the abinit density file. Can be a fortran _DEN or a netCDF DEN.nc file. In case of fortran file, requires cut3d (version >= 8.6.1) for the convertion.

• pseudopotential_paths – Dictionary {element: pseudopotential path} for all the elements present in the system.

• with_core – Core charges will be extracted from the pseudopotentials with the Density.ae_core_density_on_mesh method. Requires pseudopotential_paths.

• workdir – Working directory. If None, a temporary directory is created.

• kwargs – arguments passed to the method Density.ae_core_density_on_mesh

Returns:

An instance of BaderCharges

denpot Module

Density/potential files in netcdf/fortran format.

class abipy.electrons.denpot.DensityNcFile(filepath: str)

Bases: _NcFileWithField

Netcdf File containing the electronic density.

Usage example:

with DensityNcFile("foo_DEN.nc") as ncfile:
    ncfile.density
    ncfile.ebands.plot()

Inheritance Diagram

field_name = 'density'

density()

Density object.

to_string(verbose=0) → str

String representation.

write_chgcar(filename=None)

Write density in CHGCAR format. Return ChgCar instance.

write_xsf(filename=None)

Write density in XSF format (xcrysden)

write_cube(filename=None, spin='total')

Write density in CUBE format.

class abipy.electrons.denpot.VhartreeNcFile(filepath: str)

Bases: _NcFileWithField

Inheritance Diagram

field_name = 'vh'

vh()

Hartree potential.

class abipy.electrons.denpot.VxcNcFile(filepath: str)

Bases: _NcFileWithField

Inheritance Diagram

field_name = 'vxc'

vxc()

XC potential.

class abipy.electrons.denpot.VhxcNcFile(filepath: str)

Bases: _NcFileWithField

Inheritance Diagram

field_name = 'vhxc'

vhxc()

Hartree + XC potential.

class abipy.electrons.denpot.PotNcFile(filepath: str)

Bases: _NcFileWithField

POT file produced by the GS part containing the total KS potential in real space.

Inheritance Diagram

field_name = 'vks'

vks()

Hartree + XC potential + sum of local pseudo-potential terms.

ebands Module

Classes to analyse electronic structures.

class abipy.electrons.ebands.ElectronBands(structure, kpoints, eigens, fermie, occfacts, nelect, nspinor, nspden, nband_sk=None, smearing=None, linewidths=None)

Bases: Has_Structure

Object storing the electron band structure.

fermie

Fermi level in eV. Note that, if the band structure has been computed with a NSCF run, fermie corresponds to the fermi level obtained in the SCF run that produced the density used for the band structure calculation.

Inheritance Diagram

Error

alias of ElectronBandsError

pad_fermie = 0.001

classmethod from_file(filepath: str) → ElectronBands

Initialize an instance of abipy.electrons.ebands.ElectronBands from the netCDF file filepath.

classmethod from_binary_string(bstring) → ElectronBands

Build object from a binary string with the netcdf data. Useful for implementing GUIs in which widgets returns binary data.

classmethod from_dict(d: dict) → ElectronBands

Reconstruct object from the dictionary in MSONable format produced by as_dict.

as_dict() → dict

Return dictionary with JSON serialization.

classmethod as_ebands(obj: Any) → ElectronBands

Return an instance of abipy.electrons.ebands.ElectronBands from a generic object obj. Supports:

• instances of cls

• files (string) that can be open with abiopen and that provide an ebands attribute.

• objects providing an ebands attribute

classmethod from_mpid(material_id, nelect=None, has_timerev=True, nspinor=1, nspden=None, line_mode=True) → ElectronBands

Read band structure data corresponding to a materials project material_id. and return Abipy ElectronBands object. Return None if bands are not available.

Parameters:

• material_id (str) – Materials Project material_id (a string, e.g., mp-1234).

• nelect – Number of electrons in the unit cell. If None, this value is automatically computed using the Fermi level (if metal) or the VBM indices reported in the JSON document sent by the MP database. It is recommended to pass nelect explictly if this quantity is known in the caller.

• nspinor – Number of spinor components.

• line_mode (bool) – If True, fetch a BandStructureSymmLine object (default). If False, return the uniform band structure.

to_json() → str

Returns a JSON string representation of the MSONable object.

property structure: Structure

abipy.core.structure.Structure object.

get_plotter_with(self_key, other_key, other_ebands)

Build and abipy.electrons.ebands.ElectronBandsPlotter from self and other, use self_key and other_key as keywords

property spins

Spin range

property nband: int

property kidxs

Range with the index of the k-points.

property eigens: ndarray

Eigenvalues in eV. numpy.ndarray with shape [nspin, nkpt, mband].

property linewidths: ndarray

linewidths in eV. numpy.ndarray with shape [nspin, nkpt, mband].

property has_linewidths: bool

True if bands with linewidths.

property occfacts: ndarray

Occupation factors. numpy.ndarray with shape [nspin, nkpt, mband].

property reciprocal_lattice

pymatgen.core.lattice.Lattice with the reciprocal lattice vectors in Angstrom.

property shape: tuple

Shape of the array with the eigenvalues.

property has_metallic_scheme: bool

True if we are using a metallic scheme for occupancies.

set_fermie_to_vbm() → float

Set the Fermi energy to the valence band maximum (VBM). Useful when the initial fermie energy comes from a GS-SCF calculation that may underestimate the Fermi energy because e.g. the IBZ sampling is shifted whereas the true VMB is at Gamma.

Return: New Fermi energy in eV.

set_fermie_from_edos(edos, nelect=None) → float

Set the Fermi level using the integrated DOS computed in edos.

Args:

edos: abipy.electrons.ebands.ElectronDos object. nelect: Number of electrons. If None, the number of electrons in self. is used

Return: New fermi energy in eV.

set_fermie(new_fermie: float) → float

Set the new fermi energy. Return new value

with_points_along_path(frac_bounds=None, knames=None, dist_tol=1e-12)

Build new abipy.electrons.ebands.ElectronBands object containing the k-points along the input k-path specified by frac_bounds. Useful to extract energies along a path from calculation performed in the IBZ.

Parameters:

• frac_bounds – [M, 3] array with the vertexes of the k-path in reduced coordinates. If None, the k-path is automatically selected from the structure.

• knames – List of strings with the k-point labels defining the k-path. It has precedence over frac_bounds.

• dist_tol – A point is considered to be on the path if its distance from the line is less than dist_tol.

Returns:

namedtuple with the following attributes:

ebands: |ElectronBands| object.
ik_new2prev: Correspondence between the k-points in the new ebands and the kpoint
    of the previous band structure (self).

classmethod empty_with_ibz(ngkpt, structure, fermie, nelect, nsppol, nspinor, nspden, mband, shiftk=(0, 0, 0), kptopt=1, smearing=None, linewidths=None) → ElectronBands

Build an empty ElectronBands instance with k-points in the IBZ.

get_dict4pandas(with_geo=True, with_spglib=True) → dict

Return a OrderedDict with the most important parameters:

• Chemical formula and number of atoms.

• Lattice lengths, angles and volume.

• The spacegroup number computed by Abinit (set to None if not available).

• The spacegroup number and symbol computed by spglib (set to None not with_spglib).

Useful to construct pandas DataFrames

Parameters:

• with_geo – True if structure info should be added to the dataframe

• with_spglib – If True, spglib is invoked to get the spacegroup symbol and number.

has_bzmesh()

True if the k-point sampling is homogeneous.

has_bzpath()

True if the bands are computed on a k-path.

kptopt()

The value of the kptopt input variable.

has_timrev()

True if time-reversal symmetry is used in the BZ sampling.

get_bz2ibz_bz_points(require_gamma_centered=False)

Return named tupled with the mapping bz2ibz and the list of k-points in the BZ.

Parameters:

require_gamma_centered – True if the k-mesh should be Gamma-centered

isnot_ibz_sampling(require_gamma_centered=False) → str

Test whether the k-points in the band structure represent an IBZ with an associated k-mesh Return string with error message if the condition is not fullfilled.

Parameters:

require_gamma_centered – True if the k-mesh should be Gamma-centered

kindex(kpoint) → int

The index of the k-point in the internal list of k-points. Accepts: abipy.core.kpoints.Kpoint instance or integer.

skb_iter()

Iterator over (spin, k, band) indices.

deepcopy() → ElectronBands

Deep copy of the ElectronBands object.

degeneracies(spin, kpoint, bands_range, tol_ediff=0.001) → list

Returns a list with the indices of the degenerate bands.

Parameters:

• spin – Spin index.

• kpoint – K-point index or abipy.core.kpoints.Kpoint object

• bands_range – List of band indices to analyze.

• tol_ediff – Tolerance on the energy difference (in eV)

Returns:

List of tuples [(e0, bands_e0), (e1, bands_e1, ….] Each tuple stores the degenerate energy and a list with the band indices. The band structure of silicon at Gamma, for example, will produce something like: [(-6.3, [0]), (5.6, [1, 2, 3]), (8.1, [4, 5, 6])]

enemin(spin=None, band=None) → float

Compute the minimum of the eigenvalues.

enemax(spin=None, band=None) → float

Compute the maximum of the eigenvalues.

dispersionless_states(erange=None, deltae=0.05, kfact=0.9) → list[Electron]

This function detects dispersionless states. A state is dispersionless if there are more that (nkpt * kfact) energies in the energy intervale [e0 - deltae, e0 + deltae]

Parameters:

• [emin (erange=Energy range to be analyzed in the form)

• emax]

• deltae – Defines the energy interval in eV around the KS eigenvalue.

• kfact – Can be used to change the criterion used to detect dispersionless states.

Returns:

List of Electron objects. Each item contains information on the energy, the occupation and the location of the dispersionless band.

get_dataframe(e0='fermie', brange=None, ene_range=None) → DataFrame

Return a pandas.DataFrame with the following columns:

[‘spin’, ‘kidx’, ‘band’, ‘eig’, ‘occ’, ‘kpoint’]

where:

Column	Meaning
spin	spin index
kidx	k-point index
band	band index
eig	KS eigenvalue in eV.
occ	Occupation of the state.
kpoint	Kpoint object

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0 The Fermi energy is saved in df.fermie

• brange – If not None, only bands such as brange[0] <= band_index < brange[1] are included.

• ene_range – If not None, only bands whose energy in inside [erange[0], [erange[1]] are included. brange and ene_range are mutually exclusive. Note that e0 is taken into account. when computing the energy.

boxplot(ax=None, e0='fermie', brange=None, ene_range=None, swarm=False, **kwargs) → Any

Use seaborn to draw a box plot to show the distributions of the eigenvalues with respect to the band index.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV. - None: Don’t shift energies, equivalent to e0 = 0.

• brange – Only bands such as brange[0] <= band_index < brange[1] are included in the plot.

• ene_range – If not None, only bands whose energy in inside [erange[0], [erange[1]] are included. brange and ene_range are mutually exclusive. Note that e0 is taken into account. when computing the energy window.

• swarm – True to show the datapoints on top of the boxes.

• kwargs – Keyword arguments passed to seaborn boxplot.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

boxplotly(e0='fermie', brange=None, ene_range=None, swarm=False, fig=None, rcd=None, **kwargs)

Use ployly to draw a box plot to show the distributions of the eigenvalues with respect to the band index.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV. - None: Don’t shift energies, equivalent to e0 = 0.

• brange – Only bands such as brange[0] <= band_index < brange[1] are included in the plot.

• ene_range – If not None, only bands whose energy in inside [erange[0], [erange[1]] are included. brange and ene_range are mutually exclusive. Note that e0 is taken into account. when computing the energy window.

• swarm – True to show the datapoints on top of the boxes.

• fig – plotly figure or None if a new figure should be created.

• rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.

• kwargs – Keyword arguments passed to plotly px.box.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

classmethod from_pymatgen(pmg_bands, nelect, weights=None, has_timerev=True, ksampling=None, smearing=None, nspinor=1, nspden=None) → ElectronBands

Convert a pymatgen band structure object to an Abipy abipy.electrons.ebands.ElectronBands object.

Parameters:

• pmg_bands – pymatgen band structure object.

• nelect – Number of electrons in unit cell.

• weights – List of K-points weights (normalized to one, same order as pmg_bands.kpoints). This argument is optional but recommended when pmg_bands represents an IBZ sampling. If weights are not provided, Abipy methods requiring integrations in the BZ won’t work.

• has_timerev – True if time-reversal symmetry can be used.

• ksampling – dictionary with parameters passed to KSamplingInfo defining the k-points sampling. If None, hard-coded values are used. This argument is recommended if IBZ sampling.

• smearing – dictionary with parameters passed to Smearing If None, default hard-coded values are used.

• nspinor – Number of spinor components.

• nspden – Number of independent spin-density components. If None, nspden is automatically computed from nsppol

Warning

The Abipy band structure contains more information than the pymatgen object so the conversion is not complete, especially if you rely on the default values. Please read carefylly the docstring and the code and use the optional arguments to pass additional data required by AbiPy if you need a complete conversion.

to_pymatgen()

Return a pymatgen band structure object from an Abipy abipy.electrons.ebands.ElectronBands object.

property lomos: list[Electron]

lomo states for each spin channel as a list of nsppol Electron.

lomo_sk(spin, kpoint) → Electron

Returns the LOMO state for the given spin, kpoint.

Parameters:

• spin – Spin index

• kpoint – Index of the kpoint or abipy.core.kpoints.Kpoint object.

homo_sk(spin, kpoint) → Electron

Returns the HOMO state for the given spin, kpoint.

Parameters:

• spin – Spin index

• kpoint – Index of the kpoint or abipy.core.kpoints.Kpoint object.

lumo_sk(spin, kpoint) → Electron

Returns the LUMO state for the given spin, kpoint.

Parameters:

• spin – Spin index

• kpoint – Index of the kpoint or abipy.core.kpoints.Kpoint object.

property homos: list[Electron]

homo states for each spin channel as a list of nsppol Electron.

property lumos: list[Electron]

lumo states for each spin channel as a list of nsppol Electron.

get_edge_state(vbm_or_cbm, spin=None)

property bandwidths: list[float]

The bandwidth for each spin channel i.e. the energy difference (homo - lomo).

property fundamental_gaps: List[ElectronTransition]

List of ElectronTransition with info on the fundamental gaps for each spin.

property direct_gaps: List[ElectronTransition]

List of nsppol ElectronTransition with info on the direct gaps for each spin.

get_gaps_string(with_latex=True, unicode=False) → str

Return string with info about fundamental and direct gap (if not metallic scheme)

Parameters:

• with_latex – True to get latex symbols for the gap names and formula else text.

• unicode – True to get unicode symbols for the formula else text.

get_kpoints_and_band_range_for_edges() → tuple

Find the reduced coordinates and the band indice associate to the band edges. Important: Call set_fermie_to_vbm() to set the Fermi level to the VBM before calling this method.

Return: (k0_list, effmass_bands_f90) (Fortran notation)

to_string(title=None, with_structure=True, with_kpoints=False, verbose=0) → str

Human-readable string with useful info such as band gaps, position of HOMO, LOMO…

Parameters:

• with_structure – False if structural info shoud not be displayed.

• with_kpoints – False if k-point info shoud not be displayed.

• verbose – Verbosity level.

new_with_irred_kpoints(prune_step=None) → ElectronBands

Return a new abipy.electrons.ebands.ElectronBands object in which only the irreducible k-points are kept. This method is mainly used to prepare the band structure interpolation as the interpolator will likely fail if the input k-path contains symmetrical k-points.

Parameters:

• prune_step – Optional argument used to select a subset of the irreducible points found.

• None (If prune_step is)

• used. (all irreducible k-points are)

spacing(axis=None) → StatParams

Compute the statistical parameters of the energy spacing, i.e. e[b+1] - e[b]

statdiff(other, axis=None, numpy_op=<ufunc 'absolute'>) → StatParams

Compare the eigenenergies of two bands and compute the statistical parameters: mean, standard deviation, min and max The bands are aligned wrt to their fermi level.

Parameters:

• other – abipy.electrons.ebands.ElectronBands object.

• axis – Axis along which the statistical parameters are computed. The default is to compute the parameters of the flattened array.

• numpy_op – Numpy function to apply to the difference of the eigenvalues. The default computes |self.eigens - other.eigens|.

Returns:

namedtuple with the statistical parameters in eV

ipw_edos_widget()

Return an ipython widget with controllers to compute the electron DOS.

get_edos(method: str = 'gaussian', step: float = 0.05, width: float = 0.1) → ElectronDos

Compute the electronic DOS on a linear mesh.

Parameters:

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

Returns: abipy.electrons.ebands.ElectronDos object.

compare_gauss_edos(widths, step=0.1) → ElectronDosPlotter

Compute the electronic DOS with the Gaussian method for different values of the broadening. Return plotter object.

Parameters:

• widths – List with the tandard deviation (eV) of the gaussian.

• step – Energy step (eV) of the linear mesh.

Return: abipy.electrons.ebands.ElectronDosPlotter

plot_transitions(omega_ev, qpt=(0, 0, 0), atol_ev=0.1, atol_kdiff=0.0001, ylims=None, ax=None, alpha=0.4, **kwargs) → Any

Plot energy bands with arrows signaling possible k –> k + q indipendent-particle transitions of energy omega_ev connecting occupied to empty states.

Parameters:

• omega_ev – Transition energy in eV.

• qpt – Q-point in reduced coordinates.

• atol_ev – Absolute tolerance for energy difference in eV

• atol_kdiff – Tolerance used to compare k-points.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• alpha – The alpha blending value, between 0 (transparent) and 1 (opaque)

• ax – matplotlib.axes.Axes or None if a new figure should be created.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

get_ejdos(spin, valence, conduction, method='gaussian', step=0.1, width=0.2, mesh=None) → Function1D

Compute the join density of states at q == 0.

\(\sum_{kbv} f_{vk} (1 - f_{ck}) \delta(\omega - E_{ck} + E_{vk})\)

Warning

The present implementation assumes an energy gap

Parameters:

• spin – Spin index.

• valence – Int or iterable with the valence indices.

• conduction – Int or iterable with the conduction indices.

• method (str) – String defining the integraion method.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• mesh – Frequency mesh to use. If None, the mesh is computed automatically from the eigenvalues.

Returns: abipy.core.func1d.Function1D object.

plot_ejdosvc(vrange, crange, method='gaussian', step=0.1, width=0.2, colormap='jet', cumulative=True, ax=None, alpha=0.7, fontsize=12, **kwargs) → Any

Plot the decomposition of the joint-density of States (JDOS).

Warning

The present implementation assumes an energy gap

Parameters:

• vrange – Int or Iterable with the indices of the valence bands to consider.

• crange – Int or Iterable with the indices of the conduction bands to consider.

• method – String defining the method.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• colormap – Color map. Have a look at the colormaps here and decide which one you like: http://matplotlib.sourceforge.net/examples/pylab_examples/show_colormaps.html

• cumulative – True for cumulative plots (default).

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• alpha – The alpha blending value, between 0 (transparent) and 1 (opaque)

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

apply_scissors(scissors)

Modify the band structure with the scissors operator.

Parameters:

scissors – An instance of Scissors.

Returns:

New instance of abipy.electrons.ebands.ElectronBands with modified energies.

plot(spin=None, band_range=None, klabels=None, e0='fermie', ax=None, ylims=None, points=None, with_gaps=False, max_phfreq=None, fontsize=8, **kwargs) → Any

Plot the electronic band structure with matplotlib.

Parameters:

• spin – Spin index. None to plot both spins.

• band_range – Tuple specifying the minimum and maximum band to plot (default: all bands are plotted)

• klabels – dictionary whose keys are tuple with the reduced coordinates of the k-points. The values are the labels. e.g. klabels = {(0.0,0.0,0.0): "$\Gamma$", (0.5,0,0):"L"}.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• points – Marker object with the position and the size of the marker. Used for plotting purpose e.g. QP energies, energy derivatives etc.

• with_gaps –

  True to add markers and arrows showing the fundamental and the direct gap. IMPORTANT: If the gaps are now showed correctly in a non-magnetic semiconductor,

  call ebands.set_fermie_to_vbm() to align the Fermi level at the top of the valence bands before executing `ebands.plot(). The Fermi energy stored in the object, indeed, comes from the GS calculation that produced the DEN file. If the k-mesh used for the GS and the CBM is e.g. at Gamma, the Fermi energy will be underestimated and a manual aligment is needed.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorption/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly(spin=None, band_range=None, klabels=None, e0='fermie', fig=None, rcd=None, ylims=None, points=None, with_gaps=False, max_phfreq=None, fontsize=12, **kwargs)

Plot the electronic band structure with plotly.

Parameters:

• spin – Spin index. None to plot both spins.

• band_range – Tuple specifying the minimum and maximum band to plot (default: all bands are plotted)

• klabels – dictionary whose keys are tuple with the reduced coordinates of the k-points. The values are the labels. e.g. klabels = {(0.0,0.0,0.0): "$\Gamma$", (0.5,0,0):"L"}.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• fig – plotly figure or None if a new figure should be created.

• rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• points – Marker object with the position and the size of the marker. Used for plotting purpose e.g. QP energies, energy derivatives.

• with_gaps – True to add markers and arrows showing the fundamental and the direct gap. IMPORTANT: If the gaps are now showed correctly in a non-magnetic semiconductor, call ebands.set_fermie_to_vbm() to align the Fermi level at the top of the valence bands before executing `ebands.plot(). The Fermi energy stored in the object, indeed, comes from the GS calculation that produced the DEN file. If the k-mesh used for the GS and the CBM is e.g. at Gamma, the Fermi energy will be underestimated and a manual aligment is needed.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorption/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• fontsize – fontsize for legends and titles

• kwargs – Passed to fig.add_scatter method.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_split(ylims_list: list, hspace: float = 0.1, ratio: float = 0.5, **kwargs) → Any

Plot electronic bands with broken y-axis. Based on: https://matplotlib.org/stable/gallery/subplots_axes_and_figures/broken_axis.html

Parameters:

• ylims_list – List of tuples. Each tuple defines the y-limits for the subplots.

• hspace – space between Axes.

• ratio – proportion of vertical to horizontal extent of the slanted line.

• kwargs – keyword arguments passed to self.plot method.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_scatter3d(band, spin=0, e0='fermie', colormap='jet', ax=None, **kwargs) → Any

Use matplotlib scatter3D to produce a scatter plot of the eigenvalues in 3D. The color of the points gives the energy of the state wrt to the Fermi level.

Parameters:

• band – Band index

• spin – Spin index.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0.

• colormap – Color map. Have a look at the colormaps here and decide which one you like: <http://matplotlib.sourceforge.net/examples/pylab_examples/show_colormaps.html>

• ax – matplotlib Axes3D or None if a new figure should be created.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

decorate_ax(ax, **kwargs) → None

Add k-labels, title and unit name to axis ax.

Parameters:

• title

• fontsize

• klabels

• klabel_size

decorate_plotly(fig, **kwargs) → None

Add q-labels and unit name to figure fig. Use units=”” to add k-labels without unit name.

Parameters:

• klabels

• klabel_size

• iax – An int, use iax=n to decorate the nth axis when the fig has subplots.

add_fundgap_span(ax_or_axlist, spin, span_dir='v', fontsize=8, **kwargs) → None

Show gap as filled area.

Parameters:

• ax_or_axlist

• spin

• spand_dir

get_e0(e0)

e0: Option used to define the zero of energy in the band structure plot. Possible values:

• fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie).

• Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV

• None: Don’t shift energies, equivalent to e0 = 0.

plot_ax(ax, e0, spin=None, band=None, **kwargs) → list

Helper function to plot the energies for (spin, band) on the axis ax with matplotlib.

Parameters:

• ax – matplotlib.axes.Axes.

• e0 – Option used to define the zero of energy in the band structure plot.

• spin – Spin index. If None, all spins are plotted.

• band – Band index, If None, all bands are plotted.

• kwargs – Passed to ax.plot

Return: matplotlib lines

plotly_traces(fig, e0, rcd=None, spin=None, band=None, showlegend=False, line_opts=None, **kwargs)

Helper function to plot the energies for (spin, band) on figure fig with plotly.

Parameters:

• fig – plotly.graph_objects.Figure.

• e0 – Option used to define the zero of energy in the band structure plot.

• rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the subplot in the grid.

• spin – Spin index. If None, all spins are plotted.

• band – Band index, If None, all bands are plotted.

• showlegend – Determines whether or not an item corresponding to this trace is shown in the legend.

• line_opts – Dict of linestyle options passed to |plotly.graph_objects.scatter.Line|

• kwargs – Passed to fig.add_scatter method.

plot_with_edos(edos, klabels=None, ax_list=None, e0='fermie', points=None, with_gaps=False, max_phfreq=None, ylims=None, width_ratios=(2, 1), **kwargs) → Any

Plot the band structure and the DOS with matplotlib.

Parameters:

• edos – An instance of abipy.electrons.ebands.ElectronDos.

• klabels – dictionary whose keys are tuple with the reduced coordinates of the k-points. The values are the labels. e.g. klabels = {(0.0,0.0,0.0): "$\Gamma$", (0.5,0,0): "L"}.

• ax_list – The axes for the band structure plot and the DOS plot. If ax_list is None, a new figure is created and the two axes are automatically generated.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  * ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See ``edos_fermie``.
  * ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
  *  Number e.g ``e0 = 0.5``: shift all eigenvalues to have zero energy at 0.5 eV
  *  None: Don't shift energies, equivalent to ``e0 = 0``
  

• points – Marker object with the position and the size of the marker. Used for plotting purpose e.g. QP energies, energy derivatives…

• with_gaps – True to add markers and arrows showing the fundamental and the direct gap.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorption/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• width_ratios – Defines the ratio between the band structure plot and the dos plot.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_with_edos(edos, klabels=None, fig=None, band_rcd=None, dos_rcd=None, e0='fermie', points=None, with_gaps=False, max_phfreq=None, ylims=None, width_ratios=(2, 1), **kwargs)

Plot the band structure and the DOS with plotly.

Parameters:

• edos – An instance of abipy.electrons.ebands.ElectronDos.

• klabels – dictionary whose keys are tuple with the reduced coordinates of the k-points. The values are the labels. e.g. klabels = {(0.0,0.0,0.0): "$\Gamma$", (0.5,0,0): "L"}.

• fig – The plotly.graph_objects.Figure with two distinct plots for the band structure plot and the DOS plot. If fig is None, a new figure is created.

• band_rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the band subplot in the grid.

• dos_rcd – PlotlyRowColDesc object used when fig is not None to specify the (row, col) of the dos subplot in the grid.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  * ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See ``edos_fermie``.
  * ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
  *  Number e.g ``e0 = 0.5``: shift all eigenvalues to have zero energy at 0.5 eV
  *  None: Don't shift energies, equivalent to ``e0 = 0``
  

• points – Marker object with the position and the size of the marker. Used for plotting purpose e.g. QP energies, energy derivatives…

• with_gaps – True to add markers and arrows showing the fundamental and the direct gap.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorption/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• width_ratios – Defines the ratio between the band structure plot and the dos plot.

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_lws_vs_e0(ax=None, e0='fermie', function=<function ElectronBands.<lambda>>, exchange_xy=False, xlims=None, ylims=None, fontsize=12, **kwargs) → Any

Plot electronic linewidths vs KS energy with matplotlib.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• function – Apply this function to the values before plotting

• exchange_xy – True to exchange x-y axis.

• xlims – Set the data limits for the x-axis or the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Set the data limits for the x-axis or the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize – fontsize for titles and legend.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

to_xmgrace(filepath: str) → None

Write xmgrace file with band structure energies and labels for high-symmetry k-points.

Parameters:

filepath – String with filename or stream.

get_ifermi_dense_bs(interpolation_factor, with_velocities, nworkers=1)

Use ifermi and BoltzTraP2 to interpolate KS energies (assumes ebands in the IBZ).

Parameters:

• interpolation_factor

• with_velocities – Interpolate velocities in the full BZ.

Note

Store results in per-instance cache via memoized_method.

get_ifermi_fs(interpolation_factor=8, mu=0.0, eref='fermie', wigner_seitz=True, calculate_dimensionality=False, with_velocities=False, nworkers=1)

Use ifermi package to visualize the (interpolated) Fermi surface. Requires netcdf file with energies in the IBZ. See also <https://fermisurfaces.github.io/IFermi/>

Parameters:

• interpolation_factor – The factor by which the band structure will be interpolated.

• mu – Energy offset from the reference energy determing by eref.

• eref – Defines the energy reference. Possible values: fermie, cbm, vbm. The energy of the isosurface is given by: eref + mu.

• wigner_seitz – Controls whether the cell is the Wigner-Seitz cell or the reciprocal unit cell parallelepiped.

• calculate_dimensionality

• with_velocities – Generate the Fermi surface and calculate the group velocity at the center of each triangular face.

Returns:

example:

r = ebands.get_ifermi_fs()
r.fs_plotter.get_plot(plot_type="plotly").show()

to_bxsf(filepath)

Export the full band structure to filepath in BXSF format suitable for the visualization of isosurfaces with xcrysden (xcrysden –bxsf FILE). Require k-points in IBZ and gamma-centered k-mesh.

get_ebands3d()

derivatives(spin, band, order=1, acc=4)

Compute the derivative of the eigenvalues wrt to k using finite difference.

Parameters:

• spin – Spin index

• band – Band index

• order

• acc

Returns:

get_effmass_analyzer()

” Return an instance of EffMassAnalyzer to compute effective masses with finite differences

get_effmass_line(spin, kpoint, band, acc=4)

Compute the effective masses along a k-line. Requires band energies on a k-path.

Parameters:

• spin – Spin index.

• kpoint – integer, list of fractional coordinates or abipy.core.kpoints.Kpoint object.

• band – Band index.

• acc – accuracy

interpolate(lpratio=5, knames=None, vertices_names=None, line_density=20, kmesh=None, is_shift=None, bstart=0, bstop=None, filter_params=None, verbose=0)

Interpolate energies in k-space along a k-path and, optionally, in the IBZ for DOS calculations. Note that the interpolation will likely fail if there are symmetrical k-points in the input set of k-points so it is highly recommended to call this method with energies obtained in the IBZ.

Parameters:

• lpratio – Ratio between the number of star functions and the number of ab-initio k-points. The default should be OK in many systems, larger values may be required for accurate derivatives.

• knames – List of strings with the k-point labels for the k-path. Has precedence over vertices_names.

• vertices_names – Used to specify the k-path for the interpolated band structure It is a list of tuple, each tuple is of the form (kfrac_coords, kname) where kfrac_coords are the reduced coordinates of the k-point and kname is a string with the name of the k-point. Each point represents a vertex of the k-path. line_density defines the density of the sampling. If None, the k-path is automatically generated according to the point group of the system.

• line_density – Number of points in the smallest segment of the k-path. If 0, use list of k-points given in vertices_names

• kmesh – Used to activate the interpolation on the homogeneous mesh for DOS (uses spglib API). kmesh is given by three integers and specifies mesh numbers along reciprocal primitive axis.

• is_shift – three integers (spglib API). When is_shift is not None, the kmesh is shifted along the axis in half of adjacent mesh points irrespective of the mesh numbers. None means unshifted mesh.

• bstart – Select the range of band to be used in the interpolation

• bstop – Select the range of band to be used in the interpolation

• filter_params – TO BE described.

• verbose – Verbosity level

Returns:

namedtuple with the following attributes:

ebands_kpath: |ElectronBands| with the interpolated band structure on the k-path.
ebands_kmesh: |ElectronBands| with the interpolated band structure on the k-mesh.
    None if ``kmesh`` is not given.
interpolator: |SkwInterpolator| object.

get_collinear_mag() → float

Calculates the total collinear magnetization in Bohr magneton as the difference between the spin up and spin down densities. Note that we assume an IBZ sampling.

Returns:

the total magnetization.

Return type:

float

Raises: ValueError if total magnetization is undefined e.g. nspinor 2.

class abipy.electrons.ebands.ElectronDos(mesh, spin_dos, nelect, fermie=None, spin_idos=None)

Bases: object

This object stores the electronic density of states. It is usually created by calling the get_edos method of abipy.electrons.ebands.ElectronBands.

to_string(verbose=0) → str

String representation.

classmethod as_edos(obj: Any, edos_kwargs: dict) → ElectronDos

Return an instance of abipy.electrons.ebands.ElectronDos from a generic object obj. Supports:

• instances of cls

• files (string) that can be open with abiopen and that provide an ebands attribute.

• objects providing an ebands or get_edos attribute

Parameters:

• edos_kwargs – optional dictionary with the options passed to get_edos to compute the electron DOS.

• cls. (Used when obj is not already an instance of)

dos_idos(spin=None)

Returns DOS and IDOS for given spin. Total DOS and IDOS if spin is None.

find_mu(nelect, spin=None) → float

Finds the chemical potential given the number of electrons.

up_minus_down()

Function1D with dos_up - dos_down

get_e0(e0) → float

e0: Option used to define the zero of energy in the band structure plot. Possible values:

• fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie).

• Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV

• None: Don’t shift energies, equivalent to e0=0

plot_ax(ax, e0, spin=None, what='dos', fact=1.0, normalize=False, exchange_xy=False, **kwargs) → list

Helper function to plot the DOS data on the matplotlib axis ax.

Parameters:

• ax – matplotlib.axes.Axes.

• e0 – Option used to define the zero of energy in the band structure plot.

• spin – selects the spin component, None for total DOS, IDOS.

• what – string selecting what will be plotted. “dos” for DOS, “idos” for IDOS

• fact – Multiplication factor for DOS/IDOS. Usually +-1 for spin DOS.

• normalize – True if values should be normalized to one.

• exchange_xy – True to exchange x-y axis.

• kwargs – Options passed to matplotlib ax.plot

Return: list of lines added to the axis ax.

plotly_traces(fig, e0, spin=None, what='dos', fact=1.0, exchange_xy=False, rcd=None, trace_name='', showlegend=False, line_opts=None, **kwargs)

Helper function to plot the DOS data on the fig with plotly.

Parameters:

• fig – plotly.graph_objects.Figure.

• e0 – Option used to define the zero of energy in the band structure plot.

• spin – selects the spin component, None for total DOS, IDOS.

• what – string selecting what will be plotted. “dos” for DOS, “idos” for IDOS

• fact – Multiplication factor for DOS/IDOS. Usually +-1 for spin DOS

• exchange_xy – True to exchange x-y axis.

• rcd – PlotlyRowColDesc object used to specify the (row, col) of the subplot in the grid.

• trace_name – Name of the trace.

• showlegend – Determines whether or not an item corresponding to this trace is shown in the legend.

• line_opts – Dict of linestyle options passed to |plotly.graph_objects.scatter.Line|

• kwargs – Options passed to fig.add_scatter method.

plot(e0='fermie', spin=None, ax=None, exchange_xy=False, xlims=None, ylims=None, **kwargs) → Any

Plot electronic DOS with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0.

• spin – Selects the spin component, None if total DOS is wanted.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• exchange_xy – True to exchange x-y axis.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Set data limits for the y-axis.

• kwargs – options passed to ax.plot.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly(e0='fermie', spin=None, fig=None, exchange_xy=False, xlims=None, ylims=None, trace_name='', showlegend=False, **kwargs)

Plot electronic DOS with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0.

• spin – Selects the spin component, None if total DOS is wanted.

• fig – plotly.graph_objects.Figure.

• exchange_xy – True to exchange x-y axis.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right).

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right).

• trace_name – Name of the trace.

• showlegend – Determines whether or not an item corresponding to this trace is shown in the legend.

• kwargs – Options passed to fig.add_scatter method.

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_dos_idos(e0='fermie', ax_list=None, xlims=None, height_ratios=(1, 2), **kwargs) → Any

Plot electronic DOS and Integrated DOS on two different subplots with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0.

• ax_list – The axes for the DOS and IDOS plot. If ax_list is None, a new figure is created and the two axes are automatically generated.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• height_ratios

• kwargs – options passed to plot_ax

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_dos_idos(e0='fermie', fig=None, xlims=None, height_ratios=(1, 2), **kwargs)

Plot electronic DOS and Integrated DOS on two different subplots with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0.

• fig – The plotly.graph_objects.Figure with two distinct plots for the DOS and IDOS plot. If fig is None, a new figure is created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right).

• height_ratios

• kwargs – Options passed to plotly_traces method.

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_up_minus_down(e0='fermie', ax=None, xlims=None, **kwargs) → Any

Plot Dos_up - Dow_down with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• kwargs – options passed to ax.plot.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_up_minus_down(e0='fermie', fig=None, xlims=None, **kwargs)

Plot Dos_up - Dow_down with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fig – plotly.graph_objects.Figure or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right).

• kwargs – Options passed to fig.add_scatter method.

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

to_pymatgen()

Return a pymatgen DOS object from an Abipy abipy.electrons.ebands.ElectronDos object.

abipy.electrons.ebands.dataframe_from_ebands(ebands_objects, index=None, with_spglib=True) → DataFrame

Build a pandas dataframe with the most important results available in a list of band structures.

Parameters:

• ebands_objects – List of objects that can be converted to structure. Support netcdf filenames or abipy.electrons.ebands.ElectronBands objects See ElectronBands.as_ebands for the complete list.

• index – Index of the dataframe.

• with_spglib – If True, spglib is invoked to get the spacegroup symbol and number.

Return: pandas.DataFrame

class abipy.electrons.ebands.ElectronBandsPlotter(key_ebands=None, key_edos=None, edos_kwargs=None)

Bases: NotebookWriter

Class for plotting electronic band structure and DOSes. Supports plots on the same graph or separated plots.

Usage example:

plotter = ElectronBandsPlotter()
plotter.add_ebands("foo-label", "foo_GSR.nc")
plotter.add_ebands("bar-label", "bar_WFK.nc")
fig = plotter.gridplot()

Dictionary with the mapping label –> edos.

Inheritance Diagram

add_plotter(other) → ElectronBandsPlotter

Merge two plotters, return new plotter.

to_string(func=<class 'str'>, verbose=0) → str

String representation.

get_ebands_frame(with_spglib=True) → DataFrame

Build a pandas.DataFrame with the most important results available in the band structures. Useful to analyze band-gaps.

property ebands_list: List[ElectronBands]

“List of abipy.electrons.ebands.ElectronBands objects.

property edoses_list: List[ElectronDos]

“List of abipy.electrons.ebands.ElectronDos objects.

iter_lineopt()

Generates matplotlib linestyles.

iter_lineopt_plotly()

Generates plotly linestyles.

add_ebands(label, bands, edos=None, edos_kwargs=None) → None

Adds a band structure and optionally an edos to the plotter.

Parameters:

• label – label for the bands. Must be unique.

• bands – abipy.electrons.ebands.ElectronBands object.

• edos – abipy.electrons.ebands.ElectronDos object.

• edos_kwargs – optional dictionary with the options passed to get_edos to compute the electron DOS. Used only if edos is not None and it’s not an abipy.electrons.ebands.ElectronDos instance.

bands_statdiff(ref=0) → str

Compare the reference bands with index ref with the other bands stored in the plotter.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

yield_plotly_figs(**kwargs)

This function generates a predefined list of plotly figures with minimal input from the user.

combiplot(e0='fermie', ylims=None, width_ratios=(2, 1), fontsize=8, linestyle_dict=None, **kwargs) → Any

Plot the band structure and the DOS on the same figure with matplotlib. Use gridplot to plot band structures on different figures.

Parameters:

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values::

  • fermie: shift all eigenvalues to have zero energy at the Fermi energy (ebands.fermie)

    Note that, by default, the Fermi energy is taken from the band structure object i.e. the Fermi energy computed at the end of the SCF file that produced the density. This should be ok in semiconductors. In metals, however, a better value of the Fermi energy can be obtained from the DOS provided that the k-sampling for the DOS is much denser than the one used to compute the density. See edos_fermie.

  • edos_fermie: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.

    Available only if plotter contains dos objects.

  • Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV

  • None: Don’t shift energies, equivalent to e0=0

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• width_ratios – Defines the ratio between the band structure plot and the dos plot. Used when there are DOS stored in the plotter.

• fontsize – fontsize for legend.

• linestyle_dict – Dictionary mapping labels to matplotlib linestyle options.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot(e0='fermie', ylims=None, width_ratios=(2, 1), fontsize=8, linestyle_dict=None, **kwargs) → Any

Plot the band structure and the DOS on the same figure with matplotlib. Use gridplot to plot band structures on different figures.

Parameters:

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values::

  • fermie: shift all eigenvalues to have zero energy at the Fermi energy (ebands.fermie)

    Note that, by default, the Fermi energy is taken from the band structure object i.e. the Fermi energy computed at the end of the SCF file that produced the density. This should be ok in semiconductors. In metals, however, a better value of the Fermi energy can be obtained from the DOS provided that the k-sampling for the DOS is much denser than the one used to compute the density. See edos_fermie.

  • edos_fermie: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.

    Available only if plotter contains dos objects.

  • Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV

  • None: Don’t shift energies, equivalent to e0=0

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• width_ratios – Defines the ratio between the band structure plot and the dos plot. Used when there are DOS stored in the plotter.

• fontsize – fontsize for legend.

• linestyle_dict – Dictionary mapping labels to matplotlib linestyle options.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

combiplotly(e0='fermie', ylims=None, width_ratios=(2, 1), fontsize=12, linestyle_dict=None, **kwargs)

Plot the band structure and the DOS on the same figure with plotly. Use gridplotly to plot band structures on different figures.

Parameters:

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values::

  • fermie: shift all eigenvalues to have zero energy at the Fermi energy (ebands.fermie)

    Note that, by default, the Fermi energy is taken from the band structure object i.e. the Fermi energy computed at the end of the SCF file that produced the density. This should be ok in semiconductors. In metals, however, a better value of the Fermi energy can be obtained from the DOS provided that the k-sampling for the DOS is much denser than the one used to compute the density. See edos_fermie.

  • edos_fermie: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.

    Available only if plotter contains dos objects.

  • Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV

  • None: Don’t shift energies, equivalent to e0=0

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• width_ratios – Defines the ratio between the band structure plot and the dos plot. Used when there are DOS stored in the plotter.

• fontsize – fontsize for titles and legend.

• linestyle_dict – Dictionary mapping labels to linestyle options passed to |plotly.graph_objects.scatter|.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plotly(e0='fermie', ylims=None, width_ratios=(2, 1), fontsize=12, linestyle_dict=None, **kwargs)

Plot the band structure and the DOS on the same figure with plotly. Use gridplotly to plot band structures on different figures.

Parameters:

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values::

  • fermie: shift all eigenvalues to have zero energy at the Fermi energy (ebands.fermie)

    Note that, by default, the Fermi energy is taken from the band structure object i.e. the Fermi energy computed at the end of the SCF file that produced the density. This should be ok in semiconductors. In metals, however, a better value of the Fermi energy can be obtained from the DOS provided that the k-sampling for the DOS is much denser than the one used to compute the density. See edos_fermie.

  • edos_fermie: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.

    Available only if plotter contains dos objects.

  • Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV

  • None: Don’t shift energies, equivalent to e0=0

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• width_ratios – Defines the ratio between the band structure plot and the dos plot. Used when there are DOS stored in the plotter.

• fontsize – fontsize for titles and legend.

• linestyle_dict – Dictionary mapping labels to linestyle options passed to |plotly.graph_objects.scatter|.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

gridplot(e0='fermie', with_dos=True, with_gaps=False, max_phfreq=None, ylims=None, fontsize=8, **kwargs) → Any

Plot multiple electron bandstructures and optionally DOSes on a grid with matplotlib.

Parameters:

• eb_objects – List of objects from which the band structures are extracted. Each item in eb_objects is either a string with the path of the netcdf file, or one of the abipy object with an ebands attribute or a abipy.electrons.ebands.ElectronBands object.

• edos_objects – List of objects from which the electron DOSes are extracted. Accept filepaths or abipy.electrons.ebands.ElectronDos objects. If edos_objects is not None, each subplot in the grid contains a band structure with DOS else a simple band structure plot.

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  - ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See `edos_fermie`.
  - ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
     Available only if edos_objects is not None
  -  Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV
  -  None: Don't shift energies, equivalent to e0=0
  

• with_dos – True if DOS should be printed.

• with_gaps – True to add markers and arrows showing the fundamental and the direct gap.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorptions/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• ylims – Set the data limits for the y-axis. Accept tuple e.g. `(left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize – fontsize for subtitles.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

gridplotly(e0='fermie', with_dos=True, with_gaps=False, max_phfreq=None, ylims=None, fontsize=12, **kwargs)

Plot multiple electron bandstructures and optionally DOSes on a grid with plotly.

Parameters:

• eb_objects – List of objects from which the band structures are extracted. Each item in eb_objects is either a string with the path of the netcdf file, or one of the abipy object with an ebands attribute or a abipy.electrons.ebands.ElectronBands object.

• edos_objects – List of objects from which the electron DOSes are extracted. Accept filepaths or abipy.electrons.ebands.ElectronDos objects. If edos_objects is not None, each subplot in the grid contains a band structure with DOS else a simple band structure plot.

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  - ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See `edos_fermie`.
  - ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
     Available only if edos_objects is not None
  -  Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV
  -  None: Don't shift energies, equivalent to e0=0
  

• with_dos – True if DOS should be printed.

• with_gaps – True to add markers and arrows showing the fundamental and the direct gap.

• max_phfreq – Max phonon frequency in eV to activate scatterplot showing possible phonon absorptions/emission processes based on energy-conservation alone. All final states whose energy is within +- max_phfreq of the initial state are included. By default, the four electronic states defining the fundamental and the direct gaps are considered as initial state (not available for metals).

• ylims – Set the data limits for the y-axis. Accept tuple e.g. `(left, right)

• fontsize – fontsize for subtitles.

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

boxplot(e0='fermie', brange=None, swarm=False, fontsize=8, **kwargs) → Any

Use seaborn to draw a box plot to show distributions of eigenvalues with respect to the band index. Band structures are drawn on different subplots.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• brange – Only bands such as brange[0] <= band_index < brange[1] are included in the plot.

• swarm – True to show the datapoints on top of the boxes

• fontsize – Fontsize for title.

• kwargs – Keyword arguments passed to seaborn boxplot.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

combiboxplot(e0='fermie', brange=None, swarm=False, ax=None, **kwargs) → Any

Use seaborn to draw a box plot comparing the distributions of the eigenvalues Band structures are drawn on the same plot.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• brange – Only bands such as brange[0] <= band_index < brange[1] are included in the plot.

• swarm – True to show the datapoints on top of the boxes

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• kwargs – Keyword arguments passed to seaborn boxplot.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_band_edges(e0='fermie', epad_ev=1.0, set_fermie_to_vbm=True, colormap='viridis', fontsize=8, **kwargs) → Any

Plot the band edges for electrons and holes on two separated plots for all ebands in ebands_dict. Useful for comparing band structures obtained with/without SOC or bands obtained with different settings.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• epad_ev – Add this energy window in eV above VBM and below CBM.

• set_fermie_to_vbm – True if Fermi energy should be recomputed and fixed at max occupied energy level.

• colormap – matplotlib colormap.

• fontsize – legend and title fontsize.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

animate(e0='fermie', interval=500, savefile=None, width_ratios=(2, 1), show=True)

Use matplotlib to animate a list of band structure plots (with or without DOS).

Parameters:

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  * ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     See `edos_fermie`.
  * ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
  *  Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV
  *  None: Don't shift energies, equivalent to e0=0
  

• interval – draws a new frame every interval milliseconds.

• savefile – Use e.g. ‘myanimation.mp4’ to save the animation in mp4 format.

• width_ratios – Defines the ratio between the band structure plot and the dos plot. Used when there are DOS stored in the plotter.

• show – True if the animation should be shown immediately

Returns: Animation object.

Note

It would be nice to animate the title of the plot, unfortunately this feature is not available in the present version of matplotlib. See: http://stackoverflow.com/questions/17558096/animated-title-in-matplotlib

ipw_select_plot()

Return an ipython widget with controllers to select the plot.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.ebands.ElectronDosPlotter(key_edos=None, edos_kwargs=None)

Bases: NotebookWriter

Class for plotting multiple electronic DOSes.

Usage example:

plotter = ElectronDosPlotter()
plotter.add_edos("foo dos", "foo.nc")
plotter.add_edos("bar dos", "bar.nc")
fig = plotter.gridplot()

property edos_list: List[ElectronDos]

List of DOSes

add_edos(label, edos, edos_kwargs=None) → None

Adds a DOS for plotting.

Parameters:

• label – label for the DOS. Must be unique.

• edos – abipy.electrons.ebands.ElectronDos object.

• edos_kwargs – optional dictionary with the options passed to get_edos to compute the electron DOS. Used only if edos is not an ElectronDos instance.

combiplot(what_list='dos', spin_mode='automatic', e0='fermie', ax_list=None, xlims=None, fontsize=8, **kwargs) → Any

Plot the the DOSes on the same figure with matplotlib. Use gridplot to plot DOSes on different figures with matplotlib.

Parameters:

• what_list – Selects quantities to plot e.g. [“dos”, “idos”] to plot DOS and integrated DOS. “dos” for DOS only and “idos” for IDOS only

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• ax_list – List of matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize (int) – fontsize for legend

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot(what_list='dos', spin_mode='automatic', e0='fermie', ax_list=None, xlims=None, fontsize=8, **kwargs) → Any

Plot the the DOSes on the same figure with matplotlib. Use gridplot to plot DOSes on different figures with matplotlib.

Parameters:

• what_list – Selects quantities to plot e.g. [“dos”, “idos”] to plot DOS and integrated DOS. “dos” for DOS only and “idos” for IDOS only

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• ax_list – List of matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize (int) – fontsize for legend

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

combiplotly(what_list='dos', spin_mode='automatic', e0='fermie', ax_list=None, xlims=None, fontsize=12, **kwargs)

Plot the the DOSes on the same figure with plotly. Use gridplotly to plot DOSes on different figures with plotly.

Parameters:

• what_list – Selects quantities to plot e.g. [“dos”, “idos”] to plot DOS and integrated DOS. “dos” for DOS only and “idos” for IDOS only

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• ax_list – List of matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right)

• fontsize (int) – fontsize for legend

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plotly(what_list='dos', spin_mode='automatic', e0='fermie', ax_list=None, xlims=None, fontsize=12, **kwargs)

Plot the the DOSes on the same figure with plotly. Use gridplotly to plot DOSes on different figures with plotly.

Parameters:

• what_list – Selects quantities to plot e.g. [“dos”, “idos”] to plot DOS and integrated DOS. “dos” for DOS only and “idos” for IDOS only

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• ax_list – List of matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right)

• fontsize (int) – fontsize for legend

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

gridplot(what='dos', spin_mode='automatic', e0='fermie', sharex=True, sharey=True, xlims=None, fontsize=8, **kwargs) → Any

Plot multiple DOSes on a grid with matplotlib.

Parameters:

• what – “dos” to plot DOS, “idos” for integrated DOS.

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  - ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See ``edos_fermie``.
  - ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
     Available only if edos_objects is not None
  -  Number e.g ``e0 = 0.5``: shift all eigenvalues to have zero energy at 0.5 eV
  -  None: Don't shift energies, equivalent to ``e0 = 0``.
  

• sharex – True if x (y) axis should be shared.

• sharey – True if x (y) axis should be shared.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize – Axis_label and subtitle fontsize.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

gridplotly(what='dos', spin_mode='automatic', e0='fermie', sharex=True, sharey=True, xlims=None, fontsize=12, **kwargs)

Plot multiple DOSes on a grid with plotly.

Parameters:

• what – “dos” to plot DOS, “idos” for integrated DOS.

• spin_mode – “total” for total (I)DOS, “resolved” for plotting individual contributions. Meaningful only if nsppol == 2. “automatic” to use “resolved” if at least one DOS is polarized.

• e0 –

  Option used to define the zero of energy in the band structure plot. Possible values:

  - ``fermie``: shift all eigenvalues and the DOS to have zero energy at the Fermi energy.
     Note that, by default, the Fermi energy is taken from the band structure object
     i.e. the Fermi energy computed at the end of the SCF file that produced the density.
     This should be ok in semiconductors. In metals, however, a better value of the Fermi energy
     can be obtained from the DOS provided that the k-sampling for the DOS is much denser than
     the one used to compute the density. See ``edos_fermie``.
  - ``edos_fermie``: Use the Fermi energy computed from the DOS to define the zero of energy in both subplots.
     Available only if edos_objects is not None
  -  Number e.g ``e0 = 0.5``: shift all eigenvalues to have zero energy at 0.5 eV
  -  None: Don't shift energies, equivalent to ``e0 = 0``.
  

• sharex – True if x (y) axis should be shared.

• sharey – True if x (y) axis should be shared.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right)

• fontsize – Axis_label and subtitle fontsize.

Return: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

ipw_select_plot()

Return an ipython widget with controllers to select the plot.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

effmass_analyzer Module

This module provides objects to compute electronic effective masses via finite differences starting from a GSR file with KS energies defined along segments passing through the k-point of interest.

class abipy.electrons.effmass_analyzer.EffMassAnalyzer(ebands: ElectronBands, copy: bool = True)

Bases: Has_Structure, Has_ElectronBands

This objects provides a high-level API to compute electronic effective masses with finite differences starting from a netcdf file with an abipy.electrons.ebands.ElectronBands object.

Usage example:

from abipy.electrons.effmass_analyzer import EffMassAnalyzer
emana = EffMassAnalyzer.from_file("out_GSR.nc")
print(emana)

emana.select_vbm()
emana.summarize()
emana.plot_emass()

# Alternatively, one can use:
emana.select_cbm()
emana.select_band_edges()
emana.summarize()
emana.plot_emass()

or the most flexible API:

emana.select_kpoint_band(kpoint=[0, 0, 0], band=3)
emana.summarize()
emana.plot_emass()

Inheritance Diagram

classmethod from_file(filepath: str) → EffMassAnalyzer

Initialize the object from a netcdf file providing an abipy.electrons.ebands.ElectronBands object, usually a GSR file.

to_string(verbose: int = 0) → str

Human-readable string with info such as band gaps, position of HOMO, LOMO, etc.

Parameters:

verbose – Verbosity level.

property structure: Structure

abipy.core.structure.Structure object.

property ebands: ElectronBands

abipy.electrons.ebands.ElectronBands object.

select_kpoint_band(kpoint, band: int, spin: int = 0, degtol_ev: float = 0.001) → int

Construct line segments based on the k-point kpoint and the band index band. This is the most flexible interface and allows one to include extra bands by increasing the value of degtol_ev.

Parameters:

• kpoint – Fractional coordinates or abipy.core.kpoints.Kpoint object or index of the k-point.

• band – Band index.

• spin – Spin index.

• degtol_ev – Include all bands at this k-point whose energy differ from the one at (kpoint, band) less that degtol_ev in eV.

Return: Number of segments.

select_cbm(spin: int = 0, degtol_ev: float = 0.001) → int

Select the conduction band minimum for the given spin. Return: Number of segments.

select_vbm(spin: int = 0, degtol_ev: float = 0.001) → int

Select the valence band maximum for the given spin, Return: Number of segments.

select_band_edges(spin: int = 0, degtol_ev: float = 0.001) → int

Select conduction band minimum and valence band maximum. Return: Number of segments.

summarize(acc_list=None) → None

Compute effective masses with different accuracies and print results in tabular format. Useful to understand if results are sensitive to the number of points in the finite difference. Note however that numerical differentiation is performed with the same delta_k step.

plot_emass(acc=4, units='eV', sharey=False, fontsize=6, colormap='viridis', verbose=0, **kwargs) → Any

Plot electronic dispersion and quadratic approximant based on the effective masses computed along each segment.

Parameters:

• acc – Accuracy of finite diff.

• units – Units for band energies. “eV” or “meV”.

• sharey – True if y axis (energies) should be shared.

• fontsize – legend and title fontsize.

• colormap – matplotlib colormap

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_all_segments(ax=None, colormap='viridis', fontsize=8, **kwargs) → Any

Parameters:

• colormap – matplotlib colormap

• fontsize – legend and title fontsize.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

class abipy.electrons.effmass_analyzer.Segment(ik: int, spin: int, line, band_inds: List[int], ebands: ElectronBands)

Bases: object

This object stores the KS energies along a particular segment in k-space passing through k0. Provides methods to compute effective masses at k0 via finite differences.

to_string(verbose: int = 0) → str

String representation.

get_fd_emass_d2(enes_kline, acc: int) → tuple

get_dataframe_with_accuracies(acc_list=None) → DataFrame

Build and return a pandas.DataFrame with the effective masses computed with different accuracies (npts)

plot_emass(acc: int = 4, units='eV', ax=None, fontsize: int = 8, colormap: str = 'viridis', **kwargs) → Any

Plot band dispersion and quadratic approximation.

Parameters:

• acc

• units – Units for band energies. “eV” or “meV”.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – legend and title fontsize.

• colormap – matplotlib colormap

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

fatbands Module

Classes for the analysis of electronic fatbands and projected DOSes.

abipy.electrons.fatbands.gaussians_dos(dos, mesh, width, values, energies, weights)

class abipy.electrons.fatbands.FatBandsFile(filepath: str)

Bases: AbinitNcFile, Has_Header, Has_Structure, Has_ElectronBands, NotebookWriter

Provides methods to analyze the data stored in the FATBANDS.nc file.

Usage example:

with abiopen("out_FATBANDS.nc") as fb:
    print(fb.structure)
    fb.plot_fatbands_lview()

Alternatively, one can use the abiopen.py script to open the file in an ipython notebook with:

abiopen.py out_FATBANDS.nc -nb

Inheritance Diagram

l2color = {0: 'red', 1: 'blue', 2: 'green', 3: 'yellow', 4: 'orange'}

l2tex = {0: '$l=s$', 1: '$l=p$', 2: '$l=d$', 3: '$l=f$', 4: '$l=g$'}

marker_spin = {0: '^', 1: 'v'}

marker_spin_plotly = {0: 5, 1: 6}

spin2tex = {0: '$\\sigma=\\uparrow$', 1: '$\\sigma=\\downarrow$'}

spinors2tex = {'down-down': '$\\downarrow,\\downarrow$', 'down-up': '$\\downarrow,\\uparrow$', 'sigma_x': '$\\sigma_{x}$', 'sigma_y': '$\\sigma_{y}$', 'sigma_z': '$\\sigma_{z}$', 'up-down': '$\\uparrow,\\downarrow$', 'up-up': '$\\uparrow,\\uparrow$'}

spinors2color = {'down-down': 'yellow', 'down-up': 'violet', 'sigma_x': 'green', 'sigma_y': 'blue', 'sigma_z': 'red', 'up-down': 'brown', 'up-up': 'black'}

alpha = 0.6

marker_size = 3.0

linewidth = 0.1

linecolor = 'grey'

classmethod from_file(filepath: str) → FatBandsFile

Initialize the object from a netcdf file

wal_sbk()

numpy.ndarray of shape [natom, mbesslang, nsppol, mband, nkpt] with the L-contributions. Present only if prtdos == 3.

walm_sbk()

numpy.ndarray of shape [natom, mbesslang**2, nsppol, mband, nkpt] with the LM-contribution. Present only if prtdos == 3 and prtdosm != 0

property ebands: ElectronBands

abipy.electrons.ebands.ElectronBands object.

property structure: Structure

abipy.core.structure.Structure object.

params()

dict with parameters that might be subject to convergence studies.

close() → None

Called at the end of the with context manager.

to_string(verbose: int = 0) → str

String representation.

get_wl_atom(iatom, spin=None, band=None)

Return the l-dependent DOS weights for atom index iatom. The weights are summed over m. If spin and band are not specified, the method returns the weights for all spin and bands else the contribution for (spin, band)

get_wl_symbol(symbol, spin=None, band=None)

Return the l-dependent DOS weights for a given type specified in terms of the chemical symbol symbol. The weights are summed over m and over all atoms of the same type. If spin and band are not specified, the method returns the weights for all spins and bands else the contribution for (spin, band).

get_w_symbol(symbol, spin=None, band=None)

Return the DOS weights for a given type specified in terms of the chemical symbol symbol. The weights are summed over m and lmax[symbol] and over all atoms of the same type. If spin and band are not specified, the method returns the weights for all spins and bands else the contribution for (spin, band).

get_spilling(spin=None, band=None)

Return the spilling parameter If spin and band are not specified, the method returns the spilling for all states as a [nsppol, mband, nkpt] numpy array else the spilling for (spin, band) with shape [nkpt].

eb_plotax_kwargs(spin)

Dictionary with the options passed to ebands.plot_ax when plotting a band line with spin index spin. Subclasses can redefine the implementation to customize the plots.

eb_plotly_kwargs(spin)

Dictionary with the options passed to ebands.plot_ax when plotting a band line with spin index spin. Subclasses can redefine the implementation to customize the plots.

plot_fatbands_siteview(e0='fermie', view='inequivalent', fact=1.0, fontsize=12, ylims=None, blist=None, **kwargs) → Any

Plot fatbands for each atom in the unit cell. By default, only the inequivalent atoms are shown.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• view – “inequivalent”, “all”

• fact – float used to scale the stripe size.

• fontsize – fontsize for titles and legend

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• blist – List of band indices for the fatband plot. If None, all bands are included

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_fatbands_lview(e0='fermie', fact=1.0, ax_mat=None, lmin=0, lmax=None, ylims=None, blist=None, fontsize=12, **kwargs) → Any

Plot the electronic fatbands grouped by L with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• ax_mat – Matrix of axes, if None a new figure is produced.

• lmin – Minimum L included in plot.

• lmax – Maximum L included in plot. None means full set available on file.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• blist – List of band indices for the fatband plot. If None, all bands are included

• fontsize – Legend fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_fatbands_lview(e0='fermie', fact=1.0, fig=None, lmax=None, ylims=None, blist=None, fontsize=12, band_and_dos=0, **kwargs)

Plot the electronic fatbands grouped by L with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• fig – The fig to plot on. None if a new figure should be created.

• lmax – Maximum L included in plot. None means full set available on file.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• blist – List of band indices for the fatband plot. If None, all bands are included

• fontsize – Legend and subtitle fontsize.

• band_and_dos – Define if both band and dos will be plotted on the same fig. If 0 (default), only plot band on the created figure (when fig==None); If 1, plot band on odd_col of fig

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_fatbands_mview(iatom, e0='fermie', fact=1.0, lmax=None, ylims=None, blist=None, **kwargs) → Any

Plot the electronic fatbands grouped by LM.

Parameters:

• iatom – Index of the atom in the structure.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• lmax – Maximum L included in plot. None means full set available on file.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• blist – List of band indices for the fatband plot. If None, all bands are included

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_fatbands_typeview(e0='fermie', fact=1.0, lmax=None, l_list=None, ax_mat=None, ylims=None, blist=None, fontsize=8, **kwargs) → Any

Plot the electronic fatbands grouped by atomic type with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• lmax – Maximum L included in plot. None means full set available on file.

• l_list – List of L values to plot. None to plot all L up to lmax.

• ax_mat – Matrix of axis. None if a new figure should be created.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• blist – List of band indices for the fatband plot. If None, all bands are included

• fontsize – Legend fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_fatbands_typeview(e0='fermie', fact=1.0, lmax=None, fig=None, ylims=None, blist=None, fontsize=12, band_and_dos=0, **kwargs)

Plot the electronic fatbands grouped by atomic type with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• lmax – Maximum L included in plot. None means full set available on file.

• fig – The fig to plot on. None if a new figure should be created.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

• blist – List of band indices for the fatband plot. If None, all bands are included

• fontsize – Legend and subtitle fontsize.

• band_and_dos – Define if both band and dos will be plotted on the same fig. If 0(default), only plot band on the created figure (when fig==None); If 1, plot band on odd_col of fig

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_spilling(e0='fermie', fact=1.0, ax_list=None, ylims=None, blist=None, **kwargs) → Any

Plot the electronic fatbands

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• ax_list – List of matplotlib axes for plot. If None, new figure is produced

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• blist – List of band indices for the fatband plot. If None, all bands are included

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

get_dos_integrator(method, step, width)

FatBandsFile can use differerent integrators that are cached in self._cached_dos_integrators

plot_pjdos_lview(e0='fermie', lmax=None, method='gaussian', step=0.1, width=0.2, stacked=True, combined_spins=True, ax_mat=None, exchange_xy=False, with_info=True, with_spin_sign=True, xlims=None, ylims=None, fontsize=8, **kwargs) → Any

Plot the PJ-DOS on a linear mesh with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• lmax – Maximum L included in plot. None means full set available on file.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• stacked – True if DOS partial contributions should be stacked on top of each other.

• combined_spins – Define how up/down DOS components should be plotted when nsppol==2. If True, up/down DOSes are plotted on the same figure (positive values for up, negative values for down component) If False, up/down components are plotted on different axes.

• ax_mat

• exchange_xy – True if the dos should be plotted on the x axis instead of y.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Same meaning as xlims but for the y-axis

• fontsize – Legend and subtitle fontsize

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_pjdos_lview(e0='fermie', lmax=None, method='gaussian', step=0.1, width=0.2, stacked=True, combined_spins=True, fig=None, exchange_xy=False, with_info=True, with_spin_sign=True, xlims=None, ylims=None, fontsize=12, band_and_dos=0, **kwargs)

Plot the PJ-DOS on a linear mesh with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• lmax – Maximum L included in plot. None means full set available on file.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• stacked – True if DOS partial contributions should be stacked on top of each other.

• combined_spins – Define how up/down DOS components should be plotted when nsppol==2. If True, up/down DOSes are plotted on the same figure (positive values for up, negative values for down component) If False, up/down components are plotted on different axes.

• fig – The fig to plot on. None if a new figure should be created.

• exchange_xy – True if the dos should be plotted on the x axis instead of y.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right)

• ylims – Same meaning as xlims but for the y-axis

• fontsize – Legend and subtitle fontsize.

• band_and_dos – Define if both band and dos will be plotted on the same fig. If 0(default), only plot dos on the created figure (when fig==None); If 1, plot dos on even_col of fig

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_pjdos_typeview(e0='fermie', lmax=None, l_list=None, method='gaussian', step=0.1, width=0.2, stacked=True, combined_spins=True, ax_mat=None, exchange_xy=False, with_info=True, with_spin_sign=True, xlims=None, ylims=None, fontsize=8, **kwargs) → Any

Plot the PJ-DOS on a linear mesh with matplotlib.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• lmax – Maximum L included in plot. None means full set available on file.

• l_list – List of L values to plot. None to plot all L up to lmax.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• stacked – True if DOS partial contributions should be stacked on top of each other.

• combined_spins – Define how up/down DOS components should be plotted when nsppol==2. If True, up/down DOSes are plotted on the same figure (positive values for up, negative values for down component) If False, up/down components are plotted on different axes.

• ax_mat

• exchange_xy – True if the dos should be plotted on the x axis instead of y.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• ylims – Same meaning as xlims but for the y-axis

• fontsize – Legend and subtitle fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_pjdos_typeview(e0='fermie', lmax=None, method='gaussian', step=0.1, width=0.2, stacked=True, combined_spins=True, fig=None, exchange_xy=False, with_info=True, with_spin_sign=True, xlims=None, ylims=None, fontsize=12, band_and_dos=0, **kwargs)

Plot the PJ-DOS on a linear mesh with plotly.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• lmax – Maximum L included in plot. None means full set available on file.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• stacked – True if DOS partial contributions should be stacked on top of each other.

• combined_spins – Define how up/down DOS components should be plotted when nsppol==2. If True, up/down DOSes are plotted on the same figure (positive values for up, negative values for down component) If False, up/down components are plotted on different axes.

• fig – The fig to plot on. None if a new figure should be created.

• exchange_xy – True if the dos should be plotted on the x axis instead of y.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right)

• ylims – Same meaning as xlims but for the y-axis

• fontsize – Legend and subtitle fontsize.

• band_and_dos – Define if both band and dos will be plotted on the same fig. If 0(default), only plot dos on the created figure (when fig==None); If 1, plot dos on even_col of fig

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_fatbands_with_pjdos(e0='fermie', fact=1.0, lmax=None, blist=None, view='type', pjdosfile=None, edos_kwargs=None, stacked=True, width_ratios=(2, 1), fontsize=8, ylims=None, **kwargs) → Any

Compute the fatbands and the PJDOS on the same figure with matplotlib, a.k.a the Sistine Chapel.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• lmax – Maximum L included in plot. None means full set available on file.

• blist – List of band indices for the fatband plot. If None, all bands are included

• pjdosfile – FATBANDS file used to compute the PJDOS. If None, the PJDOS is taken from self.

• edos_kwargs

• stacked – True if DOS partial contributions should be stacked on top of each other.

• width_ratios – Defines the ratio between the band structure plot and the dos plot.

• fontsize – Legend fontsize.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plotly_fatbands_with_pjdos(e0='fermie', fact=1.0, lmax=None, blist=None, view='type', pjdosfile=None, edos_kwargs=None, stacked=True, width_ratios=(2, 1), fontsize=12, ylims=None, **kwargs)

Compute the fatbands and the PJDOS on the same figure with plotly, a.k.a the Sistine Chapel.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy. - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – float used to scale the stripe size.

• lmax – Maximum L included in plot. None means full set available on file.

• blist – List of band indices for the fatband plot. If None, all bands are included

• pjdosfile – FATBANDS file used to compute the PJDOS. If None, the PJDOS is taken from self.

• edos_kwargs

• stacked – True if DOS partial contributions should be stacked on top of each other.

• width_ratios – Defines the ratio between the band structure plot and the dos plot.

• fontsize – Legend and subtitle fontsize.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right)

Returns: plotly.graph_objects.Figure

Keyword arguments controlling the display of the figure: ================ ==================================================================== kwargs Meaning ================ ==================================================================== title Title of the plot (Default: None). show True to show the figure (default: True). hovermode True to show the hover info (default: False) savefig “abc.png” , “abc.jpeg” or “abc.webp” to save the figure to a file. write_json Write plotly figure to write_json JSON file.

Inside jupyter-lab, one can right-click the write_json file from the file menu and open with “Plotly Editor”. Make some changes to the figure, then use the file menu to save the customized plotly plot. Requires jupyter labextension install jupyterlab-chart-editor. See https://github.com/plotly/jupyterlab-chart-editor

renderer (str or None (default None)) –

A string containing the names of one or more registered renderers (separated by ‘+’ characters) or None. If None, then the default renderers specified in plotly.io.renderers.default are used. See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html

config (dict) A dict of parameters to configure the figure. The defaults are set in plotly.js. chart_studio True to push figure to chart_studio server. Requires authenticatios.

Default: False.

template Plotly template. See https://plotly.com/python/templates/

[“plotly”, “plotly_white”, “plotly_dark”, “ggplot2”,

“seaborn”, “simple_white”, “none”]

Default is None that is the default template is used.

plot_pawdos_terms(lmax=None, method='gaussian', step=0.1, width=0.2, xlims=None, *kwargs) → Any

Plot …

Parameters:

• lmax – Maximum L included in plot. None means full set available on file.

• method – String defining the method for the computation of the DOS.

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

yield_plotly_figs(**kwargs)

This function generates a predefined list of plotly figures with minimal input from the user.

get_panel(**kwargs)

Build panel with widgets to interact with the abipy.electrons.fatbands.FatBandsFile either in a notebook or in panel app.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

fold2bloch Module

Fold2Bloch netcdf file.

class abipy.electrons.fold2bloch.Fold2BlochNcfile(filepath: str)

Bases: AbinitNcFile, Has_Header, Has_Structure, Has_ElectronBands, NotebookWriter

Netcdf file with output data produced by Fold2Bloch.

Usage example:

with Fold2BlochNcfile("foo_FOLD2BLOCH.nc") as fb:
    fb.plot_unfolded()

Inheritance Diagram

classmethod from_wfkpath(wfkpath, folds, workdir=None, manager=None, mpi_procs=1, verbose=0) → Fold2BlochNcfile

Run fold2bloch in workdir.

Parameters:

• wfkpath

• folds

• workdir – Working directory of the fake task used to compute the ibz. Use None for temporary dir.

• manager – TaskManager of the task. If None, the manager is initialized from the config file.

• mpi_procs – Number of MPI processors to use.

• verbose – Verbosity level.

to_string(verbose=0) → str

String representation.

property ebands: ElectronBands

abipy.electrons.ebands.ElectronBands object with folded band energies.

property structure: Structure

abipy.core.structure.Structure object defining the supercell.

close() → None

Close the file.

params()

dict with parameters that might be subject to convergence studies.

uf_eigens()

[nsppol, nk_unfolded, nband] numpy.ndarray with unfolded eigenvalues in eV.

uf_weights()

[nss, nk_unfolded, nband] array with spectral weights. nss = max(nspinor, nsppol).

get_spectral_functions(step=0.01, width=0.02)

Parameters:

• step – Energy step (eV) of the linear mesh.

• width – Standard deviation (eV) of the gaussian.

Returns:

mesh, sfw, int_sfw

plot_unfolded(kbounds, klabels, ylims=None, dist_tol=1e-12, verbose=0, colormap='afmhot', facecolor='black', ax=None, fontsize=8, **kwargs) → Any

Plot unfolded band structure with spectral weights.

Parameters:

• klabels – dictionary whose keys are tuple with the reduced coordinates of the k-points. The values are the labels. e.g. klabels = {(0.0,0.0,0.0): "$\Gamma$", (0.5,0,0): "L"}.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• dist_tol – A point is considered to be on the path if its distance from the line is less than dist_tol.

• verbose – Verbosity level.

• colormap – Have a look at the colormaps here and decide which one you like: http://matplotlib.sourceforge.net/examples/pylab_examples/show_colormaps.html

• facecolor

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

gsr Module

Interface to the GSR.nc file storing the Ground-state results and the electron band structure.

class abipy.electrons.gsr.GsrFile(filepath: str)

Bases: AbinitNcFile, Has_Header, Has_Structure, Has_ElectronBands, NotebookWriter

File containing the results of a ground-state calculation.

Usage example:

with GsrFile("foo_GSR.nc") as gsr:
    print("energy: ", gsr.energy)
    gsr.ebands.plot()

Inheritance Diagram

classmethod from_file(filepath: str) → GsrFile

Initialize the object from a netcdf file.

to_string(verbose: int = 0) → str

String representation.

property ebands: ElectronBands

abipy.electrons.ebands.ElectronBands object.

is_scf_run()

True if the GSR has been produced by a SCF run.

ecut()

Cutoff energy in Hartree (Abinit input variable)

pawecutdg()

Cutoff energy in Hartree for the PAW double grid (Abinit input variable)

property structure: Structure

abipy.core.structure.Structure object.

energy()

Total energy in eV.

energy_per_atom()

Total energy / number_of_atoms (eV units)

cart_forces()

Cartesian forces in eV / Ang. None if forces are not available.

max_force()

Max absolute cartesian force in eV/Ang. None if forces are not available.

force_stats(**kwargs)

Return a string with information on the forces. Return None if forces are not available.

cart_stress_tensor()

Stress tensor in GPa. Return None if not available e.g. if NSCF run.

pressure()

Pressure in GPa. Return None if not available e.g. if NSCF run.

residm()

Maximum of the residuals

xc()

XcFunc object with info on the exchange-correlation functional. Use libxc convention [Marques2012].

energy_terms()

EnergyTerms with the different contributions to the total energy in eV.

params()

OrderedDict with parameters that might be subject to convergence studies.

close() → None

Close the file.

as_dict() → dict

get_computed_entry(inc_structure=True, parameters=None, data=None)

Returns a pymatgen ComputedStructureEntry from the GSR file. Same API as the one used in vasp_output.get_computed_entry.

Parameters:

• inc_structure (bool) – Set to True if you want ComputedStructureEntries to be returned instead of ComputedEntries.

• parameters (list) – Input parameters to include. It has to be one of the properties supported by the GSR object. If parameters is None, a default set of parameters that are necessary for typical post-processing will be set.

• data (list) – Output data to include. Has to be one of the properties supported by the GSR object.

Returns:

ComputedStructureEntry/ComputedEntry

get_panel(**kwargs)

Build panel with widgets to interact with the abipy.electrons.gsr.GsrFile either in a notebook or in panel app.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

yield_plotly_figs(**kwargs)

This function generates a predefined list of plotly figures with minimal input from the user.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

gw Module

Classes for the analysis of GW calculations.

class abipy.electrons.gw.QPState(spin, kpoint, band, e0, qpe, qpe_diago, vxcme, sigxme, sigcmee0, vUme, ze0)

Bases: QPState

Quasi-particle result for given (spin, kpoint, band).

Note

Energies are in eV.

property qpeme0: complex

E_QP - E_0 in eV

property re_qpe: float

Real part of the QP energy.

property imag_qpe: float

Imaginay part of the QP energy.

property skb: tuple

Tuple with (spin, kpoint, band)

copy() → QPState

Return shallow copy.

classmethod get_fields(exclude=()) → tuple

as_dict(**kwargs) → dict

Convert self into a dictionary.

to_strdict(fmt=None) → dict

Ordered dictionary mapping fields –> strings.

property tips: str

Bound method of self that returns a dictionary with the description of the fields.

classmethod TIPS() → str

Class method that returns a dictionary with the description of the fields. The string are extracted from the class doc string.

classmethod get_fields_for_plot(with_fields, exclude_fields) → list

Return list of QPState fields to plot from input arguments.

class abipy.electrons.gw.SigresFile(filepath: str)

Bases: AbinitNcFile, Has_Structure, Has_ElectronBands, NotebookWriter

Container storing the GW results reported in the SIGRES.nc file.

Usage example:

sigres = SigresFile("foo_SIGRES.nc")
sigres.plot_qps_vs_e0()

Inheritance Diagram

marker_spin = {0: '^', 1: 'v'}

color_spin = {0: 'k', 1: 'r'}

classmethod from_file(filepath: str) → SigresFile

Initialize an instance from file.

property sigma_kpoints

The k-points where QP corrections have been calculated.

get_marker(qpattr)

Return Marker object associated to the QP attribute qpattr. Used to prepare plots of KS bands with markers.

params()

dictionary with parameters that might be subject to convergence studies e.g ecuteps

close() → None

Close the netcdf file.

to_string(verbose: int = 0) → str

String representation with verbosity level verbose.

property structure: Structure

abipy.core.structure.Structure object.

property ebands: ElectronBands

abipy.electrons.ebands.ElectronBands with the KS energies.

property has_spectral_function: bool

True if sigres file contains the spectral function.

qplist_spin()

Tuple of QPList objects indexed by spin.

get_qplist(spin, kpoint, ignore_imag=False) → QPList

Return :class`QPList` for the given (spin, kpoint)

get_qpcorr(spin, kpoint, band, ignore_imag=False) → QPState

Returns the QPState object for the given (s, k, b)

qpgaps()

numpy.ndarray of shape [nsppol, nkibz] with the QP direct gaps in eV.

get_qpgap(spin, kpoint, with_ksgap=False)

Return the QP gap in eV at the given (spin, kpoint)

read_sigee_skb(spin, kpoint, band) → SelfEnergy

” Read self-energy for (spin, kpoint, band).

print_qps(precision=3, ignore_imag=True, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None

Print QP results to stream file.

Parameters:

• precision – Number of significant digits.

• ignore_imag – True if imaginary part should be ignored.

• file – Output stream.

get_points_from_ebands(ebands_kpath, dist_tol=1e-12, size=24, verbose=0) → Marker

Generate Marker object storing the QP energies lying on the k-path used by ebands_kpath. Mainly used to plot the QP energies in ebands.plot when the QP energies are interpolated with the SKW method.

Parameters:

• ebands_kpath – abipy.electrons.ebands.ElectronBands object with the QP energies along an arbitrary k-path.

• dist_tol – A point is considered to be on the path if its distance from the line is less than dist_tol.

• size – The marker size in points**2

• verbose – Verbosity level

Example:

r = sigres.interpolate(lpratio=5,
                       ks_ebands_kpath=ks_ebands_kpath,
                       ks_ebands_kmesh=ks_ebands_kmesh
                       )
points = sigres.get_points_from_ebands(r.qp_ebands_kpath, size=24)
r.qp_ebands_kpath.plot(points=points)

plot_qpgaps(ax=None, plot_qpmks=True, fontsize=8, **kwargs) → Any

Plot the KS and the QP direct gaps for all the k-points and spins available on file.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• plot_qpmks – If False, plot QP_gap, KS_gap else (QP_gap - KS_gap)

• fontsize – legend and title fontsize.

• kwargs – Passed to ax.plot method except for marker.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_qps_vs_e0(with_fields='all', exclude_fields=None, e0='fermie', xlims=None, sharey=False, ax_list=None, fontsize=8, **kwargs) → Any

Plot QP result in the SIGRES file as function of the KS energy.

Parameters:

• with_fields – The names of the qp attributes to plot as function of eKS. Accepts: List of strings or string with tokens separated by blanks. See QPState for the list of available fields.

• exclude_fields – Similar to with_fields but excludes fields

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0=0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0=0

• ax_list – List of matplotlib.axes.Axes for plot. If None, new figure is produced.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• sharey – True if y-axis should be shared.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_spectral_functions(include_bands=None, fontsize=8, ax_list=None, **kwargs) → Any

Plot the spectral function for all k-points, bands and spins available in the SIGRES file.

Parameters:

• include_bands – List of bands to include. None means all.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_eigvec_qp(spin=0, kpoint=None, band=None, **kwargs) → Any

Parameters:

• spin – Spin index

• kpoint – K-point in self-energy. Accepts abipy.core.kpoints.Kpoint, vector or index. If None, all k-points for the given spin are shown.

• band – band index. If None all bands are displayed else only <KS_b|QP_{b’}> for the given b.

• kwargs – Passed to plot method of ArrayPlotter.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_qpbands_ibz(e0='fermie', colormap='jet', ylims=None, fontsize=8, **kwargs) → Any

Plot the KS band structure in the IBZ with the QP energies.

Parameters:

• e0 – Option used to define the zero of energy in the band structure plot.

• colormap – matplotlib color map.

• ylims – Set the data limits for the y-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_ksbands_with_qpmarkers(qpattr='qpeme0', e0='fermie', fact=1000, ax=None, **kwargs) → Any

Plot the KS energies as function of k-points and add markers whose size is proportional to the QPState attribute qpattr

Parameters:

• qpattr – Name of the QP attribute to plot. See QPState.

• e0 – Option used to define the zero of energy in the band structure plot. Possible values: - fermie: shift all eigenvalues to have zero energy at the Fermi energy (self.fermie). - Number e.g e0 = 0.5: shift all eigenvalues to have zero energy at 0.5 eV - None: Don’t shift energies, equivalent to e0 = 0

• fact – Markers are multiplied by this factor.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

get_dataframe(ignore_imag=False) → DataFrame

Returns pandas.DataFrame with QP results for all k-points included in the GW calculation

Parameters:

ignore_imag – Only real part is returned if ignore_imag.

get_dataframe_sk(spin, kpoint, index=None, ignore_imag=False, with_params=True) → pd.Dataframe

Returns pandas.DataFrame with the QP results for the given (spin, k-point).

Parameters:

• ignore_imag – Only real part is returned if ignore_imag.

• with_params – True to include convergence parameters.

plot_sigma_imag_axis(kpoint, spin=0, ax_list=None, fontsize=8, **kwargs) → Any

Plot the self-energy along the imaginary frequency axis. Requires GW calculations with analytic continuation

Parameters:

• kpoint

• spin – Spin index.

• ax_list – List of matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

interpolate(lpratio=5, ks_ebands_kpath=None, ks_ebands_kmesh=None, ks_degatol=0.0001, vertices_names=None, line_density=20, filter_params=None, only_corrections=False, verbose=0)

Interpolate the GW corrections in k-space on a k-path and, optionally, on a k-mesh.

Parameters:

• lpratio – Ratio between the number of star functions and the number of ab-initio k-points. The default should be OK in many systems, larger values may be required for accurate derivatives.

• ks_ebands_kpath – KS abipy.electrons.ebands.ElectronBands on a k-path. If present, the routine interpolates the QP corrections and apply them on top of the KS band structure This is the recommended option because QP corrections are usually smoother than the QP energies and therefore easier to interpolate. If None, the QP energies are interpolated along the path defined by vertices_names and line_density.

• ks_ebands_kmesh – KS abipy.electrons.ebands.ElectronBands on a homogeneous k-mesh. If present, the routine interpolates the corrections on the k-mesh (used to compute QP the DOS)

• ks_degatol – Energy tolerance in eV. Used when either ks_ebands_kpath or ks_ebands_kmesh are given. KS energies are assumed to be degenerate if they differ by less than this value. The interpolator may break band degeneracies (the error is usually smaller if QP corrections are interpolated instead of QP energies). This problem can be partly solved by averaging the interpolated values over the set of KS degenerate states. A negative value disables this ad-hoc symmetrization.

• vertices_names – Used to specify the k-path for the interpolated QP band structure when ks_ebands_kpath is None. It’s a list of tuple, each tuple is of the form (kfrac_coords, kname) where kfrac_coords are the reduced coordinates of the k-point and kname is a string with the name of the k-point. Each point represents a vertex of the k-path. line_density defines the density of the sampling. If None, the k-path is automatically generated according to the point group of the system.

• line_density – Number of points in the smallest segment of the k-path. Used with vertices_names.

• filter_params – TO BE DESCRIBED

• only_corrections – If True, the output contains the interpolated QP corrections instead of the QP energies. Available only if ks_ebands_kpath and/or ks_ebands_kmesh are used.

• verbose – Verbosity level

Returns:

namedtuple with the following attributes:

* qp_ebands_kpath: |ElectronBands| with the QP energies interpolated along the k-path.
* qp_ebands_kmesh: |ElectronBands| with the QP energies interpolated on the k-mesh.
    None if ``ks_ebands_kmesh`` is not passed.
* ks_ebands_kpath: |ElectronBands| with the KS energies interpolated along the k-path.
* ks_ebands_kmesh: |ElectronBands| with the KS energies on the k-mesh..
    None if ``ks_ebands_kmesh`` is not passed.
* interpolator: |SkwInterpolator| object.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.gw.SigresRobot(*args)

Bases: Robot, RobotWithEbands

This robot analyzes the results contained in multiple SIGRES.nc files.

Inheritance Diagram

EXT = 'SIGRES'

merge_dataframes_sk(spin, kpoint, **kwargs)

get_qpgaps_dataframe(spin=None, kpoint=None, with_geo=False, abspath=False, funcs=None, **kwargs)

Return a pandas.DataFrame with the QP gaps for all files in the robot.

Parameters:

• spin – Spin index.

• kpoint

• with_geo – True if structure info should be added to the dataframe

• abspath – True if paths in index should be absolute. Default: Relative to getcwd().

• funcs – Function or list of functions to execute to add more data to the DataFrame. Each function receives a abipy.electrons.gw.SigresFile object and returns a tuple (key, value) where key is a string with the name of column and value is the value to be inserted.

get_fit_gaps_vs_ecuteps(spin, kpoint, plot_qpmks=True, slice_data=None, fontsize=12)

Fit QP direct gaps as a function of ecuteps using Eq. 16 of http://dx.doi.org/10.1063/1.4900447 to extrapolate results for ecuteps –> +oo.

Parameters:

• spin – Spin index (0 or 1)

• kpoint – K-point in self-energy. Accepts abipy.core.kpoints.Kpoint, vector or k-point index.

• plot_qpmks – If False, plot QP_gap else (QP_gap - KS_gap) i.e. gap correction

• slice_data – Python slice object. Used to downsample data points. None to use all files of the SigResRobot.

• fontsize – legend and label fontsize.

Return: TODO

get_dataframe(spin=None, kpoint=None, with_geo=False, abspath=False, funcs=None, **kwargs)

Return a pandas.DataFrame with the QP gaps for all files in the robot.

Parameters:

• spin – Spin index.

• kpoint

• with_geo – True if structure info should be added to the dataframe

• abspath – True if paths in index should be absolute. Default: Relative to getcwd().

• funcs – Function or list of functions to execute to add more data to the DataFrame. Each function receives a abipy.electrons.gw.SigresFile object and returns a tuple (key, value) where key is a string with the name of column and value is the value to be inserted.

plot_qpgaps_convergence(plot_qpmks=True, sortby=None, hue=None, sharey=False, fontsize=8, **kwargs) → Any

Plot the convergence of the direct QP gaps for all the k-points available in the robot.

Parameters:

• plot_qpmks – If False, plot QP_gap, KS_gap else (QP_gap - KS_gap)

• sortby – Define the convergence parameter, sort files and produce plot labels. Can be None, string or function. If None, no sorting is performed. If string and not empty it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of sortby(abifile) is used.

• hue – Variable that define subsets of the data, which will be drawn on separate lines. Accepts callable or string If string, it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of hue(abifile) is used.

• sharey – True if y-axis should be shared.

• fontsize – legend and label fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_qpdata_conv_skb(spin, kpoint, band, sortby=None, hue=None, fontsize=8, **kwargs) → Any

For each file in the SIGRES robot, plot the convergence of the QP results for given (spin, kpoint, band)

Parameters:

• spin – Spin index.

• kpoint – K-point in self-energy. Accepts abipy.core.kpoints.Kpoint, vector or index.

• band – Band index.

• sortby – Define the convergence parameter, sort files and produce plot labels. Can be None, string or function. If None, no sorting is performed. If string and not empty it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of sortby(abifile) is used.

• hue – Variable that define subsets of the data, which will be drawn on separate lines. Accepts callable or string If string, it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of hue(abifile) is used.

• what_list – List of strings selecting the quantity to plot.

• fontsize – legend and label fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_qpfield_vs_e0(field, sortby=None, hue=None, fontsize=8, sharey=False, colormap='jet', e0='fermie', **kwargs) → Any

For each file in the robot, plot one of the attributes of QpState as a function of the KS energy.

Parameters:

• field (str) – String defining the attribute to plot.

• sharey – True if y-axis should be shared.

Note

For the meaning of the other arguments, see other robot methods.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_selfenergy_conv(spin, kpoint, band, sortby=None, hue=None, colormap='jet', xlims=None, fontsize=8, **kwargs) → Any

Plot the convergence of the e-e self-energy wrt to the sortby parameter. Values can be optionally grouped by hue.

Parameters:

• spin – Spin index.

• kpoint – K-point in self-energy (can be abipy.core.kpoints.Kpoint, list/tuple or int)

• band – Band index.

• sortby – Define the convergence parameter, sort files and produce plot labels. Can be None, string or function. If None, no sorting is performed. If string and not empty it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of sortby(abifile) is used.

• hue – Variable that define subsets of the data, which will be drawn on separate lines. Accepts callable or string If string, it’s assumed that the abifile has an attribute with the same name and getattr is invoked. If callable, the output of hue(abifile) is used.

• colormap – matplotlib color map.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• fontsize – Legend and title fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

lruj Module

Classes to analyse LRUJ results.

class abipy.electrons.lruj.LrujResults(*, natom: int, npert: int, ndata: int, pawujat: int, macro_uj: int, diem_token: str, diem: float, alphas: ndarray, occ_unscr: ndarray, occ_scr: ndarray, chi0_coefficients: dict, chi_coefficients: dict, maxdeg: int, dmatpuopt: int, pert_name: str, parname: str, metric: str, fit_df: DataFrame)

Bases: object

This object stores the results produced by lruj.

natom: int

npert: int

ndata: int

pawujat: int

macro_uj: int

diem_token: str

diem: float

alphas: ndarray

occ_unscr: ndarray

occ_scr: ndarray

chi0_coefficients: dict

chi_coefficients: dict

maxdeg: int

dmatpuopt: int

pert_name: str

parname: str

metric: str

fit_df: DataFrame

classmethod from_file(filepath: str | PathLike)

Extract results from the main ouput file produced by lruj.

plot(ax=None, degrees='all', inset=True, insetdegree=1, insetlocale='lower left', ptcolor0='k', ptcolor='k', gradcolor1='#3575D5', gradcolor2='#FDAE7B', ptitle='default', fontsize=12, **kwargs) → Any

Plot

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• degrees – List of degrees to plot. If None, no polynomials are plotted.

• ptcolor0 – Color of unscreened response data points (default: black)

• ptcolor – Color of screened response data points (default: black)

• gradcolor1 – Hex code of linear regression color (default: Blue #3575D5)

• gradcolor2 – Hex code of color of regression of maximum degree in list <degrees> (default: Salmon #FDAE7B)

• ptitle – Plot title (default: “Linear Response for atom <pawujat>)

• inset – Plots inset with LR parameter for polynomial fit of degree <insetdegree> (default: True)

• insetdegree – Degree of polynomial fit information printed in the inset (default: 1)

• insetlocale – Position of inset in the plot. Standard matplotlob locations. (default: “lower left”)

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

class abipy.electrons.lruj.LrujAnalyzer(manager=None, verbose=0)

Bases: object

Analyzes multiple sets of LRUJ files.

add_ncpaths(key: str, nc_paths: list[str]) → None

run(workdir=None) → None

Invoke lruj

plot(**kwargs) → Any

Plot

Args:

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

lobster Module

Tools to analyze the output files produced by Lobster.

class abipy.electrons.lobster.CoxpFile(filepath: str)

Bases: _LobsterFile

Wrapper class for the crystal orbital projections produced by Lobster. Wraps both a COOP and a COHP. Can contain both the total and orbitalwise projections.

cop_type

String. Either “coop” or “cohp”.

type_of_index

Dictionary mappping site index to element string.

energies

List of energies. Shifted such that the Fermi level lies at 0 eV.

total

A dictionary with the values of the total overlap, not projected over orbitals. The dictionary should have the following nested keys: a tuple with the index of the sites considered as a pair (0-based, e.g. (0, 1)), the spin (i.e. 0 or 1), a “single” or “integrated” string indicating the value corresponding to the value of the energy or to the integrated value up to that energy.

partial

A dictionary with the values of the partial crystal orbital projections. The dictionary should have the following nested keys: a tuple with the index of the sites considered as a pair (0-based, e.g. (0, 1)), a tuple with the string representing the projected orbitals for that pair (e.g. (“4s”, “4p_x”)), the spin (i.e. 0 or 1), a “single” or “integrated” string indicating the value corresponding to the value of the energy or to the integrated value up to that energy. Each dictionary should contain a numpy array with a list of COP values with the same size as energies.

averaged

A dictionary with the values of the partial crystal orbital projections averaged over all atom pairs specified. The main key should indicate the spin (0 or 1) and the nested dictionary should have “single” and “integrated” as keys.

fermie

value of the fermi energy in eV.

property site_pairs_total: list

List of site pairs available for the total COP

property site_pairs_partial: list

List of site pairs available for the partial COP

classmethod from_file(filepath: str) → CoxpFile

Generates an instance of CoxpFile from the files produce by Lobster. Accepts gzipped files.

Parameters:

filepath – path to the COHPCAR.lobster or COOPCAR.lobster.

Returns:

A CoxpFile.

functions_pair_lorbitals()

Extracts a dictionary with keys pair, orbital, spin and containing a abipy.core.func1d.Function1D object resolved for l orbitals.

functions_pair_morbitals()

Extracts a dictionary with keys pair, orbital, spin and containing a abipy.core.func1d.Function1D object resolved for l and m orbitals.

functions_pair()

Extracts a dictionary with keys pair, spin and containing a abipy.core.func1d.Function1D object for the total COP.

to_string(verbose=0) → str

String representation with verbosity level verbose.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

plot(what='d', spin=None, ax=None, exchange_xy=False, fontsize=12, **kwargs) → Any

Plot COXP averaged values (DOS or IDOS depending on what).

Parameters:

• what – string selecting what will be plotted. “d” for DOS, “i” for IDOS

• spin – Select spin index if not None.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• exchange_xy – True to exchange x-y axis.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_average_pairs(with_site_index, what='single', exchange_xy=False, fontsize=8, **kwargs) → Any

Plot COXP total overlap for all sites containg with_site_index and average sum (multiplied by the number of pairs)

Parameters:

• with_site_index – int of list of integers selecting the site index to be included.

• what – “single” for COXP DOS, “integrated” for IDOS.

• exchange_xy – True to exchange x-y axis.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_site_pairs_total(from_site_index, what='single', exchange_xy=False, ax=None, fontsize=8, **kwargs) → Any

Plot COXP total overlap (DOS or IDOS) for all sites listed in from_site_index

Parameters:

• from_site_index – int of list of integers selecting the first site of the pairs to be included.

• what – “single” for COXP DOS, “integrated” for IDOS.

• exchange_xy – True to exchange x-y axis.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

get_labelstyle_from_spin_pair(spin, pair)

Return label and linestyle for spin and pair indices

plot_site_pairs_partial(from_site_index, what='single', exchange_xy=True, ax=None, fontsize=8, **kwargs) → Any

Plot partial crystal orbital projections (DOS or IDOS) for all sites listed in from_site_index

Parameters:

• from_site_index – int of list of integers selecting the first site of the pairs to be included.

• what – “single” for COXP DOS, “integrated” for IDOS.

• exchange_xy – True to exchange x-y axis.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

get_labelstyle_from_spin_pair_orbs(spin, pair, orbs)

Return label and linestyle for spin, pair indices and orbs tuple.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.lobster.ICoxpFile(filepath: str)

Bases: _LobsterFile

Wrapper class for the integrated crystal orbital projections up to the Fermi energy produced from Lobster. May contain the output stored in ICOHPLIST.lobster and ICOOPLIST.lobster

cop_type

String. Either “coop” or “cohp”.

values

A dictionary with the following keys: a tuple with the index of the sites considered as a pair (0-based, e.g. (0,1)), the spin (i.e. 0 or 1)

type_of_index

Dictionary mappping site index to element string.

classmethod from_file(filepath)

Generates an instance of ICoxpFile from the files produce by Lobster. Accepts gzipped files.

Parameters:

filepath – path to the ICOHPLIST.lobster or ICOOPLIST.lobster.

Returns:

A ICoxpFile.

to_string(verbose=0)

String representation with verbosity level verbose.

dataframe()

pandas.DataFrame with results.

plot(ax=None, **kwargs) → Any

Barplot with average values.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.lobster.LobsterDoscarFile(filepath: str)

Bases: _LobsterFile

Total and partial dos extracted from lobster DOSCAR. The fermi energy is always at the zero value.

energies

List of energies. Shifted such that the Fermi level lies at 0 eV.

total_dos

A dictionary with spin as a key (i.e. 0 or 1) and containing the values of the total DOS. Should have the same size as energies.

pdos

A dictionary with the values of the projected DOS. The dictionary should have the following nested keys: the index of the site (0-based), the string representing the projected orbital (e.g. “4p_x”), the spin (i.e. 0 or 1). Each dictionary should contain a numpy array with a list of DOS values with the same size as energies.

classmethod from_file(filepath)

Generates an instance from the DOSCAR.lobster file. Accepts gzipped files.

Parameters:

filepath – path to the DOSCAR.lobster.

Returns:

A LobsterDoscarFile.

to_string(verbose=0)

String representation with Verbosity level verbose.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

plot(spin=None, ax=None, exchange_xy=False, fontsize=12, **kwargs) → Any

Plot DOS.

Parameters:

• spin

• exchange_xy – True to exchange x-y axis.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_pdos_site(site_index, ax=None, exchange_xy=False, fontsize=8, **kwargs) → Any

Plot projected DOS

Parameters:

• site_index

• exchange_xy – True to exchange x-y axis.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.lobster.LobsterInput(basis_set=None, basis_functions=None, include_orbitals=None, atom_pairs=None, dist_range=None, orbitalwise=True, start_en=None, end_en=None, en_steps=None, gaussian_smearing=None, bwdf=None, advanced_options=None)

Bases: object

This object stores the basic variables for a Lobster input and generates the lobsterin file.

accepted_basis_sets = {'bunge', 'koga', 'pbevaspfit2015'}

available_advanced_options = {'basisRotation', 'doNotIgnoreExcessiveBands', 'doNotOrthogonalizeBasis', 'doNotUseAbsoluteSpilling', 'forceEnergyRange', 'forceV1HMatrix', 'noMemoryMappedFiles', 'noSymmetryCorrection', 'onlyReadVasprun.xml', 'skipPAWOrthonormalityTest', 'skipReOrthonormalization', 'symmetryDetectionPrecision', 'useDecimalPlaces', 'useOriginalTetrahedronMethod', 'writeBasisFunctions'}

set_basis_functions_from_abinit_pseudos(pseudos)

Sets the basis function used from the PAW abinit pseudopotentials

Parameters:

pseudos – a list of Pseudos objects.

set_basis_functions_from_potcar(potcar)

Sets the basis function used from a POTCAR.

Parameters:

potcar – a pymatgen.io.vasp.inputs.Potcar object

to_string(verbose=0)

String representation.

classmethod from_dir(dirpath, dE=0.01, **kwargs)

Generates an instance of the class based on the output folder of a DFT calculation. Reads the information from the pseudopotentials in order to determine the basis functions.

Parameters:

• dirpath – the path to the calculation directory. For abinit it should contain the “files” file and GSR file, for vasp it should contain the vasprun.xml and the POTCAR.

• dE – The spacing of the energy sampling in eV.

• kwargs – the inputs for the init method, except for basis_functions, start_en, end_en and en_steps.

Returns:

A LobsterInput.

write(dirpath='.')

Write the input file ‘lobsterin’ in dirpath.

class abipy.electrons.lobster.LobsterAnalyzer(dirpath, prefix, coop_path=None, cohp_path=None, icohp_path=None, lobdos_path=None)

Bases: NotebookWriter

classmethod from_dir(dirpath, prefix='')

Generates an instance of the class based on the output folder of a DFT calculation.

Parameters:

dirpath – the path to the calculation directory.

to_string(verbose=0)

String representation with verbosity level verbose.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

plot(entries=('coop', 'cohp', 'doscar'), spin=None, **kwargs) → Any

Plot COOP + COHP + DOSCAR.

Parameters:

• entries – “cohp” to plot COHP, “coop” for COOP

• spin

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_coxp_with_dos(from_site_index, what='cohp', with_orbitals=False, exchange_xy=True, fontsize=8, **kwargs) → Any

Plot COHP (COOP) for all sites in from_site_index and Lobster DOS on len(from_site_index) + 1 subfigures.

Parameters:

• from_site_index – List of site indices for COHP (COOP)

• what – “cohp” to plot COHP, “coop” for COOP

• with_orbitals – True if orbital projections are wanted.

• exchange_xy – True to exchange x-y axis. By default, use x-axis for DOS-like quantities.

• fontsize – fontsize for legends and titles

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

optic Module

Objects to read and analyze optical properties stored in the optic.nc file produced by optic executable.

abipy.electrons.optic.reflectivity(eps)

Reflectivity(w) from vacuum, at normal incidence

abipy.electrons.optic.kappa(eps)

Im(refractive index(w)) aka kappa

abipy.electrons.optic.n(eps)

Re(refractive index(w)) aka n

class abipy.electrons.optic.OpticNcFile(filepath: str)

Bases: AbinitNcFile, Has_Header, Has_Structure, Has_ElectronBands, NotebookWriter

This file contains the results produced by optic. Provides methods to plot optical properties and susceptibilty tensors. Used by OpticRobot to analyze multiple files.

Usage example:

with OpticNcFile("out_optic.nc") as optic:
    optic.ebands.plot()
    optic.plot()

Inheritance Diagram

classmethod from_file(filepath: str) → OpticNcFile

Initialize the object from a netcdf file.

wmesh()

Frequency mesh in eV. Note that the same frequency-mesh is used for the different optical properties.

to_string(verbose: int = 0) → str

String representation.

ebands()

abipy.electrons.ebands.ElectronBands object.

property structure: Structure

abipy.core.structure.Structure object.

has_linopt()

True if the ncfile contains Second Harmonic Generation tensor.

has_shg()

True if the ncfile contains Second Harmonic Generation tensor.

has_leo()

True if the ncfile contains the Linear Electro-optic tensor

close() → None

Close the file.

params()

OrderedDict with parameters that might be subject to convergence studies.

static get_linopt_latex_label(what: str, comp: str) → str

Return latex label for linear-optic quantities. Used in plots.

get_chi2_latex_label(key: str, what: str, comp: str) → str

Build latex label for chi2-related quantities. Used in plots.

plot_linear_epsilon(components='all', what='im', itemp=0, ax=None, xlims=None, with_xlabel=True, label=None, fontsize=12, **kwargs)

Plot components of the linear dielectric function.

Parameters:

• components – List of cartesian tensor components to plot e.g. [“xx”, “xy”]. “all” if all components available on file should be plotted on the same ax.

• what – quantity to plot. “re” for real part, “im” for imaginary. Accepts also “abs”, “angle”.

• itemp – Temperature index.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• with_xlabel – True if x-label should be added.

• label – True to add legend label to each curve.

• fontsize – Legend and label fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_linopt(select='all', itemp=0, xlims=None, **kwargs)

Subplots with all linear optic quantities selected by select at temperature itemp.

Parameters:

• select

• itemp – Temperature index.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_chi2(key, components='all', what='abs', itemp=0, decompose=False, ax=None, xlims=None, with_xlabel=True, label=None, fontsize=12, **kwargs)

Low-level function to plot chi2 tensor.

Parameters:

• key

• components – List of cartesian tensor components to plot e.g. [“xxx”, “xyz”]. “all” if all components available on file should be plotted on the same ax.

• what – quantity to plot. “re” for real part, “im” for imaginary, Accepts also “abs”, “angle”.

• itemp – Temperature index.

• decompose – True to plot individual contributions.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• with_xlabel – True to add x-label.

• label – True to add legend label to each curve.

• fontsize – Legend and label fontsize.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_shg(**kwargs)

Plot Second Harmonic Generation. See plot_chi2 for args supported.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_leo(**kwargs)

Plot Linear Electro-optic. See plot_chi2 for args supported.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.optic.OpticReader(filepath: str)

Bases: ElectronsReader

This object reads the results stored in the optic.nc file It provides helper function to access the most important quantities.

Inheritance Diagram

read_lineps(components, itemp=0)

Parameters:

• components – List of cartesian tensor components to plot e.g. [“xx”, “xy”]. “all” if all components available on file should be plotted on the same ax.

• itemp – Temperature index.

read_tensor3_terms(key, components, itemp=0)

Parameters:

• key – Name of the netcdf variable to read.

• components – List of cartesian tensor components to plot e.g. [“xxx”, “xyz”]. “all” if all components available on file should be plotted on the same ax.

• itemp – Temperature index.

Returns:

OrderedDict mapping cartesian components e.g. “xyz” to data dictionary. Individual entries are listed in ALL_CHIS[key][“terms”]

class abipy.electrons.optic.OpticRobot(*args)

Bases: Robot, RobotWithEbands

This robot analyzes the results contained in multiple optic.nc files.

Inheritance Diagram

EXT = 'OPTIC'

computed_components_intersection()

Dictionary with the list of cartesian tensor components available in each file. Use keys from ALL_CHIS.

plot_linopt_convergence(components='all', what_list=('re', 'im'), sortby='nkpt', itemp=0, xlims=None, **kwargs)

Plot the convergence of the dielectric function tensor with respect to parameter defined by sortby.

Parameters:

• components – List of cartesian tensor components to plot e.g. [“xx”, “xy”]. “all” if all components available on file should be plotted on the same ax.

• what_list – List of quantities to plot. “re” for real part, “im” for imaginary. Accepts also “abs”, “angle”.

• sortby – Define the convergence parameter, sort files and produce plot labels. Can be None, string or function. If None, no sorting is performed. If string, it’s assumed that the ncfile has an attribute with the same name and getattr is invoked. If callable, the output of callable(ncfile) is used.

• itemp – Temperature index.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_shg_convergence(**kwargs)

Plot Second Harmonic Generation. See plot_convergence_rank3 for args supported.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_leo_convergence(**kwargs)

Plot Linear electron-optic. See plot_convergence_rank3 for args supported.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_convergence_rank3(key, components='all', itemp=0, what_list=('abs',), sortby='nkpt', decompose=False, xlims=None, **kwargs)

Plot convergence of arbitrary rank3 tensor. This is a low-level routine used in other plot methods.

Parameters:

• key – Name of the quantity to analyze.

• components – List of cartesian tensor components to plot e.g. [“xxx”, “xyz”]. “all” if all components available on file should be plotted on the same ax.

• itemp – Temperature index.

• what_list – List of quantities to plot. “re” for real part, “im” for imaginary. Accepts also “abs”, “angle”.

• sortby – Define the convergence parameter, sort files and produce plot labels. Can be None, string or function. If None, no sorting is performed. If string, it’s assumed that the ncfile has an attribute with the same name and getattr is invoked. If callable, the output of callable(ncfile) is used.

• decompose – True to plot individual contributions.

• xlims – Set the data limits for the x-axis. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

psps Module

Interface to the PSPS.nc file containing the splined form factors computed by ABINIT.

abipy.electrons.psps.dataframe_from_pseudos(pseudos, index=None) → DataFrame

Build pandas dataframe with the most important info associated to a list of pseudos or a list of objects that can be converted into pseudos.

Parameters:

• pseudos – List of objects that can be converted to pseudos.

• index – Index of the dataframe.

Return: pandas Dataframe.

class abipy.electrons.psps.PspsFile(filepath: str)

Bases: AbinitNcFile, NotebookWriter

Netcdf file with the tables used in Abinit to apply the pseudopotential part of the KS Hamiltonian.

Usage example:

with PspsFile("foo_PSPS.nc") as psps:
    psps.plot_tcore_rspace()

linestyles_der = ['-', '--', '-.', ':', ':', ':']

color_der = ['black', 'red', 'green', 'orange', 'cyan']

classmethod from_file(filepath: str) → PspsFile

Initialize the object from a filepath.

classmethod from_abinit_run(pseudo, ecut, vloc_rcut=None, workdir=None) → PspsFile

Initialize the object from a filepath or a Pseudo object by invoking abinit with cutoff energy ecut.

Parameters:

vloc_rcut – Radial cutoff in Bohr (Abinit input variable)

close() → None

Close the file.

params()

OrderedDict with parameters that might be subject to convergence studies.

to_string(verbose: int = 0) → str

String representation.

plot(**kwargs) → Any

Driver routine to plot several quantities on the same graph.

Parameters:

ecut_ffnl – Max cutoff energy for ffnl plot (optional)

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_tcore_rspace(ax=None, ders=(0, 1, 2, 3), scale=1.0, rmax=3.0, **kwargs) → Any

Plot the model core charge and its derivatives in real space.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• ders – Tuple selecting the derivatives to be plotted.

• scale – 1.0 if all derivatives should be scaled to 1 else None.

• rmax – Max radius for plot in Bohr. None is full grid is wanted.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_tcore_qspace(ax=None, ders=(0,), with_fact=True, with_qn=0, scale=1.0, **kwargs) → Any

Plot the model core charge in q space.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• ders – Tuple selecting the derivatives to be plotted.

• scale – 1.0 if all derivatives should be scaled to 1 else None.

• with_qn

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_q2vq(ax=None, ders=(0,), with_qn=0, with_fact=True, scale=None, **kwargs) → Any

Plot the local part of the pseudopotential in q space.

q2vq(mqgrid) = q^2 V(q)

= -frac{Zv}{pi}

• q^2 4piint[(frac{sin(2pi q r)}{2pi q r})(r^2 V(r)+r Zv)dr].

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• ders – Tuple used to select the derivatives to be plotted.

• scale – 1.0 if all derivatives should be scaled to 1 else None.

• with_qn

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_ffspl(ax=None, ecut_ffnl=None, ders=(0,), l_select=None, with_qn=0, with_fact=False, scale=None, **kwargs) → Any

Plot the nonlocal part of the pseudopotential in q-space.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• ecut_ffnl – Max cutoff energy for ffnl plot (optional)

• scale – 1.0 if all derivatives should be scaled to 1 else None.

• ders – Tuple used to select the derivatives to be plotted.

• with_qn

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None)

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.psps.PspsRobot(*args)

Bases: Robot

This robot analyzes the results contained in multiple PSPS.nc files.

Inheritance Diagram

EXT = 'PSPS'

classmethod from_abinit_run(pseudos, ecut) → PspsRobot

Initialize the object from a list of filepaths or Pseudo objects

classmethod from_vloc_rcut_list(pseudo, vloc_rcut_list, ecut) → PspsRobot

Initialize the object by computing the form factors for the same pseudo with different values of vloc_rcut_list in Bohr.

plot_tcore_rspace(ders=(0, 1, 2, 3), scale=None, fontsize=8, **kwargs) → Any

Plot the model core charge and its derivatives in r-space.

Parameters:

fontsize – fontsize for subtitles.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_tcore_qspace(ders=(0, 1), with_qn=0, scale=None, fontsize=8, **kwargs) → Any

Plot the model core charge and its derivatives in q-space.

Parameters:

fontsize – fontsize for subtitles.

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_q2vq(ders=(0, 1), with_qn=0, with_fact=True, scale=None, fontsize=8, **kwargs) → Any

Plot the local part of the pseudopotential in q space.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_ffspl(ecut_ffnl=None, ders=(0, 1), with_qn=0, scale=None, fontsize=8, **kwargs) → Any

Plot the nonlocal part of the pseudopotential in q-space.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.psps.PspsReader(filepath: str)

Bases: ETSF_Reader

This object reads the results stored in the PSPS file produced by ABINIT. It provides helper functions to access the most important quantities.

read_coresd(rmax=None) → tuple[ndarray, ndarray]

Read the core charges and real-space derivatives for the different types of atoms.

Parameters:

rmax – Maximum radius in Bohr. If None, data on the full grid is returned.

Returns:

List of ntypat arrays. Each array contains the linear meshes in real space. coresd: List with nytpat arrays of shape [6, npts].

(np.zeros. np.zeros) if core charge is not present

Return type:

meshes

xccc1d[ntypat, n1xccc*(1-usepaw)]

Norm-conserving psps only The component xccc1d(n1xccc,1,ntypat) is the pseudo-core charge for each type of atom, on the radial grid. The components xccc1d(n1xccc,ideriv,ntypat) give the ideriv-th derivative of the pseudo-core charge with respect to the radial distance.

read_tcorespl() → tuple[ndarray, ndarray]

Returns:

Linear q-mesh in q-space. tcorespl: array of shape [ntypat, 2, mqgrid_vl] with the pseudo core density in reciprocal space on a regular grid. Only if pseudo has_tcore

Return type:

qmesh

read_vlspl() → tuple[ndarray, ndarray]

Returns:

Linear q-mesh in G-space vlspl: numpy array of shape [ntypat, two, mqgrid_vl] with the local part of each type of psp in q-space

Return type:

qmesh

read_projectors() → tuple[VnlProjector, ...]

ffspl[ntypat, lnmax, 2, mqgrid_ff] Gives, on the radial grid, the {n,l} non-local projectors both for NC and PAW.

get_lnlist_for_type(itypat: int) → list

Return a list of (l, n) indices for this atom type.

class abipy.electrons.psps.VnlProjector(itypat, ln, ekb, qmesh, data)

Bases: object

Data and parameters associated to a non-local projector.

to_string(verbose: int = 0) → str

String representation.

property ecuts: ndarray

List of cutoff energies in Ha corresponding to self.qmesh.

property sign_sqrtekb: ndarray

scissors Module

Scissors operator.

class abipy.electrons.scissors.Scissors(func_list, domains, residues, bounds=None)

Bases: object

This object represents an energy-dependent scissors operator. The operator is defined by a list of domains (energy intervals) and a list of functions defined in these domains. The domains should fulfill the constraints documented in the main constructor.

Note

eV units are assumed.

The standard way to create this object is via the methods provided by the factory class ScissorBuilder. Once the instance has been created, one can correct the band structure by calling the apply method.

Error

alias of ScissorsError

apply(eig)

Correct the eigenvalue eig (eV units).

class abipy.electrons.scissors.ScissorsBuilder(qps_spin, sigres_ebands)

Bases: object

This object facilitates the creation of Scissors instances.

Usage:

builder = ScissorsBuilder.from_file(“out_SIGRES.nc”)

# To plot the QP results as function of the KS energy: builder.plot_qpe_vs_e0()

# To select the domains esplicitly (optional but highly recommended) builder.build(domains_spin=[[-10, 6.02], [6.1, 20]])

# To compare the fitted results with the ab-initio data: builder.plot_fit()

# To plot the corrected bands: builder.plot_qpbands(abidata.ref_file(“si_nscf_WFK.nc”))

classmethod from_file(filepath)

Generate object from (SIGRES.nc) file. Main entry point for client code.

classmethod pickle_load(filepath)

Load the object from a pickle file.

pickle_dump(filepath, protocol=-1)

Save the object in Pickle format

property nsppol

Number of spins.

property e0min

Minimum KS energy in eV (takes into account spin)

property e0max

Maximum KS energy in eV (takes into account spin)

property scissors_spin

Returns a tuple of Scissors indexed by the spin value.

build(domains_spin=None, bounds_spin=None, k=3)

Build the scissors operator.

Parameters:

• domains_spin – list of domains in eV for each spin. If domains is None, domains are computed automatically from the sigres bands (two domains separated by the middle of the gap).

• bounds_spin – Options specifying the boundary conditions (not used at present)

• k – Parameter defining the order of the fit.

plot_qpe_vs_e0(with_fields='all', **kwargs)

Plot the quasiparticle corrections as function of the KS energy.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_fit(ax=None, fontsize=8, **kwargs)

Compare fit functions with input quasi-particle corrections.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – fontsize for titles and legend.

Return: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_qpbands(bands_filepath, bands_label=None, dos_filepath=None, dos_args=None, **kwargs)

Correct the energies found in the netcdf file bands_filepath and plot the band energies (both the initial and the corrected ones) with matplotlib. The plot contains the KS and the QP DOS if dos_filepath is not None.

Parameters:

• bands_filepath – Path to the netcdf file containing the initial KS energies to be corrected.

• plot. (bands_label String used to label the KS bands in the)

• dos_filepath – Optional path to a netcdf file with the initial KS energies on a homogeneous k-mesh (used to compute the KS and the QP dos)

• dos_args – Dictionary with the arguments passed to get_dos to compute the DOS Used if dos_filepath is not None.

• kwargs – Options passed to the plotter.

Return: matplotlib.figure.Figure

scr Module

Objects to analyze the screening files produced by the GW code (optdriver 3).

class abipy.electrons.scr.ScrFile(filepath: str)

Bases: AbinitNcFile, Has_Header, Has_Structure, NotebookWriter

This object provides an interface to the SCR.nc file produced by the GW code.

Usage example:

with ScrFile("foo_SCR.nc") as ncfile:
    print(ncfile)
    ncfile.plot_emacro()

Inheritance Diagram

classmethod from_file(filepath: str) → ScrFile

Initialize the object from a Netcdf file

close() → None

Close the file.

to_string(verbose=0) → str

String representation.

property structure: Structure

abipy.core.structure.Structure object.

property kpoints

List of k-points in the dielectric function.

ebands()

abipy.electrons.ebands.ElectronBands object with the single-particle energies used to compute the screening.

property ng: int

Number of G-vectors in screening matrices.

property wpoints: ndarray

Array of complex numbers with the frequencies of the dielectric function in Hartree.

property nw: int

Total number of frequencies.

property nrew: int

Number of real frequencies.

property nimw: int

Number of imaginary frequencies.

property netcdf_name: str

The netcdf name associated to the data on disk.

params()

dict with the most important parameters used to compute the screening keys can be accessed with the dot notation i.e. params.zcut.

plot_emacro(cplx_mode='re-im', ax=None, xlims=None, fontsize=12, **kwargs) → Any

Plot the macroscopic dielectric function with local-field effects.

Parameters:

• cplx_mode – string defining the data to print. Possible choices are (case-insensitive): “re” for the real part. “im” for the imaginary part. “abs” for the absolute value. “angle” will display the phase of the complex number in radians. Options can be concatenated with - e.g. re-im.

• xlims – Set the data limits for the x-axis in eV. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used.

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• fontsize – Legend and title fontsize.

Returns:

matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

plot_eelf(ax=None, xlims=None, fontsize=12, **kwargs) → Any

Plot electron energy loss function.

Parameters:

• ax – matplotlib.axes.Axes or None if a new figure should be created.

• xlims – Set the data limits for the x-axis in eV. Accept tuple e.g. (left, right) or scalar e.g. left. If left (right) is None, default values are used

• fontsize – Legend and label fontsize:

Returns: matplotlib.figure.Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.
plotly	Try to convert mpl figure to plotly.

yield_figs(**kwargs)

This function generates a predefined list of matplotlib figures with minimal input from the user. Used in abiview.py to get a quick look at the results.

write_notebook(nbpath=None) → str

Write a jupyter notebook to nbpath. If nbpath is None, a temporay file in the current working directory is created. Return path to the notebook.

class abipy.electrons.scr.SusFile(filepath: str)

Bases: ScrFile

class abipy.electrons.scr.ScrReader(filepath: str)

Bases: ETSF_Reader

This object reads the results stored in the SCR (Screening) file produced by ABINIT. It provides helper functions to access the most important quantities.

double inverse_dielectric_function(number_of_qpoints_dielectric_function, number_of_frequencies_dielectric_function, number_of_spins, number_of_spins, number_of_coefficients_dielectric_function, number_of_coefficients_dielectric_function, complex)

Inheritance Diagram

read_params() → AttrDict

Read the most important parameters used to compute the screening i.e. the parameters that may be subject to convergence studies.

Returns:

monty.collections.AttrDict a dictionary whose keys can be accessed with the dot notation i.e. d.key.

read_emacro_lf(kpoint=(0, 0, 0)) → Function1D

Read the macroscopic dielectric function with local field effects 1 / em1_{0,0)(kpoint, omega).

Return: abipy.core.func1d.Function1D object.

read_emacro_nlf(kpoint=(0, 0, 0)) → Function1D

Read the macroscopic dielectric function without local field effects e_{0,0)(kpoint, omega).

Return: abipy.core.func1d.Function1D

Warning

This function performs the inversion of e-1 to get e. that can be quite expensive and memory demanding for large matrices!

read_eelf(kpoint=(0, 0, 0)) → Function1D

Read electron energy loss function

• Im(1/ emacro)

Return: abipy.core.func1d.Function1D object.

read_wggmat(kpoint, spin1=0, spin2=0, cls=None)

Read data at the given k-point and return an instance of cls where cls is a subclass of _AwggMatrix

find_kpoint_fileindex(kpoint)

Returns the k-point and the index of the k-point in the netcdf file. Accepts abipy.core.kpoints.Kpoint instance or integer.

read_wslice(kpoint, ig1=0, ig2=0, spin1=0, spin2=0)

Read slice along the frequency dimension.

class abipy.electrons.scr.Polarizability(wpoints, gsphere, wggmat, inord='C')

Bases: _AwggMatrix

Inheritance Diagram

netcdf_name = 'polarizability'

latex_name = '\\tilde chi'

class abipy.electrons.scr.DielectricFunction(wpoints, gsphere, wggmat, inord='C')

Bases: _AwggMatrix

Inheritance Diagram

netcdf_name = 'dielectric_function'

latex_name = '\\epsilon'

class abipy.electrons.scr.InverseDielectricFunction(wpoints, gsphere, wggmat, inord='C')

Bases: _AwggMatrix

Inheritance Diagram

netcdf_name = 'inverse_dielectric_function'

latex_name = '\\epsilon^{-1}'