pymatgen.electronic_structure.bandstructure module

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

Json-serializable dict representation of BandStructureSymmLine.

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., “Gamma-X”)
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_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_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
is_metal(efermi_tol=0.0001)[source]

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

Json-serializable dict representation of BandStructureSymmLine.

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)
a

Fractional a coordinate of the kpoint

as_dict()[source]

Json-serializable dict representation of a kpoint

b

Fractional b coordinate of the kpoint

c

Fractional c coordinate of the kpoint

cart_coords

The cartesian coordinates of the kpoint as a numpy array

frac_coords

The fractional coordinates of the kpoint as a numpy array

label

The label associated with the kpoint

lattice

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

get_reconstructed_band_structure(list_bs, efermi=None)[source]

This method takes a list of band structures and reconstruct 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
  • 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)