pymatgen.electronic_structure package

Submodules

pymatgen.electronic_structure.bandstructure module

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

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

Bases: object

Generic band structure data, defined by a list of Kpoints

and corresponding energies for each of them.

kpoints[source]

Kpoints in the band structure.

Type:

list[Kpoint]

lattice_rec[source]

The reciprocal lattice of the band structure.

Type:

Lattice

efermi[source]

The Fermi level.

Type:

float

is_spin_polarized[source]

Whether the band structure is spin-polarized.

Type:

bool

bands[source]

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[source]

The number of bands in the band structure.

Type:

int

structure[source]

The structure.

Type:

Structure

projections[source]

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][source]

JSON-serializable dict representation of BandStructure.

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

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[source]

Parameters:

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

Returns:

BandStructure

get_band_gap() → dict[str, Any][source]

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][source]

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[source]

Get the direct band gap.

Returns:

The direct band gap value.

Return type:

float

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

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) → NDArray | None[source]

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, NDArray][source]

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

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[source]

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][source]

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[source]

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: NDArray, eigenvals: dict[Spin, list], lattice: Lattice, efermi: float, labels_dict: dict[str, Kpoint], coords_are_cartesian: bool = False, structure: Structure | None = None, projections: dict[Spin, NDArray] | None = None)[source]

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

JSON-serializable dict representation of BandStructureSymmLine.

get_branch(index: int) → list[dict[str, Any]][source]

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][source]

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: NDArray, lattice: Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, label: str | None = None)[source]

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[source]

Fractional a coordinate of the kpoint.

as_dict() → dict[str, Any][source]

JSON-serializable dict representation of the kpoint.

property b: float[source]

Fractional b coordinate of the kpoint.

property c: float[source]

Fractional c coordinate of the kpoint.

property cart_coords: NDArray[source]

The Cartesian coordinates of the kpoint as a NumPy array.

property frac_coords: NDArray[source]

The fractional coordinates of the kpoint as a NumPy array.

classmethod from_dict(dct: dict) → Self[source]

Create from a dict.

Parameters:

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

Returns:

Kpoint

property label: str | None[source]

The label associated with the kpoint.

property lattice: Lattice[source]

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

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

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][source]

JSON-serializable dict representation of BandStructureSymmLine.

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

Parameters:

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

Returns:

A LobsterBandStructureSymmLine object.

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

Parameters:

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

Returns:

A LobsterBandStructureSymmLine object

get_projection_on_elements() → dict[Spin, list][source]

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[Element, list]) → dict[Spin, list][source]

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[source]

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

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

MSONable dict.

static check_acc_bzt_bands(sbs_bz, sbs_ref, warn_thr=(0.03, 0.03))[source]

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[source]

Parameters:

data – Dict representation.

Returns:

BoltztrapAnalyzer

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

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

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

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

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

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

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, maximize=True, min_temp=None, max_temp=None, min_doping=None, max_doping=None, isotropy_tolerance=0.05, use_average=True)[source]

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 – target property, i.e. “seebeck”, “power factor”, “conductivity”, “kappa”, or “zt”

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

• min_temp – minimum temperature allowed

• max_temp – maximum temperature allowed

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

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

• isotropy_tolerance – tolerance for isotropic (0.05 = 5%)

• use_average – True for avg of eigenval, False for max eigenval

Returns:

{“value”, “temperature”, “doping”, “isotropic”}

Return type:

A dictionary with keys {“p”, “n”, “best”} with sub-keys

get_hall_carrier_concentration()[source]

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

Parameters:

temp – Temperature.

Returns:

The chemical potential bounds at that temperature.

get_power_factor(output='eigs', doping_levels=True, relaxation_time=1e-14)[source]

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

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

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

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

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

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

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

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

Parse .outputtrans file.

Parameters:

path_dir – dir containing boltztrap.outputtrans

Returns:

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

static parse_struct(path_dir)[source]

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

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[source]

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

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

MSONable dict.

property bs[source]

The BandStructure.

property nelec[source]

Number of electrons.

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

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[source]

Write the def to an output file.

Parameters:

output_file – Filename

write_energy(output_file) → None[source]

Write the energy to an output file.

Parameters:

output_file – Filename

write_input(output_dir) → None[source]

Write the input files.

Parameters:

output_dir – Directory to write the input files.

write_intrans(output_file) → None[source]

Write the intrans to an output file.

Parameters:

output_file – Filename

write_proj(output_file_proj: str, output_file_def: str) → None[source]

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[source]

Write the structure to an output file.

Parameters:

output_file – Filename

compare_sym_bands(bands_obj, bands_ref_obj, nb=None)[source]

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[source]

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

Parameters:

filename – Cube filename.

Returns:

Energy data.

seebeck_eff_mass_from_carr(eta, n, T, Lambda) → float[source]

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[source]

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

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: Sequence[float], cohp: dict[Spin, NDArray], are_coops: bool = False, are_cobis: bool = False, are_multi_center_cobis: bool = False, icohp: dict[Spin, NDArray] | None = None)[source]

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][source]

JSON-serializable dict representation of COHP.

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

Generate Cohp from a dict representation.

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

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[source]

Convenient wrapper to get the ICOHP for a particular spin.

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

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[source]

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

Bases: Cohp

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

are_coops[source]

Whether the object consists of COOPs.

Type:

bool

are_cobis[source]

Whether the object consists of COBIs.

Type:

bool

efermi[source]

The Fermi level.

Type:

float

energies[source]

Sequence of energies.

Type:

Sequence[float]

structure[source]

Structure associated with the COHPs.

Type:

Structure

cohp[source]

The average COHP.

Type:

Sequence[float]

icohp[source]

The average ICOHP.

Type:

Sequence[float]

all_cohps[source]

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

Type:

dict[str, Sequence[float]]

orb_res_cohp[source]

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][source]

JSON-serializable dict representation of CompleteCohp.

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

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[source]

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[source]

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[source]

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[source]

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[source]

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[Vector3D], 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)[source]

Bases: MSONable

Collection of IcohpValues.

are_coops[source]

Whether these are ICOOPs.

Type:

bool

are_cobis[source]

Whether these are ICOOPs.

Type:

bool

is_spin_polarized[source]

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[Vector3D]) – 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[source]

Whether this is COBI.

property are_coops: bool[source]

Whether this is COOP.

extremum_icohpvalue(summed_spin_channels: bool = True, spin: Spin = Spin.up) → float[source]

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

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

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][source]

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][source]

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[source]

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[source]

Whether this is spin polarized.

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

Bases: MSONable

Information for an ICOHP or ICOOP value.

energies[source]

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

Type:

NDArray

densities[source]

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

Type:

NDArray

energies_are_cartesian[source]

Whether the energies are cartesian.

Type:

bool

are_coops[source]

Whether the object is COOP/ICOOP.

Type:

bool

are_cobis[source]

Whether the object is COBIS/ICOBIS.

Type:

bool

icohp[source]

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

Type:

dict

summed_icohp[source]

The summed ICOHP/COHP values.

Type:

float

num_bonds[source]

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

Whether these are ICOBIs.

Returns:

bool

property are_coops: bool[source]

Whether these are ICOOPs.

Returns:

bool

property icohp: dict[Spin, float][source]

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[source]

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[source]

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[source]

Whether this is a spin polarized calculation.

Returns:

bool

property num_bonds: int[source]

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

Returns:

int

property summed_icohp: float[source]

Summed ICOHPs of both spin channels if spin polarized.

Returns:

ICOHP value in eV.

Return type:

float

property summed_orbital_icohp: dict[str, float][source]

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]

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][source]

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: Vector3D = (0, 0, 1))[source]

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 (Vector3D) – Spin axis, and will be converted to unit vector (default is (0, 0, 1)).

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

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: Vector3D) → Self[source]

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 (Vector3D) – Spin axis.

classmethod from_moment_relative_to_crystal_axes(moment: Vector3D, lattice: Lattice) → Self[source]

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

Used for obtaining moments from magCIF file.

Parameters:

• moment (Vector3D) – Magnetic moment.

• lattice (Lattice) – Lattice.

Returns:

Magmom

get_00t_magmom_with_xyz_saxis() → Self[source]

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: Vector3D | None = None) → tuple[list[Magmom], NDArray][source]

Ensure magmoms use the same spin axis.

Parameters:

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

• saxis (Vector3D) – An optional global spin axis.

Returns:

Magmoms and their global spin axes.

Return type:

tuple[list[Magmom], NDArray]

get_moment(saxis: Vector3D = (0, 0, 1)) → NDArray[source]

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 (Vector3D) – Spin quantization axis.

Returns:

NDArray of length 3.

get_moment_relative_to_crystal_axes(lattice: Lattice) → Vector3D[source]

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

Used for writing moments to magCIF file.

Parameters:

lattice (Lattice) – The lattice.

Returns:

Vector3D

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

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[source]

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[source]

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[source]

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[source]

Project moment along spin quantization axis.

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

Returns:

The projected moment.

Return type:

float