pymatgen.electronic_structure package — pymatgen 2026.3.9 documentation

# pymatgen.electronic_structure package

This package contains electronic structure related tools and analyses.

## Submodules

## pymatgen.electronic_structure.bandstructure module

This module provides classes to define things related to band structures.

class BandStructure(kpoints: ArrayLike, eigenvals: Mapping[Spin, ArrayLike], lattice: Lattice, efermi: float, labels_dict: Mapping[str, Kpoint] | None = None, coords_are_cartesian: bool = False, structure: Structure | None = None, projections: Mapping[Spin, NDArray] | None = None)

  Bases: `object`

  Generic band structure data, defined by a list of Kpoints

    and corresponding energies for each of them.

  kpoints

    Kpoints in the band structure.

    Type:

      list[Kpoint]

  lattice_rec

    The reciprocal lattice of the band structure.

    Type:

      Lattice

  efermi

    The Fermi level.

    Type:

      float

  is_spin_polarized

    Whether the band structure is spin-polarized.

    Type:

      bool

  bands

    The energy eigenvalues. Note that the use of an array is necessary for computational and memory efficiency due to the large amount of numerical data. The indices of the array are (band_index, kpoint_index).

    Type:

      dict[Spin, NDArray]

  nb_bands

    The number of bands in the band structure.

    Type:

      int

  structure

    The structure.

    Type:

      Structure

  projections

    The projections. Note that the use of an array is necessary for computational and memory efficiency due to the large amount of numerical data. The indices of the array are (band_index, kpoint_index, orbital_index, ion_index).

    Type:

      dict[Spin, NDArray]

  Parameters:

    - kpoints (NDArray) – Kpoint as NumPy array, in frac_coords of the given lattice by default.

    - eigenvals (dict) – Energies for spin up and spin down as {Spin.up:[][], Spin.down:[][]}, the first index of the array [][] refers to the band and the second to the index of the kpoint. The kpoints are ordered according to the kpoints array. If the band structure is not spin polarized, we only store one data set under Spin.up.

    - lattice (Lattice) – The reciprocal lattice. Pymatgen uses the physics convention of reciprocal lattice vectors with a 2*pi coefficient.

    - efermi (float) – The Fermi level.

    - labels_dict (dict[str, Kpoint]) – Dict mapping label to Kpoint.

    - coords_are_cartesian (bool) – Whether coordinates are cartesian.

    - structure (Structure) – The crystal structure associated with the band structure. This is needed if we provide projections to the band structure.

    - projections (dict[Spin, NDArray]) – Orbital projections. The indices of the array are (band_index, kpoint_index, orbital_index, ion_index). If the band structure is not spin polarized, we only store one data set under Spin.up.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of BandStructure.

  classmethod from_dict(dct: dict[str, Any]) → Self

    Create from a dict.

    Parameters:

      dct – A dict with all data for a BandStructure.

    Returns:

      BandStructure

  classmethod from_old_dict(dct: dict[str, Any]) → Self
    Parameters:

      dct (dict) – A dict with all data for a BandStructure object.

    Returns:

      BandStructure

  get_band_gap() → dict[str, Any]

    Get band gap.

    Returns:

      “energy” (float): Band gap energy. “direct” (bool): Whether the gap is direct. “transition” (str): Kpoint labels of the transition (e.g., “\Gamma-X”).

    Return type:

      dict with keys “energy”, “direct”, “transition”

  get_cbm() → dict[str, Any]

    Get data about the conduction band minimum (CBM).

    Returns:

      - “band_index” (dict): A dict with spin keys pointing to a list of the

      indices of the band containing the CBM (please note that you can have several bands sharing the CBM) {Spin.up:[], Spin.down:[]}. - “kpoint_index”: The list of indices in self.kpoints for the kpoint CBM. Please note that there can be several kpoint_indices relating to the same kpoint (e.g., Gamma can occur at different spots in the band structure line plot). - “kpoint” (Kpoint): The kpoint. - “energy” (float): The energy of the CBM. - “projections”: The projections along sites and orbitals of the CBM if any projection data is available (else it is an empty dictionary). The format is similar to the projections field in BandStructure: {spin:{‘Orbital’: [proj]}} where the array [proj] is ordered according to the sites in structure.

    Return type:

      dict with keys “band_index”, “kpoint_index”, “kpoint”, “energy”

  get_direct_band_gap() → float

    Get the direct band gap.

    Returns:

      The direct band gap value.

    Return type:

      float

  get_direct_band_gap_dict() → dict[Spin, dict[str, Any]]

    Get information about the direct band gap.

    Returns:

      The band gaps indexed by spin

        along with their band indices and kpoint index.

    Return type:

      dict[Spin, dict[str, Any]]

  get_kpoint_degeneracy(kpoint: NDArray, cartesian: bool = False, tol: float = 0.01) → int | None

    Get degeneracy of a given kpoint based on structure symmetry.

    Parameters:

      - kpoint (1x3 NDArray) – Coordinate of the k-point.

      - cartesian (bool) – Whether kpoint is in Cartesian or fractional coordinates.

      - tol (float) – Tolerance below which coordinates are considered equal.

    Returns:

      Degeneracy, or None if structure is not available.

    Return type:

      int | None

  get_projection_on_elements() → dict[Spin, list[list[dict[str, float]]]]

    Get projections on elements.

    Returns:

      Dict in {Spin.up:[][{Element: [values]}],

        Spin.down: [][{Element: [values]}]} format. If there is no projections in the band structure, return {}.

    Return type:

      dict[Spin, NDArray]

  get_projections_on_elements_and_orbitals(el_orb_spec: dict[str, list[str]])

    Get projections on elements and specific orbitals.

    Parameters:

      el_orb_spec (dict[str, list[str]]) – Elements and orbitals to project onto. Format is {Element: [orbitals]}, e.g. {“Cu”: [“d”, “s”]}.

    Returns:

      Projections on elements in the

        {Spin.up: [][{Element: {orb: values}}], Spin.down: [][{Element: {orb: values}}]} format. If there is no projections in the band structure, return {}.

    Return type:

      dict[str, list[str]

  get_sym_eq_kpoints(kpoint: NDArray, cartesian: bool = False, tol: float = 0.01) → NDArray | None

    Get unique symmetrically equivalent Kpoints.

    Parameters:

      - kpoint (1x3 array) – Coordinate of the Kpoint.

      - cartesian (bool) – Whether kpoint is in Cartesian or fractional coordinates.

      - tol (float) – Tolerance below which coordinates are considered equal.

    Returns:

      None if structure is not available.

    Return type:

      (1x3 NDArray) | None

  get_vbm() → dict[str, Any]

    Get data about the valence band maximum (VBM).

    Returns:

      - “band_index” (dict): A dict with spin keys pointing to a list of the

      indices of the band containing the VBM (please note that you can have several bands sharing the VBM) {Spin.up:[], Spin.down:[]}. - “kpoint_index”: The list of indices in self.kpoints for the kpoint VBM. Please note that there can be several kpoint_indices relating to the same kpoint (e.g., Gamma can occur at different spots in the band structure line plot). - “kpoint” (Kpoint): The kpoint. - “energy” (float): The energy of the VBM. - “projections”: The projections along sites and orbitals of the VBM if any projection data is available (else it is an empty dictionary). The format is similar to the projections field in BandStructure: {spin:{‘Orbital’: [proj]}} where the array [proj] is ordered according to the sites in structure.

    Return type:

      dict with keys “band_index”, “kpoint_index”, “kpoint”, “energy”

  is_metal(efermi_tol: float = 0.0001) → bool

    Check if the band structure indicates a metal, by looking at if the fermi level crosses a band.

    Returns:

      True if is metal.

    Return type:

      bool

class BandStructureSymmLine(kpoints: ArrayLike, eigenvals: Mapping[Spin, ArrayLike], lattice: Lattice, efermi: float, labels_dict: Mapping[str, Kpoint], coords_are_cartesian: bool = False, structure: Structure | None = None, projections: Mapping[Spin, NDArray] | None = None)

  Bases: `BandStructure`, `MSONable`

  Store band structures along selected (symmetry) lines in the Brillouin zone. We call the different symmetry lines (ex: \Gamma to Z) “branches”.

  Parameters:

    - kpoints (NDArray) – Array of kpoint, in frac_coords of the given lattice by default

    - eigenvals (dict[Spin, list]) – Energies for spin up and spin down {Spin.up:[][],Spin.down:[][]}, the first index of the array [][] refers to the band and the second to the index of the kpoint. The kpoints are ordered according to the order of the kpoints array. If the band structure is not spin polarized, we only store one data set under Spin.up.

    - lattice (Lattice) – The reciprocal lattice. Pymatgen uses the physics convention of reciprocal lattice vectors with a 2*pi coefficient.

    - efermi (float) – The Fermi level.

    - labels_dict (dict[str, Kpoint]) – Dict mapping label to Kpoint.

    - coords_are_cartesian (bool) – Whether coordinates are cartesian.

    - structure (Structure) – The crystal structure associated with the band structure. This is needed if we provide projections to the band structure.

    - projections (dict[Spin, NDArray]) – Orbital projections as {spin: array}. The indices of the array are [band_index, kpoint_index, orbital_index, ion_index].If the band structure is not spin polarized, we only store one data set under Spin.up.

  apply_scissor(new_band_gap: float) → Self

    Apply a scissor operator (shift of the CBM) to fit the given band gap. If it’s a metal, we look for the band crossing the Fermi level and shift this one up. This will not work all the time for metals!

    Parameters:

      new_band_gap (float) – The band gap the scissor band structure need to have.

    Returns:

      With the applied scissor shift.

    Return type:

      BandStructureSymmLine

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of BandStructureSymmLine.

  get_branch(index: int) → list[dict[str, Any]]
    Get what branch(es) is the kpoint. It takes into account the

      fact that one kpoint (e.g., Gamma) can be in several branches.

    Parameters:

      index (int) – The kpoint index.

    Returns:

      A list of dicts [{“name”, “start_index”, “end_index”, “index”}]

        indicating all branches in which the k_point is.

  get_equivalent_kpoints(index: int) → list[int]

    Get kpoint indices equivalent (having the same coords) to the given one.

    Parameters:

      index (int) – The kpoint index

    Returns:

      Equivalent indices.

    Return type:

      list[int]

    TODO: now it uses the label, we might want to use coordinates instead in case there was a mislabel.

class Kpoint(coords: ArrayLike, lattice: Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, label: str | None = None)

  Bases: `MSONable`

  A kpoint defined with a lattice and frac or Cartesian coordinates, similar to the Site object in pymatgen.core.structure.

  Parameters:

    - coords (NDArray) – Coordinate of the Kpoint.

    - lattice (Lattice) – The reciprocal lattice of the kpoint.

    - to_unit_cell (bool) – Translate fractional coordinate to the basic unit cell, i.e., all fractional coordinates satisfy 0 <= a < 1. Defaults to False.

    - coords_are_cartesian (bool) – Whether the coordinates given are in Cartesian (True) or fractional coordinates (by default fractional).

    - label (str) – The label of the Kpoint if any (None by default).

  property a: float

    Fractional a coordinate of the kpoint.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of the kpoint.

  property b: float

    Fractional b coordinate of the kpoint.

  property c: float

    Fractional c coordinate of the kpoint.

  property cart_coords: NDArray

    The Cartesian coordinates of the kpoint as a NumPy array.

  property frac_coords: NDArray

    The fractional coordinates of the kpoint as a NumPy array.

  classmethod from_dict(dct: dict) → Self

    Create from a dict.

    Parameters:

      dct (dict) – A dict with all data for a kpoint object.

    Returns:

      Kpoint

  property label: str | None

    The label associated with the kpoint.

  property lattice: Lattice

    The lattice associated with the kpoint, as a Lattice object.

class LobsterBandStructureSymmLine(kpoints: ArrayLike, eigenvals: Mapping[Spin, ArrayLike], lattice: Lattice, efermi: float, labels_dict: Mapping[str, Kpoint], coords_are_cartesian: bool = False, structure: Structure | None = None, projections: Mapping[Spin, NDArray] | None = None)

  Bases: `BandStructureSymmLine`

  LOBSTER subclass of BandStructure with customized functions.

  Parameters:

    - kpoints (NDArray) – Array of kpoint, in frac_coords of the given lattice by default

    - eigenvals (dict[Spin, list]) – Energies for spin up and spin down {Spin.up:[][],Spin.down:[][]}, the first index of the array [][] refers to the band and the second to the index of the kpoint. The kpoints are ordered according to the order of the kpoints array. If the band structure is not spin polarized, we only store one data set under Spin.up.

    - lattice (Lattice) – The reciprocal lattice. Pymatgen uses the physics convention of reciprocal lattice vectors with a 2*pi coefficient.

    - efermi (float) – The Fermi level.

    - labels_dict (dict[str, Kpoint]) – Dict mapping label to Kpoint.

    - coords_are_cartesian (bool) – Whether coordinates are cartesian.

    - structure (Structure) – The crystal structure associated with the band structure. This is needed if we provide projections to the band structure.

    - projections (dict[Spin, NDArray]) – Orbital projections as {spin: array}. The indices of the array are [band_index, kpoint_index, orbital_index, ion_index].If the band structure is not spin polarized, we only store one data set under Spin.up.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of BandStructureSymmLine.

  classmethod from_dict(dct: dict[str, Any]) → Self
    Parameters:

      dct (dict) – All data for a LobsterBandStructureSymmLine object.

    Returns:

      A LobsterBandStructureSymmLine object.

  classmethod from_old_dict(dct: dict[str, Any]) → Self
    Parameters:

      dct (dict) – All data for a LobsterBandStructureSymmLine object.

    Returns:

      A LobsterBandStructureSymmLine object

  get_projection_on_elements() → dict[Spin, list]

    Get projections on elements. It sums over all available orbitals for each element.

    Returns:

      dict in the {Spin.up:[][{Element:values}],

        Spin.down:[][{Element:values}]} format. If there is no projections in the band structure, return {}.

    Return type:

      dict[Spin, list]

  get_projections_on_elements_and_orbitals(el_orb_spec: dict[SpeciesLike, list]) → dict[Spin, list]

    Get projections on elements and specific orbitals.

    Parameters:

      el_orb_spec (dict) – Elements and Orbitals for which we want to project on. It is given as {Element: [orbitals]}, e.g. {“Si”: [“3s”, “3p”]} or {“Si”: [“3s”, “3p_x”, “3p_y”, “3p_z’]} depending on input files.

    Returns:

      A dictionary of projections on elements in the {Spin.up:[][{Element:{orb:values}}], Spin.down:[][{Element:{orb:values}}]} format if there is no projections in the band structure returns an empty dict.

get_reconstructed_band_structure(list_bs: list[BandStructure], efermi: float | None = None) → BandStructure
get_reconstructed_band_structure(list_bs: list[BandStructureSymmLine], efermi: float | None = None) → BandStructureSymmLine

  Merge multiple BandStructure(SymmLine) objects to a single one.

  This is typically useful when you split non self-consistent band structure runs to several independent jobs and want to merge the results.

  Parameters:

    - list_bs (list) – BandStructure or BandStructureSymmLine objects.

    - efermi (float) – The Fermi level of the reconstructed band structure. If None, an average of all the Fermi levels in each object in the list_bs is used.

  Returns:

    A BandStructure or BandStructureSymmLine object (depending on the type of the objects in list_bs).

## pymatgen.electronic_structure.boltztrap module

This module provides classes to run and analyze BoltzTraP on pymatgen band structure objects. BoltzTraP is a software developed by Georg Madsen to interpolate band structures and compute materials properties from this band structure using Boltzmann semi-classical transport theory.

https://www.tuwien.at/en/tch/tc/theoretical-materials-chemistry/boltztrap

You need version 1.2.3 or higher

References

Madsen, G. K. H., and Singh, D. J. (2006). BoltzTraP. A code for calculating band-structure dependent quantities. Computer Physics Communications, 175, 67-71

class BoltztrapAnalyzer(gap=None, mu_steps=None, cond=None, seebeck=None, kappa=None, hall=None, doping=None, mu_doping=None, seebeck_doping=None, cond_doping=None, kappa_doping=None, hall_doping=None, intrans=None, dos=None, dos_partial=None, carrier_conc=None, vol=None, warning=None, bz_bands=None, bz_kpoints=None, fermi_surface_data=None)

  Bases: `object`

  Store all the data from a boltztrap run.

  Constructor taking directly all the data generated by BoltzTraP. You won’t probably use it directly but instead use the from_files and from_dict methods.

  Parameters:

    - gap – The gap after interpolation in eV

    - mu_steps – The steps of electron chemical potential (or Fermi level) in eV.

    - cond – The electronic conductivity tensor divided by a constant relaxation time (sigma/tau) at different temperature and fermi levels. The format is {temperature: [array of 3x3 tensors at each Fermi level in mu_steps]}. The units are 1/(Ohm*m*s).

    - seebeck – The Seebeck tensor at different temperatures and fermi levels. The format is {temperature: [array of 3x3 tensors at each Fermi level in mu_steps]}. The units are V/K

    - kappa – The electronic thermal conductivity tensor divided by a constant relaxation time (kappa/tau) at different temperature and fermi levels. The format is {temperature: [array of 3x3 tensors at each Fermi level in mu_steps]} The units are W/(m*K*s)

    - hall – The hall tensor at different temperature and fermi levels The format is {temperature: [array of 27 coefficients list at each Fermi level in mu_steps]} The units are m^3/C

    - doping – The different doping levels that have been given to BoltzTraP. The format is {‘p’:[],’n’:[]} with an array of doping levels. The units are cm^-3

    - mu_doping – Gives the electron chemical potential (or Fermi level) for a given set of doping. Format is {‘p’:{temperature: [fermi levels],’n’:{temperature: [fermi levels]}} the Fermi level array is ordered according to the doping levels in doping units for doping are in cm^-3 and for Fermi level in eV

    - seebeck_doping – The Seebeck tensor at different temperatures and doping levels. The format is {‘p’: {temperature: [Seebeck tensors]}, ‘n’:{temperature: [Seebeck tensors]}} The [Seebeck tensors] array is ordered according to the doping levels in doping units for doping are in cm^-3 and for Seebeck in V/K

    - cond_doping – The electronic conductivity tensor divided by a constant relaxation time (sigma/tau) at different temperatures and doping levels The format is {‘p’:{temperature: [conductivity tensors]}, ‘n’:{temperature: [conductivity tensors]}} The [conductivity tensors] array is ordered according to the doping levels in doping units for doping are in cm^-3 and for conductivity in 1/(Ohm*m*s)

    - kappa_doping – The thermal conductivity tensor divided by a constant relaxation time (kappa/tau) at different temperatures and doping levels. The format is {‘p’:{temperature: [thermal conductivity tensors]},’n’:{temperature: [thermal conductivity tensors]}} The [thermal conductivity tensors] array is ordered according to the doping levels in doping units for doping are in cm^-3 and for thermal conductivity in W/(m*K*s)

    - hall_doping – The Hall tensor at different temperatures and doping levels. The format is {‘p’:{temperature: [Hall tensors]}, ‘n’:{temperature: [Hall tensors]}} The [Hall tensors] array is ordered according to the doping levels in doping and each Hall tensor is represented by a 27 coefficients list. The units are m^3/C

    - intrans – a dictionary of inputs e.g. {“scissor”: 0.0}

    - carrier_conc – The concentration of carriers in electron (or hole) per unit cell

    - dos – The dos computed by BoltzTraP given as a pymatgen Dos object

    - dos_partial – Data for the partial DOS projected on sites and orbitals

    - vol – Volume of the unit cell in angstrom cube (A^3)

    - warning – string if BoltzTraP outputted a warning, else None

    - bz_bands – Data for interpolated bands on a k-point line (run_type=BANDS)

    - bz_kpoints – k-point in reciprocal coordinates for interpolated bands (run_type=BANDS)

    - fermi_surface_data – energy values in a 3D grid imported from the output .cube file.

  as_dict()

    MSONable dict.

  static check_acc_bzt_bands(sbs_bz, sbs_ref, warn_thr=(0.03, 0.03))

    Compare sbs_bz BandStructureSymmLine calculated with boltztrap with the sbs_ref BandStructureSymmLine as reference (from MP for instance), computing correlation and energy difference for eight bands around the gap (semiconductors) or Fermi level (metals). warn_thr is a threshold to get a warning in the accuracy of Boltztap interpolated bands.

    Return a dictionary with these keys: - “N”: the index of the band compared; inside each there are:

    > - “Corr”: correlation coefficient for the 8 compared bands

    > - “Dist”: energy distance for the 8 compared bands

    > - “branch_name”: energy distance for that branch

    - “avg_corr”: average of correlation coefficient over the 8 bands

    - “avg_dist”: average of energy distance over the 8 bands

    - “nb_list”: list of indexes of the 8 compared bands

    - “acc_thr”: list of two float corresponding to the two warning thresholds in input

    - “acc_err”: list of two bools:

        True if the avg_corr > warn_thr[0], and True if the avg_dist > warn_thr[1]

    See also compare_sym_bands function doc.

  classmethod from_dict(data: dict) → Self
    Parameters:

      data – Dict representation.

    Returns:

      BoltztrapAnalyzer

  classmethod from_files(path_dir: str, dos_spin: Literal[-1, 1] = 1) → Self

    Get a BoltztrapAnalyzer object from a set of files.

    Parameters:

      - path_dir – directory where the boltztrap files are

      - dos_spin – in DOS mode, set to 1 for spin up and -1 for spin down

    Returns:

      BoltztrapAnalyzer

  get_average_eff_mass(output='eigs', doping_levels=True)

    Get the average effective mass tensor. We call it average because it takes into account all the bands and regions in the Brillouin zone. This is different than the standard textbook effective mass which relates often to only one (parabolic) band. The average effective mass tensor is defined as the integrated average of the second derivative of E(k) This effective mass tensor takes into account: -non-parabolicity -multiple extrema -multiple bands.

    For more information about it. See:

    Hautier, G., Miglio, A., Waroquiers, D., Rignanese, G., & Gonze, X. (2014). How Does Chemistry Influence Electron Effective Mass in Oxides? A High-Throughput Computational Analysis. Chemistry of Materials, 26(19), 5447-5458. doi:10.1021/cm404079a

    or

    Hautier, G., Miglio, A., Ceder, G., Rignanese, G.-M., & Gonze, X. (2013). Identification and design principles of low hole effective mass p-type transparent conducting oxides. Nature Communications, 4, 2292. doi:10.1038/ncomms3292

    Depending on the value of output, we have either the full 3x3 effective mass tensor, its 3 eigenvalues or an average

    Parameters:

      - output (str) – ‘eigs’ for eigenvalues, ‘tensor’ for the full

      - average (tensor and 'average' for an)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

    Returns:

      {temp:[]},’n’:{temp:[]}} with an array of effective mass tensor, eigenvalues of average value (depending on output) for each temperature and for each doping level. The ‘p’ links to hole effective mass tensor and ‘n’ to electron effective mass tensor.

    Return type:

      If doping_levels=True,a dictionary {‘p’

  get_carrier_concentration()

    Get the carrier concentration (in cm^-3).

    Returns:

      []} with an array of carrier concentration (in cm^-3) at each temperature The array relates to each step of electron chemical potential

    Return type:

      a dictionary {temp

  get_complete_dos(structure: Structure, analyzer_for_second_spin=None)

    Get a CompleteDos object with the DOS from the interpolated projected band structure.

    Parameters:

      - structure – necessary to identify sites for projection

      - analyzer_for_second_spin – must be specified to have a CompleteDos with both Spin components

    Returns:

      from the interpolated projected band structure

    Return type:

      CompleteDos

    Example of use in case of spin polarized case:

    > BoltztrapRunner(bs=bs,nelec=10,run_type=”DOS”,spin=1).run(path_dir=’dos_up/’) an_up=BoltztrapAnalyzer.from_files(“dos_up/boltztrap/”, dos_spin=1)

    > BoltztrapRunner(bs=bs,nelec=10,run_type=”DOS”,spin=-1).run(path_dir=’dos_dw/’) an_dw=BoltztrapAnalyzer.from_files(“dos_dw/boltztrap/”, dos_spin=-1)

    > cdos=an_up.get_complete_dos(bs.structure,an_dw)

  get_complexity_factor(output: Literal['average', 'tensor'] = 'average', temp=300, doping_levels=False, Lambda=0.5)

    Fermi surface complexity factor respect to calculated as explained in Ref. Gibbs, Z. M. et al., Effective mass and fermi surface complexity factor from ab initio band structure calculations. npj Computational Materials 3, 8 (2017).

    Parameters:

      - output – ‘average’ returns the complexity factor calculated using the average of the three diagonal components of the seebeck and conductivity tensors. ‘tensor’ returns the complexity factor respect to the three diagonal components of seebeck and conductivity tensors.

      - doping_levels – False means that the complexity factor is calculated for every value of the chemical potential True means that the complexity factor is calculated for every value of the doping levels for both n and p types

      - temp – temperature of calculated seebeck and conductivity.

      - Lambda – fitting parameter used to model the scattering (0.5 means constant relaxation time).

    Returns:

      a list of values for the complexity factor w.r.t the chemical potential, if doping_levels is set at False; a dict with n an p keys that contain a list of values for the complexity factor w.r.t the doping levels, if doping_levels is set at True; if ‘tensor’ is selected, each element of the lists is a list containing the three components of the complexity factor.

  get_conductivity(output='eigs', doping_levels=True, relaxation_time=1e-14)

    Get the conductivity (1/Ohm*m) in either a full 3x3 tensor form, as 3 eigenvalues, or as the average value (trace/3.0) If doping_levels=True, the results are given at different p and n doping levels (given by self.doping), otherwise it is given as a series of electron chemical potential values.

    Parameters:

      - output (str) – the type of output. ‘tensor’ give the full

      - tensor (3x3)

      - and ('eigs' its 3 eigenvalues)

      - eigenvalues ('average' the average of the three)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

      - relaxation_time (float) – constant relaxation time in secs

    Returns:

      {‘p’:[],’n’:[]}}. The ‘p’ links to conductivity at p-type doping and ‘n’ to the conductivity at n-type doping. Otherwise, returns a {temp:[]} dictionary. The result contains either the sorted three eigenvalues of the symmetric conductivity tensor (format=’eigs’) or a full tensor (3x3 array) (output=’tensor’) or as an average (output=’average’). The result includes a given constant relaxation time

      units are 1/Ohm*m

    Return type:

      If doping_levels=True, a dictionary {temp

  get_extreme(target_prop: Literal['seebeck', 'power factor', 'conductivity', 'kappa', 'zt'], maximize: bool = True, min_temp: float | None = None, max_temp: float | None = None, min_doping: float | None = None, max_doping: float | None = None, isotropy_tolerance: float = 0.05, use_average: bool = True) → dict[Literal['p', 'n', 'best'], dict[str, Any]]

    Use eigenvalues over a range of carriers, temperatures, and doping levels, to estimate the “best” value that can be achieved for the given target_property. Note that this method searches the doping dict only, not the full mu dict.

    Parameters:

      - target_prop ("seebeck", "power factor", "conductivity", "kappa", "zt") – target property.

      - maximize (bool) – True to maximize, False to minimize (e.g. kappa)

      - min_temp (float) – minimum temperature allowed

      - max_temp (float) – maximum temperature allowed

      - min_doping (float) – minimum doping allowed (e.g., 1E18)

      - max_doping (float) – maximum doping allowed (e.g., 1E20)

      - isotropy_tolerance (float) – tolerance for isotropic (0.05 = 5%)

      - use_average (bool) – True for average of eigenval, False for max eigenval.

    Returns:

      {“p”, “n”, “best”}. Each key maps to a sub-dictionary with the following keys:

      > {“value”, “temperature”, “doping”, “isotropic”, “carrier_type”}.

    Return type:

      A dictionary with the following keys

  get_hall_carrier_concentration()

    Get the Hall carrier concentration (in cm^-3). This is the trace of the Hall tensor (see BoltzTraP source code) Hall carrier concentration are not always exactly the same than carrier concentration.

    Returns:

      []} with an array of Hall carrier concentration (in cm^-3) at each temperature The array relates to each step of electron chemical potential

    Return type:

      a dictionary {temp

  get_mu_bounds(temp=300)
    Parameters:

      temp – Temperature.

    Returns:

      The chemical potential bounds at that temperature.

  get_power_factor(output='eigs', doping_levels=True, relaxation_time=1e-14)

    Get the power factor (Seebeck^2 * conductivity) in units microW/(m*K^2) in either a full 3x3 tensor form, as 3 eigenvalues, or as the average value (trace/3.0) If doping_levels=True, the results are given at different p and n doping levels (given by self.doping), otherwise it is given as a series of electron chemical potential values.

    Parameters:

      - output (str) – the type of output. ‘tensor’ give the full 3x3

      - tensor

      - and ('eigs' its 3 eigenvalues)

      - eigenvalues ('average' the average of the three)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

      - relaxation_time (float) – constant relaxation time in secs

    Returns:

      {‘p’:[],’n’:[]}}. The ‘p’ links to power factor at p-type doping and ‘n’ to the conductivity at n-type doping. Otherwise, returns a {temp:[]} dictionary. The result contains either the sorted three eigenvalues of the symmetric power factor tensor (format=’eigs’) or a full tensor (3x3 array) ( output=’tensor’) or as an average (output=’average’). The result includes a given constant relaxation time

      units are microW/(m K^2)

    Return type:

      If doping_levels=True, a dictionary {temp

  get_seebeck(output='eigs', doping_levels=True)

    Get the seebeck coefficient (microV/K) in either a full 3x3 tensor form, as 3 eigenvalues, or as the average value (trace/3.0) If doping_levels=True, the results are given at different p and n doping levels (given by self.doping), otherwise it is given as a series of electron chemical potential values.

    Parameters:

      - output (str) – the type of output. ‘tensor’ give the full

      - tensor (3x3)

      - and ('eigs' its 3 eigenvalues)

      - eigenvalues ('average' the average of the three)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

    Returns:

      {‘p’:[],’n’:[]}}. The ‘p’ links to Seebeck at p-type doping and ‘n’ to the Seebeck at n-type doping. Otherwise, returns a {temp:[]} dictionary The result contains either the sorted three eigenvalues of the symmetric Seebeck tensor (output=’eigs’) or a full tensor (3x3 array) ( output=’tensor’) or as an average (output=’average’).

      units are microV/K

    Return type:

      If doping_levels=True, a dictionary {temp

  get_seebeck_eff_mass(output='average', temp=300, doping_levels=False, Lambda=0.5)

    Seebeck effective mass calculated as explained in Ref. Gibbs, Z. M. et al., Effective mass and fermi surface complexity factor from ab initio band structure calculations. npj Computational Materials 3, 8 (2017).

    Parameters:

      - output – ‘average’ returns the seebeck effective mass calculated using the average of the three diagonal components of the seebeck tensor. ‘tensor’ returns the seebeck effective mass respect to the three diagonal components of the seebeck tensor.

      - doping_levels – False means that the seebeck effective mass is calculated for every value of the chemical potential True means that the seebeck effective mass is calculated for every value of the doping levels for both n and p types

      - temp – temperature of calculated seebeck.

      - Lambda – fitting parameter used to model the scattering (0.5 means constant relaxation time).

    Returns:

      a list of values for the seebeck effective mass w.r.t the chemical potential, if doping_levels is set at False; a dict with n an p keys that contain a list of values for the seebeck effective mass w.r.t the doping levels, if doping_levels is set at True; if ‘tensor’ is selected, each element of the lists is a list containing the three components of the seebeck effective mass.

  get_symm_bands(structure: Structure, efermi, kpt_line=None, labels_dict=None)

    Useful to read bands from BoltzTraP output and get a BandStructureSymmLine object comparable with that one from a DFT calculation (if the same kpt_line is provided). Default kpt_line and labels_dict is the standard path of high symmetry k-point for the specified structure. They could be extracted from the BandStructureSymmLine object that you want to compare with. efermi variable must be specified to create the BandStructureSymmLine object (usually it comes from DFT or BoltzTraP calc).

  get_thermal_conductivity(output='eigs', doping_levels=True, k_el=True, relaxation_time=1e-14)

    Get the electronic part of the thermal conductivity in either a full 3x3 tensor form, as 3 eigenvalues, or as the average value (trace/3.0) If doping_levels=True, the results are given at different p and n doping levels (given by self.doping), otherwise it is given as a series of electron chemical potential values.

    Parameters:

      - output (str) – the type of output. ‘tensor’ give the full 3x3

      - tensor

      - and ('eigs' its 3 eigenvalues)

      - eigenvalues ('average' the average of the three)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

      - k_el (bool) – True for k_0-PF*T, False for k_0

      - relaxation_time (float) – constant relaxation time in secs

    Returns:

      {‘p’:[],’n’:[]}}. The ‘p’ links to thermal conductivity at p-type doping and ‘n’ to the thermal conductivity at n-type doping. Otherwise, returns a {temp:[]} dictionary. The result contains either the sorted three eigenvalues of the symmetric conductivity tensor (format=’eigs’) or a full tensor (3x3 array) ( output=’tensor’) or as an average (output=’average’). The result includes a given constant relaxation time

      units are W/mK

    Return type:

      If doping_levels=True, a dictionary {temp

  get_zt(output='eigs', doping_levels=True, relaxation_time=1e-14, k_l=1)

    Get the ZT coefficient (S^2*cond*T/thermal cond) in either a full 3x3 tensor form, as 3 eigenvalues, or as the average value (trace/3.0) If doping_levels=True, the results are given at different p and n doping levels (given by self.doping), otherwise it is given as a series of electron chemical potential values. We assume a constant relaxation time and a constant lattice thermal conductivity.

    Parameters:

      - output (str) – the type of output. ‘tensor’ give the full 3x3

      - tensor

      - and ('eigs' its 3 eigenvalues)

      - eigenvalues ('average' the average of the three)

      - doping_levels (bool) – True for the results to be given at

      - levels (different doping)

      - results (False for)

      - potentials (at different electron chemical)

      - relaxation_time (float) – constant relaxation time in secs

      - k_l (float) – lattice thermal cond in W/(m*K)

    Returns:

      {‘p’:[],’n’:[]}}. The ‘p’ links to ZT at p-type doping and ‘n’ to the ZT at n-type doping. Otherwise, returns a {temp:[]} dictionary. The result contains either the sorted three eigenvalues of the symmetric ZT tensor (format=’eigs’) or a full tensor (3x3 array) ( output=’tensor’) or as an average (output=’average’). The result includes a given constant relaxation time and lattice thermal conductivity

    Return type:

      If doping_levels=True, a dictionary {temp

  static parse_cond_and_hall(path_dir, doping_levels=None)

    Parse the conductivity and Hall tensors.

    Parameters:

      - path_dir – Path containing .condtens / .halltens files

      - doping_levels – ([float]) - doping lvls, parse outtrans to get this.

    Returns:

      mu_steps, cond, seebeck, kappa, hall, pn_doping_levels, mu_doping, seebeck_doping, cond_doping, kappa_doping, hall_doping, carrier_conc

  static parse_intrans(path_dir)

    Parse boltztrap.intrans mainly to extract the value of scissor applied to the bands or some other inputs.

    Parameters:

      path_dir – (str) dir containing the boltztrap.intrans file

    Returns:

      various inputs that had been used in the BoltzTraP run.

    Return type:

      dict

  static parse_outputtrans(path_dir)

    Parse .outputtrans file.

    Parameters:

      path_dir – dir containing boltztrap.outputtrans

    Returns:

      tuple - (run_type, warning, efermi, gap, doping_levels)

  static parse_struct(path_dir)

    Parse boltztrap.struct file (only the volume).

    Parameters:

      path_dir – (str) dir containing the boltztrap.struct file

    Returns:

      volume of the structure in Angstrom^3

    Return type:

      float

  static parse_transdos(path_dir, efermi, dos_spin=1, trim_dos=False)

    Parse .transdos (total DOS) and .transdos_x_y (partial DOS) files.

    Parameters:

      - path_dir – (str) dir containing DOS files

      - efermi – (float) Fermi energy

      - dos_spin – (int) -1 for spin down, +1 for spin up

      - trim_dos – (bool) whether to post-process / trim DOS.

    Returns:

      tuple - (DOS, dict of partial DOS)

exception BoltztrapError

  Bases: `Exception`

  Exception class for boltztrap. Raised when the boltztrap gives an error.

class BoltztrapRunner(bs, nelec, dos_type='HISTO', energy_grid=0.005, lpfac=10, run_type='BOLTZ', band_nb=None, tauref=0, tauexp=0, tauen=0, soc=False, doping=None, energy_span_around_fermi=1.5, scissor=0.0, kpt_line=None, spin=None, cond_band=False, tmax=1300, tgrid=50, symprec=0.001, cb_cut=10, timeout=7200)

  Bases: `MSONable`

  This class is used to run BoltzTraP on a band structure object.

  Parameters:

    - bs – A band structure object

    - nelec – the number of electrons

    - dos_type – two options for the band structure integration: “HISTO” (histogram) or “TETRA” using the tetrahedon method. TETRA typically gives better results (especially for DOSes) but takes more time

    - energy_grid – the energy steps used for the integration (eV)

    - lpfac – the number of interpolation points in the real space. By default 10 gives 10 time more points in the real space than the number of kpoints given in reciprocal space

    - run_type – type of boltztrap usage. by default - BOLTZ: (default) compute transport coefficients - BANDS: interpolate all bands contained in the energy range specified in energy_span_around_fermi variable, along specified k-points - DOS: compute total and partial dos (custom BoltzTraP code needed!) - FERMI: compute fermi surface or more correctly to get certain bands interpolated

    - band_nb – indicates a band number. Used for Fermi Surface interpolation (run_type=”FERMI”)

    - spin – specific spin component (1: up, -1: down) of the band selected in FERMI mode (mandatory).

    - cond_band – if a conduction band is specified in FERMI mode, set this variable as True

    - tauref – reference relaxation time. Only set to a value different than zero if we want to model beyond the constant relaxation time.

    - tauexp – exponent for the energy in the non-constant relaxation time approach

    - tauen – reference energy for the non-constant relaxation time approach

    - soc – results from spin-orbit coupling (soc) computations give typically non-polarized (no spin up or down) results but single electron occupations. If the band structure comes from a soc computation, you should set soc to True (default False)

    - doping – the fixed doping levels you want to compute. BoltzTraP provides both transport values depending on electron chemical potential (fermi energy) and for a series of fixed carrier concentrations. By default, this is set to 1e16 to 1e22 in increments of factors of 10.

    - energy_span_around_fermi – usually the interpolation is not needed on the entire energy range but on a specific range around the Fermi level. This energy gives this range in eV. by default it is 1.5 eV. If DOS or BANDS type are selected, this range is automatically set to cover the entire energy range.

    - scissor – scissor to apply to the band gap (eV). This applies a scissor operation moving the band edges without changing the band shape. This is useful to correct the often underestimated band gap in DFT. Default is 0.0 (no scissor)

    - kpt_line – list of fractional coordinates of kpoints as arrays or list of Kpoint objects for BANDS mode calculation (standard path of high symmetry k-points is automatically set as default)

    - tmax – Maximum temperature (K) for calculation (default=1300)

    - tgrid – Temperature interval for calculation (default=50)

    - symprec – 1e-3 is the default in pymatgen. If the kmesh has been generated using a different symprec, it has to be specified to avoid a “factorization error” in BoltzTraP calculation. If a kmesh that spans the whole Brillouin zone has been used, or to disable all the symmetries, set symprec to None.

    - cb_cut – by default 10% of the highest conduction bands are removed because they are often not accurate. Tune cb_cut to change the percentage (0-100) of bands that are removed.

    - timeout – overall time limit (in seconds): mainly to avoid infinite loop when trying to find Fermi levels.

  as_dict()

    MSONable dict.

  property bs

    The BandStructure.

  property nelec

    Number of electrons.

  run(path_dir=None, convergence=True, write_input=True, clear_dir=False, max_lpfac=150, min_egrid=5e-05)

    Write inputs (optional), run BoltzTraP, and ensure convergence (optional).

    Parameters:

      - path_dir (str) – directory in which to run BoltzTraP

      - convergence (bool) – whether to check convergence and make corrections if needed

      - write_input – (bool) whether to write input files before the run (required for convergence mode)

      - clear_dir – (bool) whether to remove all files in the path_dir before starting

      - max_lpfac – (float) maximum lpfac value to try before reducing egrid in convergence mode

      - min_egrid – (float) minimum egrid value to try before giving up in convergence mode

  write_def(output_file) → None

    Write the def to an output file.

    Parameters:

      output_file – Filename

  write_energy(output_file) → None

    Write the energy to an output file.

    Parameters:

      output_file – Filename

  write_input(output_dir) → None

    Write the input files.

    Parameters:

      output_dir – Directory to write the input files.

  write_intrans(output_file) → None

    Write the intrans to an output file.

    Parameters:

      output_file – Filename

  write_proj(output_file_proj: str, output_file_def: str) → None

    Write the projections to an output file.

    Parameters:

      - output_file_proj – output file name

      - output_file_def – output file name

  write_struct(output_file) → None

    Write the structure to an output file.

    Parameters:

      output_file – Filename

compare_sym_bands(bands_obj, bands_ref_obj, nb=None)

  Compute the mean of correlation between bzt and vasp bandstructure on sym line, for all bands and locally (for each branches) the difference squared (%) if nb is specified.

eta_from_seebeck(seeb, Lambda) → float

  It takes a value of seebeck and adjusts the analytic seebeck until it’s equal.

  Returns:

    eta where the two seebeck coefficients are equal (reduced chemical potential).

  Return type:

    float

read_cube_file(filename)
  Parameters:

    filename – Cube filename.

  Returns:

    Energy data.

seebeck_eff_mass_from_carr(eta, n, T, Lambda) → float

  Calculate seebeck effective mass at a certain carrier concentration eta in kB*T units, n in cm-3, T in K, returns mass in m0 units.

seebeck_eff_mass_from_seebeck_carr(seeb, n, T, Lambda) → float

  Find the chemical potential where analytic and calculated seebeck are identical and then calculate the seebeck effective mass at that chemical potential and a certain carrier concentration n.

seebeck_spb(eta, Lambda=0.5)

  Seebeck analytic formula in the single parabolic model.

## pymatgen.electronic_structure.boltztrap2 module

## pymatgen.electronic_structure.cohp module

This module defines classes to represent:

  - Crystal orbital Hamilton population (COHP) and integrated COHP (ICOHP).

  - Crystal orbital overlap population (COOP).

  - Crystal orbital bond index (COBI).

If you use this module, please cite: J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, “Automated Bonding Analysis with Crystal Orbital Hamilton Populations”, ChemPlusChem 2022, e202200123, DOI: 10.1002/cplu.202200123.

class Cohp(efermi: float, energies: ArrayLike, cohp: Mapping[Spin, NDArray], are_coops: bool = False, are_cobis: bool = False, are_multi_center_cobis: bool = False, icohp: Mapping[Spin, NDArray] | None = None)

  Bases: `MSONable`

  Basic COHP object.

  Parameters:

    - efermi (float) – The Fermi level.

    - energies (Sequence[float]) – Energies.

    - ({Spin (icohp) – NDArrary}): The COHP for each spin.

    - are_coops (bool) – Whether this object describes COOPs.

    - are_cobis (bool) – Whether this object describes COBIs.

    - are_multi_center_cobis (bool) – Whether this object describes multi-center COBIs.

    - ({Spin – NDArrary}): The ICOHP for each spin.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of COHP.

  classmethod from_dict(dct: dict[str, Any]) → Self

    Generate Cohp from a dict representation.

  get_cohp(spin: SpinLike | None = None, integrated: bool = False) → dict[Spin, NDArray] | None

    Get the COHP or ICOHP for a particular spin.

    Parameters:

      - spin (SpinLike) – Selected spin. If is None and both spins are present, both will be returned.

      - integrated – Return ICOHP (True) or COHP (False).

    Returns:

      The COHP or ICOHP for the selected spin.

    Return type:

      dict

  get_icohp(spin: SpinLike | None = None) → dict[Spin, NDArray] | None

    Convenient wrapper to get the ICOHP for a particular spin.

  get_interpolated_value(energy: float, integrated: bool = False) → dict[Spin, float]

    Get the interpolated COHP for a particular energy.

    Parameters:

      - energy (float) – Energy to get the COHP value for.

      - integrated (bool) – Return ICOHP (True) or COHP (False).

  has_antibnd_states_below_efermi(spin: SpinLike | None = None, limit: float = 0.01) → dict[Spin, bool] | None

    Get dict of antibonding states below the Fermi level for the spin.

    Parameters:

      - spin (SpinLike) – Selected spin.

      - limit (float) – Only COHP higher than this value will be considered.

class CompleteCohp(structure: Structure, avg_cohp: Cohp, cohp_dict: dict[str, Cohp], bonds: dict[str, Any] | None = None, are_coops: bool = False, are_cobis: bool = False, are_multi_center_cobis: bool = False, orb_res_cohp: dict[str, dict] | None = None)

  Bases: `Cohp`

  A wrapper that defines an average COHP, and individual COHPs.

  are_coops

    Whether the object consists of COOPs.

    Type:

      bool

  are_cobis

    Whether the object consists of COBIs.

    Type:

      bool

  efermi

    The Fermi level.

    Type:

      float

  energies

    Sequence of energies.

    Type:

      Sequence[float]

  structure

    Structure associated with the COHPs.

    Type:

      Structure

  cohp

    The average COHP.

    Type:

      Sequence[float]

  icohp

    The average ICOHP.

    Type:

      Sequence[float]

  all_cohps

    COHPs for individual bonds of the form {label: COHP}.

    Type:

      dict[str, Sequence[float]]

  orb_res_cohp

    Orbital-resolved COHPs.

    Type:

      dict[str, Dict[str, Sequence[float]]]

  Parameters:

    - structure (Structure) – Structure associated with this COHP.

    - avg_cohp (Cohp) – The average COHP.

    - cohp_dict (dict[str, Cohp]) – COHP for individual bonds of the form {label: COHP}.

    - bonds (dict[str, Any]) – Information on the bonds of the form {label: {key: val}}. The value can be any information, but typically contains the sites, the bond length, and the number of bonds. If nothing is supplied, it will default to an empty dict.

    - are_coops (bool) – Whether the Cohp objects are COOPs. Defaults to False for COHPs.

    - are_cobis (bool) – Whether the Cohp objects are COBIs. Defaults to False for COHPs.

    - are_multi_center_cobis (bool) – Whether the Cohp objects are multi-center COBIs. Defaults to False for COHPs.

    - orb_res_cohp (dict) – Orbital-resolved COHPs.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of CompleteCohp.

  classmethod from_dict(dct: dict[str, Any]) → Self

    Get CompleteCohp object from a dict representation.

    TODO: Clean this up.

  classmethod from_file(fmt: Literal['LMTO', 'LOBSTER'], filename: PathLike | None = None, structure_file: PathLike | None = None, are_coops: bool = False, are_cobis: bool = False, are_multi_center_cobis: bool = False) → Self

    Create CompleteCohp from an output file of a COHP calculation.

    Parameters:

      - fmt (Literal["LMTO", "LOBSTER"]) – The code used to calculate COHPs.

      - filename (PathLike) – The COHP output file. Defaults to “COPL” for LMTO and “COHPCAR.lobster/COOPCAR.lobster” for LOBSTER.

      - structure_file (PathLike) – The file containing the structure. If None, use “CTRL” for LMTO and “POSCAR” for LOBSTER.

      - are_coops (bool) – Whether the populations are COOPs or COHPs. Defaults to False for COHPs.

      - are_cobis (bool) – Whether the populations are COBIs or COHPs. Defaults to False for COHPs.

      - are_multi_center_cobis (bool) – Whether this file includes information on multi-center COBIs.

    Returns:

      A CompleteCohp object.

  get_cohp_by_label(label: str, summed_spin_channels: bool = False) → Cohp

    Get specific Cohp by the label, to simplify plotting.

    Parameters:

      - label (str) – Label for the interaction.

      - summed_spin_channels (bool) – Sum the spin channels and return the sum as Spin.up.

    Returns:

      The Cohp.

  get_orbital_resolved_cohp(label: str, orbitals: str | list[tuple[str, Orbital]] | tuple[tuple[str, Orbital], ...], summed_spin_channels: bool = False) → Cohp | None

    Get orbital-resolved COHP.

    Parameters:

      - label (str) – Bond labels as in ICOHPLIST/ICOOPLIST.lobster.

      - orbitals – The orbitals as a label, or list/tuple of [(n1, orbital1), (n2, orbital2), …]. Where each orbital can either be str, int, or Orbital.

      - summed_spin_channels (bool) – Sum the spin channels and return the sum as Spin.up.

    Returns:

      A Cohp object if CompleteCohp contains orbital-resolved COHP,

        or None if it doesn’t.

    Note: It currently assumes that orbitals are str if they aren’t the

      other valid types. This is not ideal, but is the easiest way to avoid unicode issues between Python 2 and Python 3.

  get_summed_cohp_by_label_and_orbital_list(label_list: list[str], orbital_list: list[str], divisor: float = 1, summed_spin_channels: bool = False) → Cohp

    Get a Cohp object that includes a summed COHP divided by divisor.

    Parameters:

      - label_list (list[str]) – Labels for the COHP that should be included.

      - orbital_list (list[str]) – Orbitals for the COHPs that should be included (same order as label_list).

      - divisor (float) – The summed COHP will be divided by this divisor.

      - summed_spin_channels (bool) – Sum the spin channels and return the sum in Spin.up.

    Returns:

      A Cohp object including the summed COHP.

  get_summed_cohp_by_label_list(label_list: list[str], divisor: float = 1, summed_spin_channels: bool = False) → Cohp

    Get a Cohp object that includes a summed COHP divided by divisor.

    Parameters:

      - label_list (list[str]) – Labels for the COHP to include.

      - divisor (float) – The summed COHP will be divided by this divisor.

      - summed_spin_channels (bool) – Sum the spin channels and return the sum in Spin.up.

    Returns:

      A Cohp object for the summed COHP.

class IcohpCollection(list_labels: list[str], list_atom1: list[str], list_atom2: list[str], list_length: list[float], list_translation: list[tuple[int, int, int]], list_num: list[int], list_icohp: list[dict[Spin, float]], is_spin_polarized: bool, list_orb_icohp: list[dict[str, dict[Literal['icohp', 'orbitals'], Any]]] | None = None, are_coops: bool = False, are_cobis: bool = False)

  Bases: `MSONable`

  Collection of IcohpValues.

  are_coops

    Whether these are ICOOPs.

    Type:

      bool

  are_cobis

    Whether these are ICOOPs.

    Type:

      bool

  is_spin_polarized

    Whether the calculation is spin polarized.

    Type:

      bool

  Parameters:

    - list_labels (list[str]) – Labels for ICOHP/ICOOP values.

    - list_atom1 (list[str]) – Atom names, e.g. “O1”.

    - list_atom2 (list[str]) – Atom names, e.g. “O1”.

    - list_length (list[float]) – Bond lengths in Angstrom.

    - list_translation (list[tuple[int, int, int]]) – Cell translation vectors.

    - list_num (list[int]) – Numbers of equivalent bonds, usually 1 starting from LOBSTER 3.0.0.

    - list_icohp (list[dict]) – Dicts as {Spin.up: ICOHP_up, Spin.down: ICOHP_down}.

    - is_spin_polarized (bool) – Whether the calculation is spin polarized.

    - list_orb_icohp (list[dict]) – Dicts as {[str(Orbital1)-str(Orbital2)]: { “icohp”: {Spin.up: IcohpValue for spin.up, Spin.down: IcohpValue for spin.down}, “orbitals”: [Orbital1, Orbital2]}.

    - are_coops (bool) – Whether ICOOPs are stored.

    - are_cobis (bool) – Whether ICOBIs are stored.

  property are_cobis: bool

    Whether this is COBI.

  property are_coops: bool

    Whether this is COOP.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of COHP.

  extremum_icohpvalue(summed_spin_channels: bool = True, spin: Spin = Spin.up) → float

    Get ICOHP/ICOOP of the strongest bond.

    Parameters:

      - summed_spin_channels (bool) – Whether the ICOHPs/ICOOPs of both spin channels should be summed.

      - spin (Spin) – If not summed_spin_channels, this indicates which spin channel should be returned.

    Returns:

      Lowest ICOHP/largest ICOOP value (i.e. ICOHP/ICOOP value of strongest bond).

  classmethod from_dict(dct: dict[str, Any]) → Self

    Generate IcohpCollection from a dict representation.

  get_icohp_by_label(label: str, summed_spin_channels: bool = True, spin: Spin = Spin.up, orbitals: str | tuple[Orbital, Orbital] | None = None) → float

    Get an ICOHP value for a certain bond indicated by the label.

    Parameters:

      - label (str) – The bond number in Icohplist.lobster/Icooplist.lobster, starting from “1”.

      - summed_spin_channels (bool) – Whether the ICOHPs/ICOOPs of both spin channels should be summed.

      - spin (Spin) – If not summed_spin_channels, indicate which spin channel should be returned.

      - orbitals – List of Orbital or “str(Orbital1)-str(Orbital2)”.

    Returns:

      ICOHP/ICOOP value.

    Return type:

      float

  get_icohp_dict_by_bondlengths(minbondlength: float = 0.0, maxbondlength: float = 8.0) → dict[str, IcohpValue]

    Get IcohpValues within certain bond length range.

    Parameters:

      - minbondlength (float) – The minimum bond length.

      - maxbondlength (float) – The maximum bond length.

    Returns:

      Keys are the labels from the initial list_labels.

    Return type:

      dict[str, IcohpValue]

  get_icohp_dict_of_site(site: int, minsummedicohp: float | None = None, maxsummedicohp: float | None = None, minbondlength: float = 0.0, maxbondlength: float = 8.0, only_bonds_to: list[str] | None = None) → dict[str, IcohpValue]

    Get IcohpValues for a certain site.

    Parameters:

      - site (int) – The site of interest, ordered as in Icohplist.lobster/Icooplist.lobster, starts from 0.

      - minsummedicohp (float) – Minimal ICOHP/ICOOP of the bonds that are considered. It is the summed ICOHP value from both spin channels for spin polarized cases

      - maxsummedicohp (float) – Maximal ICOHP/ICOOP of the bonds that are considered. It is the summed ICOHP value from both spin channels for spin polarized cases

      - minbondlength (float) – The minimum bond length.

      - maxbondlength (float) – The maximum bond length.

      - only_bonds_to (list[str]) – The bonding partners that are allowed, e.g. [“O”].

    Returns:

      Dict of IcohpValues, the keys correspond to the values from the initial list_labels.

  get_summed_icohp_by_label_list(label_list: list[str], divisor: float = 1.0, summed_spin_channels: bool = True, spin: Spin = Spin.up) → float

    Get the sum of ICOHP values.

    Parameters:

      - label_list (list[str]) – Labels of the ICOHPs/ICOOPs that should be summed, the same as in ICOHPLIST/ICOOPLIST.

      - divisor (float) – Divisor used to divide the sum.

      - summed_spin_channels (bool) – Whether the ICOHPs/ICOOPs of both spin channels should be summed.

      - spin (Spin) – If not summed_spin_channels, indicate which spin channel should be returned.

    Returns:

      Sum of ICOHPs selected with label_list.

    Return type:

      float

  property is_spin_polarized: bool

    Whether this is spin polarized.

class IcohpValue(label: str, atom1: str, atom2: str, length: float, translation: tuple[int, int, int], num: int, icohp: dict[Spin, float], are_coops: bool = False, are_cobis: bool = False, orbitals: dict[str, dict[Literal['icohp', 'orbitals'], Any]] | None = None)

  Bases: `MSONable`

  Information for an ICOHP or ICOOP value.

  energies

    Energy values for the COHP/ICOHP/COOP/ICOOP.

    Type:

      NDArray

  densities

    Density of states for the COHP/ICOHP/COOP/ICOOP.

    Type:

      NDArray

  energies_are_cartesian

    Whether the energies are cartesian.

    Type:

      bool

  are_coops

    Whether the object is COOP/ICOOP.

    Type:

      bool

  are_cobis

    Whether the object is COBIS/ICOBIS.

    Type:

      bool

  icohp

    The ICOHP/COHP values, whose keys are Spin.up and Spin.down.

    Type:

      dict

  summed_icohp

    The summed ICOHP/COHP values.

    Type:

      float

  num_bonds

    The number of bonds used for the average COHP (for LOBSTER versions <3.0).

    Type:

      int

  Parameters:

    - label (str) – Label for the ICOHP.

    - atom1 (str) – The first atom that contributes to the bond.

    - atom2 (str) – The second atom that contributes to the bond.

    - length (float) – Bond length.

    - translation (tuple[int, int, int]) – cell translation vector, e.g. (0, 0, 0).

    - num (int) – The number of equivalent bonds.

    - icohp (dict[Spin, float]) – {Spin.up: ICOHP_up, Spin.down: ICOHP_down}

    - are_coops (bool) – Whether these are COOPs.

    - are_cobis (bool) – Whether these are COBIs.

    - orbitals (dict) –

      {[str(Orbital1)-str(Orbital2)]: { “icohp”: {

      > > Spin.up: IcohpValue for spin.up, Spin.down: IcohpValue for spin.down

      > },

      ”orbitals”: [Orbital1, Orbital2, …]}.

  property are_cobis: bool

    Whether these are ICOBIs.

    Returns:

      bool

  property are_coops: bool

    Whether these are ICOOPs.

    Returns:

      bool

  property icohp: dict[Spin, float]

    Dict with ICOHPs for spin up and spin down.

    Returns:

      {Spin.up: ICOHP_up, Spin.down: ICOHP_down}.

    Return type:

      dict[Spin, float]

  icohpvalue(spin: Spin = Spin.up) → float
    Parameters:

      spin – Spin.up or Spin.down.

    Returns:

      ICOHP value corresponding to chosen spin.

    Return type:

      float

  icohpvalue_orbital(orbitals: tuple[Orbital, Orbital] | str, spin: Spin = Spin.up) → float
    Parameters:

      - orbitals – tuple[Orbital, Orbital] or “str(Orbital0)-str(Orbital1)”.

      - spin (Spin) – Spin.up or Spin.down.

    Returns:

      ICOHP value corresponding to chosen spin.

    Return type:

      float

  property is_spin_polarized: bool

    Whether this is a spin polarized calculation.

    Returns:

      bool

  property num_bonds: int

    The number of bonds for which the ICOHP value is an average.

    Returns:

      int

  property summed_icohp: float

    Summed ICOHPs of both spin channels if spin polarized.

    Returns:

      ICOHP value in eV.

    Return type:

      float

  property summed_orbital_icohp: dict[str, float]

    Summed orbital-resolved ICOHPs of both spin channels if spin-polarized.

    Returns:

      “str(Orbital1)-str(Ortibal2)”: ICOHP value in eV.

    Return type:

      dict[str, float]

  property translation: tuple[int, int, int]

    Returns the translation vector with respect to the origin cell as defined in LOBSTER.

    Returns:

      tuple[int, int, int]

get_integrated_cohp_in_energy_range(cohp: CompleteCohp, label: str, orbital: str | None = None, energy_range: float | tuple[float, float] | None = None, relative_E_Fermi: bool = True, summed_spin_channels: bool = True) → float | dict[Spin, float]

  Integrate CompleteCohps which include data of integrated COHPs (ICOHPs).

  Parameters:

    - cohp (CompleteCohp) – CompleteCohp object.

    - label (str) – Label of the COHP data.

    - orbital (str) – If not None, a orbital resolved integrated COHP will be returned.

    - energy_range – If None, return the ICOHP value at Fermi level. If float, integrate from this value up to Fermi level. If (float, float), integrate in between.

    - relative_E_Fermi (bool) – Whether energy scale with Fermi level at 0 eV is chosen.

    - summed_spin_channels (bool) – Whether Spin channels will be summed.

  Returns:

    float: the ICOHP. else:

    > dict: {Spin.up: float, Spin.down: float}

  Return type:

    If summed_spin_channels

## pymatgen.electronic_structure.core module

This module provides core classes to define electronic structure, including Spin, Orbital and Magmom.

class Magmom(moment: MagMomentLike, saxis: ArrayLike = (0, 0, 1))

  Bases: `MSONable`

  In active development. Use with caution, feedback is appreciated.

  Class to handle magnetic moments. Define the magnetic moment of a site or species relative to a spin quantization axis. Designed for use in electronic structure calculations.

  > - For the general case, Magmom can be specified by a 3D vector,

  > e.g. m = Magmom([1.0, 1.0, 2.0]), and indexing will work as expected, e.g. m[0] gives 1.0.

  > - For collinear calculations, Magmom can assumed to be float-like,

  > e.g. m = Magmom(5.0) will work as expected, e.g. float(m) gives 5.0.

  Both cases should be safe and shouldn’t give any surprise, and more advanced functionality is available if required.

  There are also static methods for sequences of magmoms:

  > - Magmom.are_collinear(magmoms) - If True, a collinear electronic

  > structure calculation can be safely initialized, with float(Magmom) giving the expected scalar magnetic moment value.

  > - Magmom.get_consistent_set_and_saxis(magmoms) - For non-collinear

  > electronic structure calculations, a global and consistent spin axis has to be used. This method returns a list of Magmoms which all share a common spin axis, along with the global spin axis.

  All methods that take sequence of magmoms will accept either Magmom objects, or as scalars/lists and will automatically convert to Magmom representations internally.

  The following methods are also useful for VASP calculations:

    - Magmom.get_xyz_magmom_with_001_saxis()

    - Magmom.get_00t_magmom_with_xyz_saxis()

    See VASP documentation for more information:

      https://cms.mpi.univie.ac.at/wiki/index.php/SAXIS

  Parameters:

    - moment (float | Sequence[float] | NDArray, Magmom) – Magnetic moment.

    - saxis (tuple[float, float, float]) – Spin axis, and will be converted to unit vector (default is (0, 0, 1)).

  static are_collinear(magmoms: Sequence[MagMomentLike]) → bool

    Check if a list of magnetic moments are collinear with each other.

    Parameters:

      magmoms (Sequence[MagMomentLike]) – Magmoms, floats or vectors.

    Returns:

      bool.

  classmethod from_global_moment_and_saxis(global_moment: MagMomentLike, saxis: tuple[float, float, float]) → Self

    Initialize Magmom from a given global magnetic moment, i.e. magnetic moment with saxis=(0, 0, 1), and provided saxis.

    Method is useful if you do not know the components of your magnetic moment in frame of your desired spin axis.

    Parameters:

      - global_moment (MagMomentLike) – Global magnetic moment.

      - saxis (tuple[float, float, float]) – Spin axis.

  classmethod from_moment_relative_to_crystal_axes(moment: tuple[float, float, float], lattice: Lattice) → Self

    Obtain a Magmom object from a magnetic moment provided relative to crystal axes.

    Used for obtaining moments from magCIF file.

    Parameters:

      - moment (tuple[float, float, float]) – Magnetic moment.

      - lattice (Lattice) – Lattice.

    Returns:

      Magmom

  get_00t_magmom_with_xyz_saxis() → Self

    For internal implementation reasons, the non-collinear calculations in VASP prefer the following.

    > MAGMOM = 0 0 total_magnetic_moment SAXIS = x y z

    to an equivalent:

    > MAGMOM = x y z SAXIS = 0 0 1

    Returns:

      With magnetic moment (0, 0, t), where t is the total magnetic

        moment, and saxis rotated as required.

        A consistent direction of saxis is applied such that t might be positive or negative depending on the direction of the initial moment. This is useful in the case of collinear structures, rather than assuming t is always positive.

    Return type:

      Magmom

  static get_consistent_set_and_saxis(magmoms: Sequence[MagMomentLike], saxis: tuple[float, float, float] | None = None) → tuple[list[NDArray], NDArray]

    Ensure magmoms use the same spin axis.

    Parameters:

      - magmoms (Sequence[MagMomentLike]) – Magmoms, floats or vectors.

      - saxis (tuple[float, float, float]) – An optional global spin axis.

    Returns:

      Magmoms and their global spin axes.

    Return type:

      tuple[list[Magmom], NDArray]

  get_moment(saxis: tuple[float, float, float] = (0, 0, 1)) → NDArray

    Get magnetic moment relative to a given spin quantization axis. If no axis is provided, moment will be given relative to the Magmom’s internal spin quantization axis, i.e. equivalent to Magmom.moment.

    Parameters:

      saxis (tuple[float, float, float]) – Spin quantization axis.

    Returns:

      NDArray of length 3.

  get_moment_relative_to_crystal_axes(lattice: Lattice) → tuple[float, float, float]

    If scalar magmoms, moments will be given arbitrarily along z.

    Used for writing moments to magCIF file.

    Parameters:

      lattice (Lattice) – The lattice.

    Returns:

      tuple[float, float, float]

  static get_suggested_saxis(magmoms: Sequence[MagMomentLike]) → NDArray

    Get a suggested spin axis for magmoms, taking the largest magnetic moment as the reference. For calculations with collinear spins, this would give a sensible saxis for a NCL calculation.

    Parameters:

      magmoms (Sequence[MagMomentLike]) – Magmoms, floats or vectors.

    Returns:

      NDArray of length 3

  get_xyz_magmom_with_001_saxis() → Self

    Get a Magmom in the default setting of saxis = (0, 0, 1) and the magnetic moment rotated as required.

    Returns:

      Magmom

  property global_moment: NDArray

    The magnetic moment defined in an arbitrary global reference frame, as a np.array of length 3.

  static have_consistent_saxis(magmoms: Sequence[MagMomentLike]) → bool

    Check whether all Magmoms have a consistent spin quantization axis.

    To write MAGMOM tags to a VASP INCAR, a consistent global SAXIS value for all magmoms has to be used.

    If spin axes are inconsistent, can create a consistent set with:

      Magmom.get_consistent_set(magmoms).

    Parameters:

      magmoms (Sequence[MagMomentLike]) – Magmoms.

    Returns:

      bool

  property projection: float

    Project moment along spin quantization axis.

    Useful for obtaining collinear approximation for slightly non-collinear magmoms.

    Returns:

      The projected moment.

    Return type:

      float

class Orbital(value)

  Bases: `Enum`

  Enum type for specific orbitals. The indices are the order in which the orbitals are reported in VASP and has no special meaning.

  dx2 = 8
  dxy = 4
  dxz = 7
  dyz = 5
  dz2 = 6
  f0 = 12
  f1 = 13
  f2 = 14
  f3 = 15
  f_1 = 11
  f_2 = 10
  f_3 = 9
  property orbital_type: OrbitalType

    OrbitalType of an orbital.

  px = 3
  py = 1
  pz = 2
  s = 0

class OrbitalType(value)

  Bases: `Enum`

  Enum type for orbital type. Indices are the azimuthal quantum number l.

  d = 2
  f = 3
  p = 1
  s = 0

class Spin(value)

  Bases: `Enum`

  Enum type for Spin. Only up and down. Usage: Spin.up, Spin.down.

  down = -1
  up = 1

## pymatgen.electronic_structure.dos module

This module defines classes to represent the density of states (DOS), etc.

class CompleteDos(structure: Structure, total_dos: Dos, pdoss: Mapping[PeriodicSite, Mapping[Orbital, Mapping[Spin, ArrayLike]]], normalize: bool = False)

  Bases: `Dos`

  Define total DOS, and projected DOS (PDOS).

  Mainly used by pymatgen.io.vasp.Vasprun to create a complete DOS from a vasprun.xml file. You are unlikely to generate this object manually.

  structure

    Structure associated with the CompleteDos.

    Type:

      Structure

  pdos

    PDOS.

    Type:

      dict[PeriodicSite, dict[Orbital, dict[Spin, NDArray]]]

  Parameters:

    - structure (Structure) – Structure associated with this DOS.

    - total_dos (Dos) – Total DOS for the structure.

    - pdoss (dict) – The PDOSs supplied as {Site: {Orbital: {Spin: Densities}}}.

    - normalize (bool) – Whether to normalize the DOS by the volume of the structure. If True, the units of the DOS are states/eV/Angstrom^3. Otherwise, the units are states/eV.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of CompleteDos.

  static fp_to_dict(fp: DosFingerprint) → dict[str, NDArray]

    Convert a DOS FingerPrint into a dict.

    Parameters:

      fp (DosFingerprint) – The DOS FingerPrint to convert.

    Returns:

      The FingerPrint as dict.

    Return type:

      dict(Keys=type, Values=np.array(energies, densities))

  classmethod from_dict(dct: dict) → Self

    Get CompleteDos object from dict representation.

  get_band_center(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None) → float

    Compute the orbital-projected band center, defined as the first moment relative to the Fermi level as:

    > int_{-inf}^{+inf} rho(E)*E dE/int_{-inf}^{+inf} rho(E) dE.

    Note that the band center is often highly sensitive to the selected energy range.

    “elements” and “sites” cannot be used together.

    References

    Hammer and Norskov, Surf. Sci., 343 (1995).

    Parameters:

      - band (OrbitalType) – Orbital to get the band center of (default is d-band)

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. If None, both spin channels will be combined.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

    Returns:

      The band center in eV, often denoted epsilon_d for the d-band center.

    Return type:

      float

  get_band_filling(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None) → float

    Compute the orbital-projected band filling, defined as the zeroth moment up to the Fermi level.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbital to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. If None, both spin channels will be combined.

    Returns:

      Band filling in eV, often denoted f_d for the d-band.

    Return type:

      float

  get_band_kurtosis(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None) → float
    Get the orbital-projected kurtosis, defined as the fourth standardized moment

      int_{-inf}^{+inf} rho(E)*(E-E_center)^4 dE/int_{-inf}^{+inf} rho(E) dE) / (int_{-inf}^{+inf} rho(E)*(E-E_center)^2 dE/int_{-inf}^{+inf} rho(E) dE))^2

    where E_center is the orbital-projected band center.

    Note that the kurtosis is often highly sensitive to the selected energy range.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbitals to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. By default, both spin channels will be combined.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

    Returns:

      The orbital-projected kurtosis (dimensionless).

    Return type:

      float

  get_band_skewness(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None) → float
    Get the orbital-projected skewness, defined as the third standardized moment:

      int_{-inf}^{+inf} rho(E)*(E-E_center)^3 dE/int_{-inf}^{+inf} rho(E) dE) / (int_{-inf}^{+inf} rho(E)*(E-E_center)^2 dE/int_{-inf}^{+inf} rho(E) dE))^(3/2)

    where E_center is the orbital-projected band center.

    Note that the skewness is often highly sensitive to the selected energy range.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbitals to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. By default, both spin channels will be combined.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

    Returns:

      The orbital-projected skewness (dimensionless).

    Return type:

      float

  get_band_width(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None) → float

    Get the orbital-projected band width, defined as the square root of the second moment:

    > sqrt(int_{-inf}^{+inf} rho(E)*(E-E_center)^2 dE/int_{-inf}^{+inf} rho(E) dE)

    where E_center is the orbital-projected band center.

    Note that the band width is often highly sensitive to the selected energy range.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbital to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. By default, both spin channels will be combined.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

    Returns:

      Orbital-projected band width in eV.

    Return type:

      float

  get_dos_fp(fp_type: str = 'summed_pdos', binning: bool = True, min_e: float | None = None, max_e: float | None = None, n_bins: int = 256, normalize: bool = True) → DosFingerprint

    Generate the DOS fingerprint.

    Based on the work of:

      F. Knoop, T. A. r Purcell, M. Scheffler, C. Carbogno, J. Open Source Softw. 2020, 5, 2671. Source - https://gitlab.com/vibes-developers/vibes/-/tree/master/vibes/materials_fp Copyright (c) 2020 Florian Knoop, Thomas A.R.Purcell, Matthias Scheffler, Christian Carbogno. Please also see and cite related work by: M. Kuban, S. Rigamonti, C. Draxl, Digital Discovery 2024, 3, 2448.

    Parameters:

      - fp_type (str) – The FingerPrint type, can be “{s/p/d/f/summed}_{pdos/tdos}” (default is summed_pdos).

      - binning (bool) – Whether to bin the DOS FingerPrint using np.linspace and n_bins. Default is True.

      - min_e (float) – The minimum energy to include (default is None).

      - max_e (float) – The maximum energy to include (default is None).

      - n_bins (int) – Number of bins to be used, if binning (default is 256).

      - normalize (bool) – Whether to normalize the integrated DOS to 1. Default is True.

    Raises:

      ValueError – If “fp_type” is not one of the accepted values.

    Returns:

      The DOS fingerprint.

    Return type:

      DosFingerprint(energies, densities, type, n_bins)

  static get_dos_fp_similarity(fp1: DosFingerprint, fp2: DosFingerprint, col: int = 1, pt: int | Literal['All'] = 'All', normalize: bool = False, metric: Literal['tanimoto', 'wasserstein', 'cosine-sim'] = 'tanimoto') → float

    Calculate the similarity index (dot product) of two DOS FingerPrints.

    Parameters:

      - fp1 (DosFingerprint) – The 1st dos fingerprint object

      - fp2 (DosFingerprint) – The 2nd dos fingerprint object

      - col (int) – The item in the fingerprints (0:energies,1: densities) to compute the similarity index of (default is 1)

      - pt (int or str) – The index of the point that the dot product is to be taken (default is All)

      - normalize (bool) – If True normalize the scalar product to 1 (default is False)

      - metric (Literal) – Metric used to compute similarity default is “tanimoto”.

    Raises:

      - ValueError – If metric other than tanimoto, wasserstein and “cosine-sim” is requested.

      - ValueError – If normalize is set to True along with the metric.

    Returns:

      Similarity index given by the dot product.

    Return type:

      float

  get_element_dos() → dict[SpeciesLike, Dos]

    Get element projected DOS.

    Returns:

      dict[Element, Dos]

  get_element_spd_dos(el: SpeciesLike) → dict[OrbitalType, Dos]

    Get element and orbital (spd) projected DOS.

    Parameters:

      el (SpeciesLike) – Element associated with CompleteDos.

    Returns:

      dict[OrbitalType, Dos]

  get_hilbert_transform(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None) → Dos

    Get the Hilbert transform of the orbital-projected DOS, often plotted for a Newns-Anderson analysis.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbital to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

    Returns:

      Hilbert transformation of the projected DOS.

    Return type:

      Dos

  get_n_moment(n: int, band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None, center: bool = True) → float

    Get the nth moment of the DOS centered around the orbital-projected band center, defined as:

    > int_{-inf}^{+inf} rho(E)*(E-E_center)^n dE/int_{-inf}^{+inf} rho(E) dE

    where n is the order, E_center is the orbital-projected band center, and E is the set of energies taken with respect to the Fermi level.

    “elements” and “sites” cannot be used together.

    Parameters:

      - n (int) – The order for the moment.

      - band (OrbitalType) – Orbital to get the band center of (default is d-band).

      - elements (list[PeriodicSite]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. By default, both spin channels will be combined.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

      - center (bool) – Take moments with respect to the band center.

    Returns:

      Orbital-projected nth moment in eV

  get_normalized() → Self

    Get normalized CompleteDos.

  get_site_dos(site: PeriodicSite) → Dos

    Get the total DOS for a site with all orbitals.

    Parameters:

      site (PeriodicSite) – Site in Structure associated with CompleteDos.

    Returns:

      Total DOS for a site with all orbitals.

    Return type:

      Dos

  get_site_orbital_dos(site: PeriodicSite, orbital: Orbital) → Dos

    Get the Dos for a particular orbital of a particular site.

    Parameters:

      - site – Site in Structure associated with CompleteDos.

      - orbital – Orbital in the site.

    Returns:

      for a particular orbital of a particular site.

    Return type:

      Dos

  get_site_spd_dos(site: PeriodicSite) → dict[OrbitalType, Dos]

    Get orbital projected DOS of a particular site.

    Parameters:

      site (PeriodicSite) – Site in Structure associated with CompleteDos.

    Returns:

      dict[OrbitalType, Dos]

  get_site_t2g_eg_resolved_dos(site: PeriodicSite) → dict[Literal['e_g', 't2g'], Dos]

    Get the t2g/e_g projected DOS for a particular site.

    Parameters:

      site (PeriodicSite) – Site in Structure associated with CompleteDos.

    Returns:

      Summed e_g and t2g DOS for the site.

    Return type:

      dict[Literal[“e_g”, “t2g”], Dos]

  get_spd_dos() → dict[OrbitalType, Dos]

    Get orbital projected DOS.

    Returns:

      dict[OrbitalType, Dos]

  get_upper_band_edge(band: OrbitalType = OrbitalType.d, elements: list[SpeciesLike] | None = None, sites: list[PeriodicSite] | None = None, spin: Spin | None = None, erange: tuple[float, float] | None = None) → float

    Get the orbital-projected upper band edge.

    The definition by Xin et al. Phys. Rev. B, 89, 115114 (2014) is used, which is the highest peak position of the Hilbert transform of the orbital-projected DOS.

    “elements” and “sites” cannot be used together.

    Parameters:

      - band (OrbitalType) – Orbital to get the band center of (default is d-band).

      - elements (list[SpeciesLike]) – Elements to get the band center of.

      - sites (list[PeriodicSite]) – Sites to get the band center of.

      - spin (Spin) – Spin channel to use. Both spin channels will be combined by default.

      - erange (tuple(min, max)) – The energy range to consider, with respect to the Fermi level. Default to None for all energies.

    Returns:

      Upper band edge in eV, often denoted epsilon_u.

    Return type:

      float

  property spin_polarization: float | None

    Spin polarization at Fermi level.

    Examples

    See Sanvito et al., DOI: 10.1126/sciadv.1602241 for an example usage.

    Returns:

      Spin polarization in range [0, 1], will return NaN

        if spin polarization is ill-defined (e.g. for insulator). None if the calculation is not spin-polarized.

    Return type:

      float | None

class DOS(energies: ArrayLike, densities: ArrayLike, efermi: float)

  Bases: `Spectrum`

  (Work in progress) Replacement of basic DOS object.

    All other DOS objects are extended versions of this.

  energies

    Energies.

    Type:

      Sequence[float]

  densities

    Spin densities, e.g. {Spin.up: DOS_up, Spin.down: DOS_down}.

    Type:

      dict[Spin, NDArray]

  efermi

    The Fermi level.

    Type:

      float

  Parameters:

    - energies (Sequence[float]) – The Energies.

    - densities (NDArray) – A Nx1 or Nx2 array. If former, it is interpreted as a Spin.up only density. Otherwise, the first column is interpreted as Spin.up and the other Spin.down.

    - efermi (float) – The Fermi level.

  XLABEL = 'Energy'
  YLABEL = 'Density'
  get_cbm_vbm(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → tuple[float, float]

    Expects a DOS object and finds the CBM and VBM eigenvalues, using interpolation to determine the points at which the DOS crosses the threshold tol.

    tol may need to be increased for systems with noise/disorder.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the gap: - None: In the summed DOS. - Up: In the spin up channel. - Down: In the spin down channel.

    Returns:

      Energies in eV corresponding to the CBM and VBM.

    Return type:

      tuple[float, float]

  get_gap(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → float

    Expects a DOS object and finds the band gap, using the determined VBM and CBM eigenvalues.

    tol may need to be increased for systems with noise/disorder.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the gap: - None: In the summed DOS. - Up: In the spin up channel. - Down: In the spin down channel.

    Returns:

      Gap in eV.

    Return type:

      float

  get_interpolated_gap(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → tuple[float, float, float]

    Find the interpolated band gap.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the gap: - None: In the summed DOS. - Up: In the spin up channel. - Down: In the spin down channel.

    Returns:

      Energies in eV corresponding to the

        band gap, CBM and VBM.

    Return type:

      tuple[float, float, float]

class Dos(efermi: float, energies: ArrayLike, densities: Mapping[Spin, ArrayLike], norm_vol: float | None = None)

  Bases: `MSONable`

  Basic DOS object. All other DOS objects are extended versions of this.

  energies

    Energies.

    Type:

      Sequence[float]

  densities

    Spin densities, e.g. {Spin.up: DOS_up, Spin.down: DOS_down}.

    Type:

      dict[Spin, NDArray

  efermi

    The Fermi level.

    Type:

      float

  Parameters:

    - efermi (float) – The Fermi level.

    - energies (Sequence[float]) – Energies.

    - densities (dict[Spin, NDArray]) – The density of states for each Spin.

    - norm_vol (float | None) – The volume used to normalize the DOS. Defaults to 1 if None which will not perform any normalization. If None, the result will be in unit of states/eV, otherwise will be in states/eV/Angstrom^3.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of Dos.

  classmethod from_dict(dct: dict) → Self

    Get Dos from a dict representation.

  get_cbm_vbm(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → tuple[float, float]

    Expects a DOS object and finds the CBM and VBM eigenvalues, using interpolation to determine the points at which the DOS crosses the threshold tol.

    tol may need to be increased for systems with noise/disorder.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the gap: None - In the summed DOS. Up - In the spin up channel. Down - In the spin down channel.

    Returns:

      Energies in eV corresponding to the CBM and VBM.

    Return type:

      tuple[float, float]

  get_densities(spin: Spin | None = None) → None | NDArray

    Get the DOS for a particular spin.

    Parameters:

      spin (Spin) – Spin.

    Returns:

      The DOS for the particular spin. Or the sum of both spins

        if Spin is None.

    Return type:

      NDArray

  get_gap(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → float

    Find the band gap.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the band gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the band gap: None - In the summed DOS. Up - In the spin up channel. Down - In the spin down channel.

    Returns:

      Band gap in eV.

    Return type:

      float

  get_interpolated_gap(tol: float = 0.0001, abs_tol: bool = False, spin: Spin | None = None) → tuple[float, float, float]

    Find the interpolated band gap.

    Parameters:

      - tol (float) – Tolerance in occupations for determining the band gap.

      - abs_tol (bool) – Use absolute (True) or relative (False) tolerance.

      - spin (Spin | None) – Find the gap: None - In the summed DOS. Up - In the spin up channel. Down - In the spin down channel.

    Returns:

      Energies in eV corresponding to the

        band gap, CBM and VBM.

    Return type:

      tuple[float, float, float]

  get_interpolated_value(energy: float) → dict[Spin, float]

    Get interpolated density for a particular energy.

    Parameters:

      energy (float) – Energy to return the density for.

    Returns:

      Density for energy for each spin.

    Return type:

      dict[Spin, float]

  get_smeared_densities(sigma: float) → dict[Spin, NDArray]

    Get the the DOS with a Gaussian smearing.

    Parameters:

      sigma (float) – Standard deviation of Gaussian smearing.

    Returns:

      NDArray}: Gaussian-smeared DOS by spin.

    Return type:

      {Spin

class DosFingerprint(energies: np.ndarray, densities: np.ndarray, fp_type: str, n_bins: int, bin_width: float)

  Bases: `NamedTuple`

  Represents a Density of States (DOS) fingerprint.

  This named tuple is used to store information related to the Density of States (DOS) in a material. It includes the energies, densities, type, number of bins, and bin width.

  Parameters:

    - energies – The energy values associated with the DOS.

    - densities – The corresponding density values for each energy.

    - fp_type – The type of DOS fingerprint.

    - n_bins – The number of bins used in the fingerprint.

    - bin_width – The width of each bin in the DOS fingerprint.

  Create new instance of DosFingerprint(energies, densities, fp_type, n_bins, bin_width)

  bin_width: float

    Alias for field number 4

  densities: ndarray

    Alias for field number 1

  energies: ndarray

    Alias for field number 0

  fp_type: str

    Alias for field number 2

  n_bins: int

    Alias for field number 3

class FermiDos(dos: Dos, structure: Structure | None = None, nelecs: float | None = None, bandgap: float | None = None)

  Bases: `Dos`, `MSONable`

  Relate the density of states, doping levels (i.e. carrier concentrations) and corresponding Fermi levels.

  A negative doping concentration indicates the majority carriers are electrons (N-type); a positive doping concentration indicates holes are the majority carriers (P-type).

  Parameters:

    - dos (Dos) – Pymatgen Dos object.

    - structure (Structure) – A structure. If None, the Structure of the Dos will be used. If the Dos does not have an associated Structure, an ValueError will be raised.

    - nelecs (float) – The number of electrons included in the energy range of Dos. It is used for normalizing the DOS. Default None to the total number of electrons in the structure.

    - bandgap (float) – If not None, the energy values are scissored so that the electronic band gap matches this value.

  as_dict() → dict[str, Any]

    JSON-serializable dict representation of FermiDos.

  classmethod from_dict(dct: dict) → Self

    Get FermiDos object from a dict representation.

  get_doping(fermi_level: float, temperature: float) → float

    Calculate the doping (majority carrier concentration) at a given Fermi level and temperature. A simple Left Riemann sum is used for integrating the density of states over energy & equilibrium Fermi-Dirac distribution.

    Parameters:

      - fermi_level (float) – The Fermi level in eV.

      - temperature (float) – The temperature in Kelvin.

    Returns:

      The doping concentration in units of 1/cm^3. Negative values

        indicate that the majority carriers are electrons (N-type), whereas positive values indicates the majority carriers are holes (P-type).

    Return type:

      float

  get_fermi(concentration: float, temperature: float, rtol: float = 0.01, nstep: int = 50, step: float = 0.1, precision: int = 8) → float

    Find the Fermi level at which the doping concentration at the given temperature (T) is equal to concentration. An algorithm is used where the relative error is minimized by calculating the doping at a grid which continually becomes finer.

    Parameters:

      - concentration (float) – The doping concentration in 1/cm^3. Negative values represent N-type doping and positive values represent P-type.

      - temperature (float) – The temperature in Kelvin.

      - rtol (float) – The maximum acceptable relative error.

      - nstep (int) – The number of steps checked around a given Fermi level.

      - step (float) – The initial Energy step length when searching.

      - precision (int) – The decimal places of calculated Fermi level.

    Raises:

      ValueError – If the Fermi level cannot be found.

    Returns:

      The Fermi level in eV. Note that this is different from

        the default Dos.efermi.

    Return type:

      float

  get_fermi_interextrapolated(concentration: float, temperature: float, warn: bool = True, c_ref: float = 10000000000.0, **kwargs) → float

    Similar to get_fermi method except that when it fails to converge, an interpolated or extrapolated Fermi level is returned, with the assumption that the Fermi level changes linearly with log(abs(concentration)), and therefore must be used with caution.

    Parameters:

      - concentration (float) – The doping concentration in 1/cm^3. Negative value represents N-type doping and positive value represents P-type.

      - temperature (float) – The temperature in Kelvin.

      - warn (bool) – Whether to give a warning the first time the Fermi level cannot be found.

      - c_ref (float) – A doping concentration where get_fermi returns a value without error for both c_ref and -c_ref.

      - **kwargs – Keyword arguments passed to the get_fermi function.

    Returns:

      The possibly interpolated or extrapolated Fermi level.

    Return type:

      float

class LobsterCompleteDos(structure: Structure, total_dos: Dos, pdoss: Mapping[PeriodicSite, Mapping[Orbital, Mapping[Spin, ArrayLike]]], normalize: bool = False)

  Bases: `CompleteDos`

  Extended CompleteDos for LOBSTER.

  Parameters:

    - structure (Structure) – Structure associated with this DOS.

    - total_dos (Dos) – Total DOS for the structure.

    - pdoss (dict) – The PDOSs supplied as {Site: {Orbital: {Spin: Densities}}}.

    - normalize (bool) – Whether to normalize the DOS by the volume of the structure. If True, the units of the DOS are states/eV/Angstrom^3. Otherwise, the units are states/eV.

  classmethod from_dict(dct: dict) → Self

    Get LobsterCompleteDos from a dict representation.

  get_element_spd_dos(el: SpeciesLike) → dict[str, Dos]

    Get element and s/p/d projected DOS.

    Parameters:

      el (SpeciesLike) – Element associated with LobsterCompleteDos.

    Returns:

      Dos, OrbitalType.p: Dos, OrbitalType.d: Dos}

    Return type:

      dict of {OrbitalType.s

  get_site_orbital_dos(site: PeriodicSite, orbital: str) → Dos

    Get the DOS for a particular orbital of a particular site.

    Parameters:

      - site (PeriodicSite) – Site in Structure associated with LobsterCompleteDos.

      - orbital (str) –

        Principal quantum number and orbital, e.g. “4s”. Possible orbitals are: “s”, “p_y”, “p_z”, “p_x”, “d_xy”, “d_yz”, “d_z^2”,

        > ”d_xz”, “d_x^2-y^2”, “f_y(3x^2-y^2)”, “f_xyz”, “f_yz^2”, “f_z^3”, “f_xz^2”, “f_z(x^2-y^2)”, “f_x(x^2-3y^2)”.

        In contrast to the Cohpcar and the Cohplist objects,

          the strings from the LOBSTER files are used.

    Returns:

      DOS of an orbital of a specific site.

    Return type:

      Dos

  get_site_t2g_eg_resolved_dos(site: PeriodicSite) → dict[Literal['e_g', 't2g'], Dos]

    Get the t2g/e_g projected DOS for a particular site.

    Parameters:

      site (PeriodicSite) – Site in Structure associated with LobsterCompleteDos.

    Returns:

      Summed e_g and t2g DOS for the site.

    Return type:

      dict[Literal[“e_g”, “t2g”], Dos]

  get_spd_dos() → dict[str, Dos]

    Get orbital projected DOS.

    For example, if 3s and 4s are included in the basis of some element, they will be both summed in the orbital projected DOS.

    Returns:

      Dos}

    Return type:

      {orbital

add_densities(density1: Mapping[Spin, ArrayLike], density2: Mapping[Spin, ArrayLike]) → dict[Spin, NDArray]

  Sum two DOS along each spin channel.

  Parameters:

    - density1 (dict[Spin, NDArray]) – First DOS.

    - density2 (dict[Spin, NDArray]) – Second DOS.

  Returns:

    dict[Spin, NDArray]

f0(E: float | NDArray, fermi: float, T: float) → float

  Fermi-Dirac distribution function.

  Parameters:

    - E (float) – Energy in eV.

    - fermi (float) – The Fermi level in eV.

    - T (float) – The temperature in kelvin.

  Returns:

    The Fermi-Dirac occupation probability at energy E.

  Return type:

    float

## pymatgen.electronic_structure.plotter module

This module implements plotter for DOS and band structure.

class BSDOSPlotter(bs_projection: Literal['elements'] | None = 'elements', dos_projection: str = 'elements', vb_energy_range: float = 4, cb_energy_range: float = 4, fixed_cb_energy: bool = False, egrid_interval: float = 1, font: str = 'Times New Roman', axis_fontsize: float = 20, tick_fontsize: float = 15, legend_fontsize: float = 14, bs_legend: str = 'best', dos_legend: str = 'best', rgb_legend: bool = True, fig_size: tuple[float, float] = (11, 8.5))

  Bases: `object`

  A joint, aligned band structure and density of states plot. Contributions from Jan Pohls as well as the online example from Germain Salvato-Vallverdu: https://gvallver.perso.univ-pau.fr/?p=587.

  Instantiate plotter settings.

  Parameters:

    - bs_projection ('elements' | None) – Whether to project the bands onto elements.

    - dos_projection (str) – “elements”, “orbitals”, or None

    - vb_energy_range (float) – energy in eV to show of valence bands

    - cb_energy_range (float) – energy in eV to show of conduction bands

    - fixed_cb_energy (bool) – If true, the cb_energy_range will be interpreted as constant (i.e., no gap correction for cb energy)

    - egrid_interval (float) – interval for grid marks

    - font (str) – font family

    - axis_fontsize (float) – font size for axis

    - tick_fontsize (float) – font size for axis tick labels

    - legend_fontsize (float) – font size for legends

    - bs_legend (str) – matplotlib string location for legend or None

    - dos_legend (str) – matplotlib string location for legend or None

    - rgb_legend (bool) – (T/F) whether to draw RGB triangle/bar for element proj.

    - fig_size (tuple) – dimensions of figure size (width, height)

  get_plot(bs: BandStructureSymmLine, dos: Dos | CompleteDos | None = None) → plt.Axes | tuple[plt.Axes, plt.Axes]

    Get a matplotlib plot object.

    Parameters:

      - bs (BandStructureSymmLine) – the bandstructure to plot. Projection data must exist for projected plots.

      - dos (Dos) – the Dos to plot. Projection data must exist (i.e., CompleteDos) for projected plots.

    Returns:

      matplotlib axes for the band structure and DOS, resp.

    Return type:

      plt.Axes | tuple[plt.Axes, plt.Axes]

class BSPlotter(bs: BandStructureSymmLine)

  Bases: `object`

  Plot or get data to facilitate the plotting of band structure.

  Parameters:

    bs – A BandStructureSymmLine object.

  add_bs(bs: BandStructureSymmLine | list[BandStructureSymmLine]) → None

    Add bands objects to the BSPlotter.

  bs_plot_data(zero_to_efermi=True, bs=None, bs_ref=None, split_branches=True)

    Get the data nicely formatted for a plot.

    Parameters:

      - zero_to_efermi – Automatically set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - bs – the bandstructure to get the data from. If not provided, the first one in the self._bs list will be used.

      - bs_ref – is the bandstructure of reference when a rescale of the distances is need to plot multiple bands

      - split_branches – if True distances and energies are split according to the branches. If False distances and energies are split only where branches are discontinuous (reducing the number of lines to plot).

    Returns:

      A dictionary of the following format: ticks: A dict with the ‘distances’ at which there is a kpoint (the x axis) and the labels (None if no label). energy: A dict storing bands for spin up and spin down data {Spin:[np.array(nb_bands,kpoints),…]} as a list of discontinuous kpath of energies. The energy of multiple continuous branches are stored together. vbm: A list of tuples (distance,energy) marking the vbms. The energies are shifted with respect to the Fermi level is the option has been selected. cbm: A list of tuples (distance,energy) marking the cbms. The energies are shifted with respect to the Fermi level is the option has been selected. lattice: The reciprocal lattice. zero_energy: This is the energy used as zero for the plot. band_gap:A string indicating the band gap and its nature (empty if it’s a metal). is_metal: True if the band structure is metallic (i.e., there is at least one band crossing the Fermi level).

    Return type:

      dict

  get_plot(zero_to_efermi=True, ylim=None, smooth=False, vbm_cbm_marker=False, smooth_tol=0, smooth_k=3, smooth_np=100, bs_labels=None)

    Get a matplotlib object for the bandstructures plot. Multiple bandstructure objs are plotted together if they have the same high symm path.

    Parameters:

      - zero_to_efermi – Automatically set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - ylim – Specify the y-axis (energy) limits; by default None let the code choose. It is vbm-4 and cbm+4 if insulator efermi-10 and efermi+10 if metal

      - smooth (bool or list(bools)) – interpolates the bands by a spline cubic. A single bool values means to interpolate all the bandstructure objs. A list of bools allows to select the bandstructure obs to interpolate.

      - vbm_cbm_marker (bool) – if True, a marker is added to the vbm and cbm.

      - smooth_tol (float) – tolerance for fitting spline to band data. Default is None such that no tolerance will be used.

      - smooth_k (int) – degree of splines 1<k<5

      - smooth_np (int) – number of interpolated points per each branch.

      - bs_labels – labels for each band for the plot legend.

  get_ticks()

    Get all ticks and labels for a band structure plot.

    Returns:

      A dictionary with ‘distance’: a list of distance at which ticks should be set and ‘label’: a list of label for each of those ticks.

    Return type:

      dict

  get_ticks_old()

    Get all ticks and labels for a band structure plot.

    Returns:

      A dictionary with ‘distance’: a list of distance at which ticks should be set and ‘label’: a list of label for each of those ticks.

    Return type:

      dict

  plot_brillouin()

    Plot the Brillouin zone.

    Returns:

      A matplotlib figure object with the Brillouin zone.

    Return type:

      plt.Figure

  plot_compare(other_plotter, legend=True) → Axes

    Plot two band structure for comparison. One is in red the other in blue (no difference in spins). The two band structures need to be defined on the same symmetry lines! and the distance between symmetry lines is the one of the band structure used to build the BSPlotter.

    Parameters:

      - other_plotter – Another band structure object defined along the same symmetry lines

      - legend – True to add a legend to the plot

    Returns:

      matplotlib Axes object with both band structures

    Return type:

      plt.Axes

  save_plot(filename: str, ylim=None, zero_to_efermi=True, smooth=False) → None

    Save matplotlib plot to a file.

    Parameters:

      - filename (str) – Filename to write to. Must include extension to specify image format.

      - ylim – Specifies the y-axis limits.

      - zero_to_efermi – Automatically set the Fermi level as the plot’s origin (i.e. subtract E - E_f). Defaults to True.

      - smooth – Cubic spline interpolation of the bands.

  show(zero_to_efermi=True, ylim=None, smooth=False, smooth_tol=None) → None

    Show the plot using matplotlib.

    Parameters:

      - zero_to_efermi – Set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - ylim – Specify the y-axis (energy) limits; by default None let the code choose. It is vbm-4 and cbm+4 if insulator efermi-10 and efermi+10 if metal

      - smooth – interpolates the bands by a spline cubic

      - smooth_tol (float) – tolerance for fitting spline to band data. Default is None such that no tolerance will be used.

class BSPlotterProjected(bs: BandStructureSymmLine)

  Bases: `BSPlotter`

  Plot or get data to facilitate plotting of projected band structure along orbitals, elements or sites.

  Parameters:

    - bs – A BandStructureSymmLine object with projections

    - calculation. (e.g. from a VASP)

  get_elt_projected_plots(zero_to_efermi: bool = True, ylim: tuple[float, float] | None = None, vbm_cbm_marker: bool = False, band_linewidth: float = 1.0) → Axes

    Generate a plot with subplots for different elements.

    The blue and red colors are for spin up and spin down The size of the dot in the plot corresponds to the value for the specific point.

    Returns:

      2x2 array of plt.Axes with different

        subplots for each projection.

    Return type:

      np.ndarray[plt.Axes]

  get_elt_projected_plots_color(zero_to_efermi: bool = True, elt_ordered: list | None = None, band_linewidth: float = 3) → Axes

    Generate a pyplot plot where the band structure line color depends on the element of the band. where each element is associated with red, green or blue.

    The method can only deal with binary and ternary compounds.

    Spin up and spin down are differentiated by a ‘-’ and a ‘–’ line.

    Parameters:

      - zero_to_efermi – set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - elt_ordered – A list of ordered Elements. The first one is red, second green, last blue.

      - band_linewidth (float) – width of the line.

    Raises:

      - RuntimeError – if the band structure is None.

      - ValueError – if the number of elements is not 2 or 3.

    Returns:

      a pyplot object

  get_projected_plots_dots(dictio: dict[str, list], zero_to_efermi: bool = True, ylim: tuple[float, float] | None = None, vbm_cbm_marker: bool = False, band_linewidth: float = 1.0, marker_size: float = 15.0) → list[Axes]

    Generate a plot with subplots for each element-orbital pair.

    The orbitals are named as in the FATBAND file, e.g. “2p” or “2p_x”.

    he blue and red colors are for spin up and spin down The size of the dot in the plot corresponds to the value for the specific point.

    Parameters:

      - dictio – The element and orbitals you want a projection on. The format is {Element: [*Orbitals]} for instance {“Cu”:[“d”, “s”], “O”:[“p”]} will yield projections for Cu on d and s orbitals and oxygen on p.

      - zero_to_efermi – Set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - ylim – The y-axis limits. Defaults to None.

      - vbm_cbm_marker (bool) – Add markers for the VBM and CBM. Defaults to False.

      - band_linewidth (float) – The width of the lines. Defaults to 1.0.

      - marker_size (float) – The size of the markers. Defaults to 15.0.

    Returns:

      plt.Axes

  get_projected_plots_dots_patom_pmorb(dictio, dictpa, sum_atoms=None, sum_morbs=None, zero_to_efermi=True, ylim=None, vbm_cbm_marker=False, selected_branches=None, w_h_size=(12, 8), num_column=None)

    Return a plot composed of subplots for different atoms and orbitals (subshell orbitals such as ‘s’, ‘p’, ‘d’ and ‘f’ defined by azimuthal quantum numbers l = 0, 1, 2 and 3, respectively or individual orbitals like ‘px’, ‘py’ and ‘pz’ defined by magnetic quantum numbers m = -1, 1 and 0, respectively). This is an extension of “get_projected_plots_dots” method.

    Parameters:

      - dictio – The elements and the orbitals you need to project on. The format is {Element:[Orbitals]}, for instance: {‘Cu’:[‘dxy’,’s’,’px’],’O’:[‘px’,’py’,’pz’]} will give projections for Cu on orbitals dxy, s, px and for O on orbitals px, py, pz. If you want to sum over all individual orbitals of subshell orbitals, for example, ‘px’, ‘py’ and ‘pz’ of O, just simply set {‘Cu’:[‘dxy’,’s’,’px’],’O’:[‘p’]} and set sum_morbs (see explanations below) as {‘O’:[p],…}. Otherwise, you will get an error.

      - dictpa – The elements and their sites (defined by site numbers) you need to project on. The format is {Element: [Site numbers]}, for instance: {‘Cu’:[1,5],’O’:[3,4]} will give projections for Cu on site-1 and on site-5, O on site-3 and on site-4 in the cell. The correct site numbers of atoms are consistent with themselves in the structure computed. Normally, the structure should be totally similar with POSCAR file, however, sometimes VASP can rotate or translate the cell. Thus, it would be safe if using Vasprun class to get the final_structure and as a result, correct index numbers of atoms.

      - sum_atoms – Sum projection of the similar atoms together (e.g.: Cu on site-1 and Cu on site-5). The format is {Element: [Site numbers]}, for instance: {‘Cu’: [1,5], ‘O’: [3,4]} means summing projections over Cu on site-1 and Cu on site-5 and O on site-3 and on site-4. If you do not want to use this functional, just turn it off by setting sum_atoms = None.

      - sum_morbs – Sum projections of individual orbitals of similar atoms together (e.g.: ‘dxy’ and ‘dxz’). The format is {Element: [individual orbitals]}, for instance: {‘Cu’: [‘dxy’, ‘dxz’], ‘O’: [‘px’, ‘py’]} means summing projections over ‘dxy’ and ‘dxz’ of Cu and ‘px’ and ‘py’ of O. If you do not want to use this functional, just turn it off by setting sum_morbs = None.

      - zero_to_efermi – Automatically set the Fermi level as the plot’s origin (i.e. subtract E_f). Defaults to True.

      - ylim – The y-axis limit. Defaults to None.

      - vbm_cbm_marker – Whether to plot points to indicate valence band maxima and conduction band minima positions. Defaults to False.

      - selected_branches – The index of symmetry lines you chose for plotting. This can be useful when the number of symmetry lines (in KPOINTS file) are manny while you only want to show for certain ones. The format is [index of line], for instance: [1, 3, 4] means you just need to do projection along lines number 1, 3 and 4 while neglecting lines number 2 and so on. By default, this is None type and all symmetry lines will be plotted.

      - w_h_size – This variable help you to control the width and height of figure. By default, width = 12 and height = 8 (inches). The width/height ratio is kept the same for subfigures and the size of each depends on how many number of subfigures are plotted.

      - num_column – This variable help you to manage how the subfigures are arranged in the figure by setting up the number of columns of subfigures. The value should be an int number. For example, num_column = 3 means you want to plot subfigures in 3 columns. By default, num_column = None and subfigures are aligned in 2 columns.

    Returns:

      A pyplot object with different subfigures for different projections. The blue and red colors lines are bands for spin up and spin down. The green and cyan dots are projections for spin up and spin down. The bigger the green or cyan dots in the projected band structures, the higher character for the corresponding elements and orbitals. List of individual orbitals and their numbers (set up by VASP and no special meaning): s = 0; py = 1 pz = 2 px = 3; dxy = 4 dyz = 5 dz2 = 6 dxz = 7 dx2 = 8; f_3 = 9 f_2 = 10 f_1 = 11 f0 = 12 f1 = 13 f2 = 14 f3 = 15

class BoltztrapPlotter(bz)

  Bases: `object`

  Plot Boltztrap data.

  Parameters:

    bz – a BoltztrapAnalyzer object.

  plot_carriers(temp=300)

    Plot the carrier concentration in function of Fermi level.

    Parameters:

      temp – the temperature

    Returns:

      a matplotlib object

  plot_complexity_factor_mu(temps=(300,), output='average', Lambda=0.5)

    Plot respect to the chemical potential of the Fermi surface complexity factor calculated as explained in Ref. Gibbs, Z. M. et al., Effective mass and fermi surface complexity factor from ab initio band structure calculations. npj Computational Materials 3, 8 (2017).

    Parameters:

      - output – ‘average’ returns the complexity factor calculated using the average of the three diagonal components of the seebeck and conductivity tensors. ‘tensor’ returns the complexity factor respect to the three diagonal components of seebeck and conductivity tensors.

      - temps – list of temperatures of calculated seebeck and conductivity.

      - Lambda – fitting parameter used to model the scattering (0.5 means constant relaxation time).

    Returns:

      a matplotlib object

  plot_conductivity_dop(temps='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the conductivity in function of doping levels for different temperatures.

    Parameters:

      - temps – the default ‘all’ plots all the temperatures in the analyzer. Specify a list of temperatures if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_conductivity_mu(temp: float = 600, output: str = 'eig', relaxation_time: float = 1e-14, xlim: tuple[float, float] | None = None)

    Plot the conductivity in function of Fermi level. Semi-log plot.

    Parameters:

      - temp (float) – the temperature

      - output (str) – “eig” or “average”

      - relaxation_time (float) – A relaxation time in s. Defaults to 1e-14 and the plot is in units of relaxation time

      - xlim (tuple[float, float]) – a 2-tuple of min and max fermi energy. Defaults to (0, band gap)

    Returns:

      a matplotlib object

  plot_conductivity_temp(doping='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the conductivity in function of temperature for different doping levels.

    Parameters:

      - doping (str) – the default ‘all’ plots all the doping levels in the analyzer. Specify a list of doping levels if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_dos(sigma=0.05)

    Plot dos.

    Parameters:

      sigma – a smearing

    Returns:

      a matplotlib object

  plot_eff_mass_dop(temps='all', output: Literal['average', 'eigs'] = 'average')

    Plot the average effective mass in function of doping levels for different temperatures.

    Parameters:

      - temps – the default ‘all’ plots all the temperatures in the analyzer. Specify a list of temperatures if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_eff_mass_temp(doping='all', output: Literal['average', 'eigs'] = 'average')

    Plot the average effective mass in function of temperature for different doping levels.

    Parameters:

      - doping (str) – the default ‘all’ plots all the doping levels in the analyzer. Specify a list of doping levels if you want to plot only some.

      - output ('average' | 'eigs') – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

    Returns:

      a matplotlib Axes object

  plot_hall_carriers(temp=300)

    Plot the Hall carrier concentration in function of Fermi level.

    Parameters:

      temp – the temperature

    Returns:

      a matplotlib object

  plot_power_factor_dop(temps='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the Power Factor in function of doping levels for different temperatures.

    Parameters:

      - temps – the default ‘all’ plots all the temperatures in the analyzer. Specify a list of temperatures if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_power_factor_mu(temp: float = 600, output: str = 'eig', relaxation_time: float = 1e-14, xlim: tuple[float, float] | None = None)

    Plot the power factor in function of Fermi level. Semi-log plot.

    Parameters:

      - temp (float) – the temperature

      - output (str) – “eig” or “average”

      - relaxation_time (float) – A relaxation time in s. Defaults to 1e-14 and the plot is in units of relaxation time

      - xlim (tuple[float, float]) – a 2-tuple of min and max fermi energy. Defaults to (0, band gap)

    Returns:

      a matplotlib object

  plot_power_factor_temp(doping='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the Power Factor in function of temperature for different doping levels.

    Parameters:

      - doping (str) – the default ‘all’ plots all the doping levels in the analyzer. Specify a list of doping levels if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_seebeck_dop(temps='all', output: Literal['average', 'eigs'] = 'average')

    Plot the Seebeck in function of doping levels for different temperatures.

    Parameters:

      - temps – the default ‘all’ plots all the temperatures in the analyzer. Specify a list of temperatures if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

    Returns:

      a matplotlib object

  plot_seebeck_eff_mass_mu(temps=(300,), output='average', Lambda=0.5)

    Plot respect to the chemical potential of the Seebeck effective mass calculated as explained in Ref. Gibbs, Z. M. et al., Effective mass and fermi surface complexity factor from ab initio band structure calculations. npj Computational Materials 3, 8 (2017).

    Parameters:

      - output – ‘average’ returns the seebeck effective mass calculated using the average of the three diagonal components of the seebeck tensor. ‘tensor’ returns the seebeck effective mass respect to the three diagonal components of the seebeck tensor.

      - temps – list of temperatures of calculated seebeck.

      - Lambda – fitting parameter used to model the scattering (0.5 means constant relaxation time).

    Returns:

      a matplotlib object

  plot_seebeck_mu(temp: float = 600, output: str = 'eig', xlim: Sequence[float] | None = None)

    Plot the seebeck coefficient in function of Fermi level.

    Parameters:

      - temp (float) – the temperature

      - output (str) – “eig” or “average”

      - xlim (tuple[float, float]) – a 2-tuple of min and max fermi energy. Defaults to (0, band gap)

    Returns:

      a matplotlib object

  plot_seebeck_temp(doping='all', output: Literal['average', 'eigs'] = 'average')

    Plot the Seebeck coefficient in function of temperature for different doping levels.

    Parameters:

      - doping (str) – the default ‘all’ plots all the doping levels in the analyzer. Specify a list of doping levels if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

    Returns:

      a matplotlib object

  plot_zt_dop(temps='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the figure of merit zT in function of doping levels for different temperatures.

    Parameters:

      - temps – the default ‘all’ plots all the temperatures in the analyzer. Specify a list of temperatures if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Returns:

      a matplotlib object

  plot_zt_mu(temp: float = 600, output: str = 'eig', relaxation_time: float = 1e-14, xlim: tuple[float, float] | None = None) → Axes

    Plot the ZT as function of Fermi level.

    Parameters:

      - temp (float) – the temperature

      - output (str) – “eig” or “average”

      - relaxation_time (float) – A relaxation time in s. Defaults to 1e-14 and the plot is in units of relaxation time

      - xlim (tuple[float, float]) – a 2-tuple of min and max fermi energy. Defaults to (0, band gap)

    Returns:

      matplotlib axes object

    Return type:

      plt.Axes

  plot_zt_temp(doping='all', output: Literal['average', 'eigs'] = 'average', relaxation_time=1e-14)

    Plot the figure of merit zT in function of temperature for different doping levels.

    Parameters:

      - doping (str) – the default ‘all’ plots all the doping levels in the analyzer. Specify a list of doping levels if you want to plot only some.

      - output – with ‘average’ you get an average of the three directions with ‘eigs’ you get all the three directions.

      - relaxation_time – specify a constant relaxation time value

    Raises:

      ValueError – if output is not ‘average’ or ‘eigs’

    Returns:

      a matplotlib object

class CohpPlotter(zero_at_efermi=True, are_coops=False, are_cobis=False)

  Bases: `object`

  Plot crystal orbital Hamilton populations (COHPs) or crystal orbital overlap populations (COOPs). It is modeled after the DosPlotter object.

  Parameters:

    - zero_at_efermi – Whether to shift all populations to have zero energy at the Fermi level. Defaults to True.

    - are_coops – Switch to indicate that these are COOPs, not COHPs. Defaults to False for COHPs.

    - are_cobis – Switch to indicate that these are COBIs or multi-center COBIs, not COHPs/COOPs. Defaults to False for COHPs.

  add_cohp(label, cohp) → None

    Add a COHP for plotting.

    Parameters:

      - label – Label for the COHP. Must be unique.

      - cohp – COHP object.

  add_cohp_dict(cohp_dict, key_sort_func=None) → None

    Add a dictionary of COHPs with an optional sorting function for the keys.

    Parameters:

      - cohp_dict – dict of the form {label: Cohp}

      - key_sort_func – function used to sort the cohp_dict keys.

  get_cohp_dict()

    Get the added COHPs as a json-serializable dict. Note that if you have specified smearing for the COHP plot, the populations returned will be the smeared and not the original populations.

    Returns:

      Dict of COHP data of the form {label: {“efermi”: efermi, “energies”: …, “COHP”: {Spin.up: …}, “ICOHP”: …}}.

    Return type:

      dict

  get_plot(xlim=None, ylim=None, plot_negative=None, integrated=False, invert_axes=True)

    Get a matplotlib plot showing the COHP.

    Parameters:

      - xlim – Specifies the x-axis limits. Defaults to None for automatic determination.

      - ylim – Specifies the y-axis limits. Defaults to None for automatic determination.

      - plot_negative – It is common to plot -COHP(E) so that the sign means the same for COOPs and COHPs. Defaults to None for automatic determination: If are_coops is True, this will be set to False, else it will be set to True.

      - integrated – Switch to plot ICOHPs. Defaults to False.

      - invert_axes – Put the energies onto the y-axis, which is common in chemistry.

    Returns:

      A matplotlib object.

  save_plot(filename: str, xlim=None, ylim=None) → None

    Save matplotlib plot to a file.

    Parameters:

      - filename (str) – File name to write to. Must include extension to specify image format.

      - xlim – Specifies the x-axis limits. Defaults to None for automatic determination.

      - ylim – Specifies the y-axis limits. Defaults to None for automatic determination.

  show(xlim=None, ylim=None) → None

    Show the plot using matplotlib.

    Parameters:

      - xlim – Specifies the x-axis limits. Defaults to None for automatic determination.

      - ylim – Specifies the y-axis limits. Defaults to None for automatic determination.

class DosPlotter(zero_at_efermi: bool = True, stack: bool = False, sigma: float | None = None)

  Bases: `object`

  Plot DOS. The interface is extremely flexible given there are many different ways in which people want to view DOS. Typical usage is:

  > # Initialize plotter with some optional args. Defaults are usually fine plotter = PhononDosPlotter().

  > # Add DOS with a label plotter.add_dos(“Total DOS”, dos)

  > # Alternatively, you can add a dict of DOS. This is the typical form # returned by CompletePhononDos.get_element_dos(). plotter.add_dos_dict({“dos1”: dos1, “dos2”: dos2}) plotter.add_dos_dict(complete_dos.get_spd_dos())

  Parameters:

    - zero_at_efermi (bool) – Whether to shift all Dos to have zero energy at the fermi energy. Defaults to True.

    - stack (bool) – Whether to plot the DOS as a stacked area graph

    - sigma (float) – Specify a standard deviation for Gaussian smearing the DOS for nicer looking plots. Defaults to None for no smearing.

  add_dos(label: str, dos: Dos) → None

    Add a DOS for plotting.

    Parameters:

      - label – a unique label for the DOS.

      - dos – Dos object

  add_dos_dict(dos_dict, key_sort_func=None) → None

    Add a dictionary of DOSs, with an optional sorting function for the keys.

    Parameters:

      - dos_dict – dict of {label: Dos}

      - key_sort_func – function used to sort the dos_dict keys.

  get_dos_dict()

    Get the added doses as a json-serializable dict. Note that if you have specified smearing for the DOS plot, the densities returned will be the smeared densities, not the original densities.

    Returns:

      Dict of dos data. Generally of the form {label: {‘energies’:…, ‘densities’: {‘up’:…}, ‘efermi’:efermi}}

    Return type:

      dict

  get_plot(xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, invert_axes: bool = False, beta_dashed: bool = False) → Axes

    Get a matplotlib plot showing the DOS.

    Parameters:

      - xlim (tuple[float, float]) – The energy axis limits. Defaults to None for automatic determination.

      - ylim (tuple[float, float]) – The y-axis limits. Defaults to None for automatic determination.

      - invert_axes (bool) – Whether to invert the x and y axes. Enables chemist style DOS plotting. Defaults to False.

      - beta_dashed (bool) – Plots the beta spin channel with a dashed line. Defaults to False.

    Returns:

      matplotlib Axes object.

    Return type:

      plt.Axes

  save_plot(filename: str, xlim=None, ylim=None, invert_axes=False, beta_dashed=False) → None

    Save matplotlib plot to a file.

    Parameters:

      - filename (str) – Filename to write to. Must include extension to specify image format.

      - xlim – Specifies the x-axis limits. Set to None for automatic determination.

      - ylim – Specifies the y-axis limits.

      - invert_axes (bool) – Whether to invert the x and y axes. Enables chemist style DOS plotting. Defaults to False.

      - beta_dashed (bool) – Plots the beta spin channel with a dashed line. Defaults to False.

  show(xlim=None, ylim=None, invert_axes=False, beta_dashed=False) → None

    Show the plot using matplotlib.

    Parameters:

      - xlim – Specifies the x-axis limits. Set to None for automatic determination.

      - ylim – Specifies the y-axis limits.

      - invert_axes (bool) – Whether to invert the x and y axes. Enables chemist style DOS plotting. Defaults to False.

      - beta_dashed (bool) – Plots the beta spin channel with a dashed line. Defaults to False.

fold_point(p, lattice, coords_are_cartesian=False)

  Folds a point with coordinates p inside the first Brillouin zone of the lattice.

  Parameters:

    - p – coordinates of one point

    - lattice – Lattice object used to convert from reciprocal to Cartesian coordinates

    - coords_are_cartesian – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.

  Returns:

    The Cartesian coordinates folded inside the first Brillouin zone

plot_brillouin_zone(bz_lattice, lines=None, labels=None, kpoints=None, fold=False, coords_are_cartesian: bool = False, ax: Axes = None, **kwargs)

  Plots a 3D representation of the Brillouin zone of the structure. Can add to the plot paths, labels and kpoints.

  Parameters:

    - bz_lattice – Lattice object of the Brillouin zone

    - lines – list of lists of coordinates. Each list represent a different path

    - labels – dict containing the label as a key and the coordinates as value.

    - kpoints – list of coordinates

    - fold – whether the points should be folded inside the first Brillouin Zone. Defaults to False. Requires lattice if True.

    - coords_are_cartesian – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.

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

    - kwargs – provided by add_fig_kwargs decorator

  Returns:

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

plot_brillouin_zone_from_kpath(kpath, ax: Axes = None, **kwargs) → Axes
  Get the plot (as a matplotlib object) of the symmetry line path in

    the Brillouin Zone.

  Parameters:

    - kpath (HighSymmKpath) – a HighSymmKPath object

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

    - **kwargs – provided by add_fig_kwargs decorator

  Returns:

    matplotlib Axes

    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.

  Return type:

    plt.Axes

plot_ellipsoid(hessian, center, lattice=None, rescale=1.0, ax: Axes = None, coords_are_cartesian=False, arrows=False, **kwargs)

  Plots a 3D ellipsoid rappresenting the Hessian matrix in input. Useful to get a graphical visualization of the effective mass of a band in a single k-point.

  Parameters:

    - hessian – the Hessian matrix

    - center – the center of the ellipsoid in reciprocal coords (Default)

    - lattice – Lattice object of the Brillouin zone

    - rescale – factor for size scaling of the ellipsoid

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

    - coords_are_cartesian – Set to True if you are providing a center in Cartesian coordinates. Defaults to False.

    - arrows – whether to plot arrows for the principal axes of the ellipsoid. Defaults to False.

    - **kwargs – passed to the matplotlib function ‘plot_wireframe’. Color defaults to blue, rstride and cstride default to 4, alpha defaults to 0.2.

  Returns:

    matplotlib figure and matplotlib ax

  Example of use:

    fig,ax=plot_wigner_seitz(struct.reciprocal_lattice) plot_ellipsoid(hessian,[0.0,0.0,0.0], struct.reciprocal_lattice,ax=ax)

plot_fermi_surface(data, structure, cbm, energy_levels=None, multiple_figure=True, mlab_figure=None, kpoints_dict=None, colors=None, transparency_factor=None, labels_scale_factor=0.05, points_scale_factor=0.02, interactive=True)

  Plot the Fermi surface at specific energy value using Boltztrap 1 FERMI mode.

  The easiest way to use this plotter is:

  > 1. Run boltztrap in ‘FERMI’ mode using BoltztrapRunner,

  > 2. Load BoltztrapAnalyzer using your method of choice (e.g., from_files)

  > 3. Pass in your BoltztrapAnalyzer’s fermi_surface_data as this

  >      function’s data argument.

  Parameters:

    - data – energy values in a 3D grid from a CUBE file via read_cube_file function, or from a BoltztrapAnalyzer.fermi_surface_data

    - structure – structure object of the material

    - energy_levels ([float]) – Energy values for plotting the fermi surface(s) By default 0 eV correspond to the VBM, as in the plot of band structure along symmetry line. Default: One surface, with max energy value + 0.01 eV

    - cbm (bool) – True if the considered band is a conduction band or not.

    - multiple_figure (bool) – If True a figure for each energy level will be shown. If False all the surfaces will be shown in the same figure. In this last case, tune the transparency factor.

    - mlab_figure (mayavi.mlab.figure) – A previous figure to plot a new surface on.

    - kpoints_dict (dict) – dictionary of kpoints to label in the plot. Example: {“K”:[0.5,0.0,0.5]}, coords are fractional

    - colors ([tuple]) – Iterable of 3-tuples (r,g,b) of integers to define the colors of each surface (one per energy level). Should be the same length as the number of surfaces being plotted. Example (3 surfaces): colors=[(1,0,0), (0,1,0), (0,0,1)] Example (2 surfaces): colors=[(0, 0.5, 0.5)]

    - transparency_factor (float) – Values in the range [0,1] to tune the opacity of each surface. Should be one transparency_factor per surface.

    - labels_scale_factor (float) – factor to tune size of the kpoint labels

    - points_scale_factor (float) – factor to tune size of the kpoint points

    - interactive (bool) – if True an interactive figure will be shown. If False a non interactive figure will be shown, but it is possible to plot other surfaces on the same figure. To make it interactive, run mlab.show().

  Returns:

    The mlab plotter and an interactive

      figure to control the plot.

  Return type:

    tuple[mlab.figure, mlab]

  Note: Experimental.

    Please, double check the surface shown by using some other software and report issues.

plot_labels(labels, lattice=None, coords_are_cartesian=False, ax: Axes = None, **kwargs)

  Add labels to a matplotlib Axes.

  Parameters:

    - labels – dict containing the label as a key and the coordinates as value.

    - lattice – Lattice object used to convert from reciprocal to Cartesian coordinates

    - coords_are_cartesian – Set to True if you are providing. coordinates in Cartesian coordinates. Defaults to False. Requires lattice if False.

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

    - kwargs – kwargs passed to the matplotlib function ‘text’. Color defaults to blue and size to 25.

  Returns:

    matplotlib figure and matplotlib ax

plot_lattice_vectors(lattice, ax: Axes = None, **kwargs)

  Add the basis vectors of the lattice provided to a matplotlib Axes.

  Parameters:

    - lattice – Lattice object

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

    - kwargs – kwargs passed to the matplotlib function ‘plot’. Color defaults to green and linewidth to 3.

  Returns:

    matplotlib figure and matplotlib ax

plot_path(line, lattice=None, coords_are_cartesian=False, ax: Axes = None, **kwargs)

  Add a line passing through the coordinates listed in ‘line’ to a matplotlib Axes.

  Parameters:

    - line – list of coordinates.

    - lattice – Lattice object used to convert from reciprocal to Cartesian coordinates

    - coords_are_cartesian – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False. Requires lattice if False.

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

    - kwargs – kwargs passed to the matplotlib function ‘plot’. Color defaults to red and linewidth to 3.

  Returns:

    matplotlib figure and matplotlib ax

plot_points(points, lattice=None, coords_are_cartesian=False, fold=False, ax: Axes = None, **kwargs)

  Add Points to a matplotlib Axes.

  Parameters:

    - points – list of coordinates

    - lattice – Lattice object used to convert from reciprocal to Cartesian coordinates

    - coords_are_cartesian – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False. Requires lattice if False.

    - fold – whether the points should be folded inside the first Brillouin Zone. Defaults to False. Requires lattice if True.

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

    - kwargs – kwargs passed to the matplotlib function ‘scatter’. Color defaults to blue

  Returns:

    matplotlib figure and matplotlib ax

plot_wigner_seitz(lattice, ax: Axes = None, **kwargs)

  Add the skeleton of the Wigner-Seitz cell of the lattice to a matplotlib Axes.

  Parameters:

    - lattice – Lattice object

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

    - kwargs – kwargs passed to the matplotlib function ‘plot’. Color defaults to black and linewidth to 1.

  Returns:

    matplotlib figure and matplotlib ax