# pymatgen.electronic_structure.bandstructure module

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

class BandStructure(kpoints, eigenvals, lattice, efermi, labels_dict=None, coords_are_cartesian=False, structure=None, projections=None)

  Bases: `object`

  This is the most generic band structure data possible it’s defined by a list of kpoints + energies for each of them

  kpoints:
  the list of kpoints (as Kpoint objects) in the band structure
  lattice_rec

    the reciprocal lattice of the band structure.

  efermi

    the fermi energy

  is_spin_polarized

    True if the band structure is spin-polarized, False otherwise

  bands

    The energy eigenvalues as a {spin: ndarray}. Note that the use of an ndarray is necessary for computational as well as memory efficiency due to the large amount of numerical data. The indices of the ndarray are [band_index, kpoint_index].

  nb_bands

    returns the number of bands in the band structure

  structure

    returns the structure

  projections

    The projections as a {spin: ndarray}. Note that the use of an ndarray is necessary for computational as well as memory efficiency due to the large amount of numerical data. The indices of the ndarray are [band_index, kpoint_index, orbital_index, ion_index].

  Parameters

    - kpoints – list of kpoint as numpy arrays, in frac_coords of the given lattice by default

    - eigenvals – dict of 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 – The reciprocal lattice as a pymatgen Lattice object. Pymatgen uses the physics convention of reciprocal lattice vectors WITH a 2*pi coefficient

    - efermi – fermi energy

    - labels_dict – (dict) of {} this links a kpoint (in frac coords or cartesian coordinates depending on the coords) to a label.

    - coords_are_cartesian – Whether coordinates are cartesian.

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

    - projections – dict of orbital projections as {spin: ndarray}. The indices of the ndarrayare [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()

    Json-serializable dict representation of BandStructure.

  classmethod from_dict(d)

    Create from dict.

    Parameters

      object. (A dict with all data for a band structure) –

    Returns

      A BandStructure object

  classmethod from_old_dict(d)
    Parameters

      d (dict) – A dict with all data for a band structure symm line object.

    Returns

      A BandStructureSymmLine object

  get_band_gap()

    Returns band gap data.

    Returns

      “energy”: band gap energy “direct”: A boolean telling if the gap is direct or not “transition”: kpoint labels of the transition (e.g., “\Gamma-X”)

    Return type

      A dict {“energy”,”direct”,”transition”}

  get_cbm()

    Returns data about the CBM.

    Returns

      {“band_index”,”kpoint_index”,”kpoint”,”energy”} - “band_index”: 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”: The kpoint (as a kpoint object) - “energy”: 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 dictionnary). 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

  get_direct_band_gap()

    Returns the direct band gap.

    Returns

      the value of the direct band gap

  get_direct_band_gap_dict()

    Returns a dictionary of information about the direct band gap

    Returns

      a dictionary of the band gaps indexed by spin along with their band indices and k-point index

  get_kpoint_degeneracy(kpoint, cartesian=False, tol=0.01)

    Returns degeneracy of a given k-point based on structure symmetry :param kpoint: coordinate of the k-point :type kpoint: 1x3 array :param cartesian: kpoint is in cartesian or fractional coordinates :type cartesian: bool :param tol: tolerance below which coordinates are considered equal :type tol: float

    Returns

      degeneracy or None if structure is not available

    Return type

      (int or None)

  get_projection_on_elements()

    Method returning a dictionary of projections on elements.

    Returns

      [][{Element:values}], Spin.down:[][{Element:values}]} format if there is no projections in the band structure returns an empty dict

    Return type

      a dictionary in the {Spin.up

  get_projections_on_elements_and_orbitals(el_orb_spec)

    Method returning a dictionary of projections on elements and specific orbitals

    Parameters

      el_orb_spec – A dictionary of Elements and Orbitals for which we want to have projections on. It is given as: {Element:[orbitals]}, e.g., {‘Cu’:[‘d’,’s’]}

    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_sym_eq_kpoints(kpoint, cartesian=False, tol=0.01)

    Returns a list of unique symmetrically equivalent k-points.

    Parameters

      - kpoint (1x3 array) – coordinate of the k-point

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

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

    Returns

      if structure is not available returns None

    Return type

      ([1x3 array] or None)

  get_vbm()

    Returns data about the VBM.

    Returns

      dict as {“band_index”,”kpoint_index”,”kpoint”,”energy”} - “band_index”: 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”: The kpoint (as a kpoint object) - “energy”: 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 dictionnary). 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

  is_metal(efermi_tol=0.0001)

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

    Returns

      True if a metal, False if not

class BandStructureSymmLine(kpoints, eigenvals, lattice, efermi, labels_dict, coords_are_cartesian=False, structure=None, projections=None)

  Bases: `pymatgen.electronic_structure.bandstructure.BandStructure`, `monty.json.MSONable`

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

  Parameters

    - kpoints – list of kpoint as numpy arrays, in frac_coords of the given lattice by default

    - eigenvals – dict of 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 – The reciprocal lattice. Pymatgen uses the physics convention of reciprocal lattice vectors WITH a 2*pi coefficient

    - efermi – fermi energy

    - label_dict – (dict) of {} this link a kpoint (in frac coords or cartesian coordinates depending on the coords).

    - coords_are_cartesian – Whether coordinates are cartesian.

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

    - projections – dict of orbital projections as {spin: ndarray}. The indices of the ndarrayare [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)

    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 – the band gap the scissor band structure need to have.

    Returns

      a BandStructureSymmLine object with the applied scissor shift

  as_dict()

    Json-serializable dict representation of BandStructureSymmLine.

  get_branch(index)

    Returns in what branch(es) is the kpoint. There can be several branches.

    Parameters

      index – the kpoint index

    Returns

      A list of dictionaries [{“name”,”start_index”,”end_index”,”index”}] indicating all branches in which the k_point is. It takes into account the fact that one kpoint (e.g., \Gamma) can be in several branches

  get_equivalent_kpoints(index)

    Returns the list of kpoint indices equivalent (meaning they are the same frac coords) to the given one.

    Parameters

      index – the kpoint index

    Returns

      a list of equivalent indices

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

class Kpoint(coords, lattice, to_unit_cell=False, coords_are_cartesian=False, label=None)

  Bases: `monty.json.MSONable`

  Class to store kpoint objects. A kpoint is defined with a lattice and frac or cartesian coordinates syntax similar than the site object in pymatgen.core.structure.

  Parameters

    - coords – coordinate of the kpoint as a numpy array

    - lattice – A pymatgen.core.lattice.Lattice lattice object representing the reciprocal lattice of the kpoint

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

    - coords_are_cartesian – Boolean indicating if the coordinates given are in cartesian or fractional coordinates (by default fractional)

    - label – the label of the kpoint if any (None by default)

  property a

    Fractional a coordinate of the kpoint

  as_dict()

    Json-serializable dict representation of a kpoint

  property b

    Fractional b coordinate of the kpoint

  property c

    Fractional c coordinate of the kpoint

  property cart_coords

    The cartesian coordinates of the kpoint as a numpy array

  property frac_coords

    The fractional coordinates of the kpoint as a numpy array

  classmethod from_dict(d)

    Create from dict.

    Parameters

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

    Returns

      A Kpoint object

  property label

    The label associated with the kpoint

  property lattice

    The lattice associated with the kpoint. It’s a pymatgen.core.lattice.Lattice object

class LobsterBandStructureSymmLine(kpoints, eigenvals, lattice, efermi, labels_dict, coords_are_cartesian=False, structure=None, projections=None)

  Bases: `pymatgen.electronic_structure.bandstructure.BandStructureSymmLine`

  Lobster subclass of BandStructure with customized functions.

  Parameters

    - kpoints – list of kpoint as numpy arrays, in frac_coords of the given lattice by default

    - eigenvals – dict of 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 – The reciprocal lattice. Pymatgen uses the physics convention of reciprocal lattice vectors WITH a 2*pi coefficient

    - efermi – fermi energy

    - label_dict – (dict) of {} this link a kpoint (in frac coords or cartesian coordinates depending on the coords).

    - coords_are_cartesian – Whether coordinates are cartesian.

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

    - projections – dict of orbital projections as {spin: ndarray}. The indices of the ndarrayare [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()

    Json-serializable dict representation of BandStructureSymmLine.

  classmethod from_dict(d)
    Parameters

      d (dict) – A dict with all data for a band structure symm line object.

    Returns

      A BandStructureSymmLine object

  classmethod from_old_dict(d)
    Parameters

      d (dict) – A dict with all data for a band structure symm line object.

    Returns

      A BandStructureSymmLine object

  get_projection_on_elements()

    Method returning a dictionary of projections on elements. It sums over all available orbitals for each element.

    Returns

      [][{Element:values}], Spin.down:[][{Element:values}]} format if there is no projections in the band structure returns an empty dict

    Return type

      a dictionary in the {Spin.up

  get_projections_on_elements_and_orbitals(el_orb_spec)

    Method returning a dictionary of projections on elements and specific orbitals

    Parameters

      el_orb_spec – A dictionary of Elements and Orbitals for which we want to have projections 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, efermi=None)

  This method takes a list of band structures and reconstructs one band structure object from all of them.

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

  Parameters

    - list_bs – A list of BandStructure or BandStructureSymmLine objects.

    - efermi – The Fermi energy of the reconstructed band structure. If None is assigned an average of all the Fermi energy in each object in the list_bs is used.

  Returns

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