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)[source]¶ 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 spinpolarized, 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.

classmethod
from_dict
(d)[source]¶ Create from dict.
 Parameters
dict with all data for a band structure object. (A) –
 Returns
A BandStructure object

classmethod
from_old_dict
(d)[source]¶  Parameters
d (dict) – A dict with all data for a band structure symm line object.
 Returns
A BandStructureSymmLine object

get_band_gap
()[source]¶ 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., “\GammaX”)
 Return type
A dict {“energy”,”direct”,”transition”}

get_cbm
()[source]¶ 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 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

get_direct_band_gap
()[source]¶ Returns the direct band gap.
 Returns
the value of the direct band gap

get_direct_band_gap_dict
()[source]¶ 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 kpoint index

get_kpoint_degeneracy
(kpoint, cartesian=False, tol=0.01)[source]¶ Returns degeneracy of a given kpoint based on structure symmetry :param kpoint: coordinate of the kpoint :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
()[source]¶ 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)[source]¶ 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)[source]¶ Returns a list of unique symmetrically equivalent kpoints.
 Parameters
kpoint (1x3 array) – coordinate of the kpoint
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
()[source]¶ 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


class
BandStructureSymmLine
(kpoints, eigenvals, lattice, efermi, labels_dict, coords_are_cartesian=False, structure=None, projections=None)[source]¶ 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)[source]¶ 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

classmethod
from_dict
(d)[source]¶  Parameters
d (dict) – A dict with all data for a band structure symm line object.
 Returns
A BandStructureSymmLine object

classmethod
from_old_dict
(d)[source]¶  Parameters
d (dict) – A dict with all data for a band structure symm line object.
 Returns
A BandStructureSymmLine object

get_branch
(index)[source]¶ 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)[source]¶ 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)[source]¶ 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

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

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)[source]¶ 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.

apply_scissor
(new_band_gap)[source]¶ 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

classmethod
from_dict
(d)[source]¶  Parameters
d (dict) – A dict with all data for a band structure symm line object.
 Returns
A BandStructureSymmLine object

classmethod
from_old_dict
(d)[source]¶  Parameters
d (dict) – A dict with all data for a band structure symm line object.
 Returns
A BandStructureSymmLine object

get_projection_on_elements
()[source]¶ 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)[source]¶ 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)[source]¶ 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)