pymatgen.electronic_structure.boltztrap module

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

Class used to 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]
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 corresponing 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

static from_dict(data)[source]
static from_files(path_dir, dos_spin=1)[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:

a BoltztrapAnalyzer object

get_average_eff_mass(output='eigs', doping_levels=True)[source]

Gives 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 (string) – ‘eigs’ for eigenvalues, ‘tensor’ for the full
  • and 'average' for an average (tensor) –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
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]

gives the carrier concentration (in cm^-3)

Returns
a dictionary {temp:[]} with an array of carrier concentration (in cm^-3) at each temperature The array relates to each step of electron chemical potential
get_complete_dos(structure, analyzer_for_second_spin=None)[source]

Gives a CompleteDos object with the DOS from the interpolated projected band structure :param the structure: :type the structure: necessary to identify sites for projection :param analyzer_for_second_spin must be specified to have a: :param CompleteDos with both Spin components:

Returns:a CompleteDos object

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_conductivity(output='eigs', doping_levels=True, relaxation_time=1e-14)[source]

Gives 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 (string) – the type of output. ‘tensor’ give the full
  • tensor, 'eigs' its 3 eigenvalues and (3x3) –
  • the average of the three eigenvalues ('average') –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
  • 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]

This method takes in eigenvalues over a range of carriers, temperatures, and doping levels, and tells you what is 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]

gives 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
a dictionary {temp:[]} with an array of Hall carrier concentration (in cm^-3) at each temperature The array relates to each step of electron chemical potential
get_mu_bounds(temp=300)[source]
get_power_factor(output='eigs', doping_levels=True, relaxation_time=1e-14)[source]

Gives 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 (string) – the type of output. ‘tensor’ give the full 3x3
  • 'eigs' its 3 eigenvalues and (tensor,) –
  • the average of the three eigenvalues ('average') –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
  • 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 dictionnary {temp

get_seebeck(output='eigs', doping_levels=True)[source]

Gives 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 (string) – the type of output. ‘tensor’ give the full
  • tensor, 'eigs' its 3 eigenvalues and (3x3) –
  • the average of the three eigenvalues ('average') –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
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_symm_bands(structure, efermi, kpt_line=None, labels_dict=None)[source]

Function 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]

Gives 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 (string) – the type of output. ‘tensor’ give the full 3x3
  • 'eigs' its 3 eigenvalues and (tensor,) –
  • the average of the three eigenvalues ('average') –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
  • k_el (boolean) – 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, kl=1.0)[source]

Gives 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 (string) – the type of output. ‘tensor’ give the full 3x3
  • 'eigs' its 3 eigenvalues and (tensor,) –
  • the average of the three eigenvalues ('average') –
  • doping_levels (boolean) – True for the results to be given at
  • doping levels, False for results (different) –
  • different electron chemical potentials (at) –
  • 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]

Parses the conductivity and Hall tensors :param path_dir: Path containing .condtens / .halltens files :param 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]

Parses boltztrap.intrans mainly to extract the value of scissor applied to the bands or some other inputs :param path_dir: (str) dir containing the boltztrap.intrans file

Returns:a dictionary containing various inputs that had been used in the Boltztrap run.
Return type:intrans (dict)
static parse_outputtrans(path_dir)[source]

Parses .outputtrans file

Parameters:path_dir – dir containing boltztrap.outputtrans
Returns:tuple - (run_type, warning, efermi, gap, doping_levels)
static parse_struct(path_dir)[source]

Parses boltztrap.struct file (only the volume) :param path_dir: (str) dir containing the boltztrap.struct file

Returns:(float) volume
static parse_transdos(path_dir, efermi, dos_spin=1, trim_dos=False)[source]

Parses .transdos (total DOS) and .transdos_x_y (partial DOS) files :param path_dir: (str) dir containing DOS files :param efermi: (float) Fermi energy :param dos_spin: (int) -1 for spin down, +1 for spin up :param trim_dos: (bool) whether to post-process / trim DOS

Returns:tuple - (DOS, dict of partial DOS)
exception BoltztrapError(msg)[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)[source]

Bases: object

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.
bs
nelec
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) :param path_dir: directory in which to run BoltzTraP :type path_dir: str :param convergence: whether to check convergence and make

corrections if needed
Parameters:
  • 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

Returns:

write_def(output_file)[source]
write_energy(output_file)[source]
write_input(output_dir)[source]
write_intrans(output_file)[source]
write_proj(output_file_proj, output_file_def)[source]
write_struct(output_file)[source]
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.

read_cube_file(filename)[source]