tp.data package

Module contents

Data generation, loading and saving.

Submodules

tp.data.load module

Data loading tools.

Loads data from codes into a dictionary, with units and array structures standardised. Also adds a meta subdictionary, which contains units, array dimensions and the data source.

tp.data.load.amset(filename, quantities='all', doping='n')

Loads AMSET transport data from json.

Includes unit conversion and outputs units (see tp.settings). Swaps temperature and doping indices so temperature is first, for consistency with other codes, and mobility is formatted as an array, like scattering_rates is in the mesh.h5 file. Maintains basic compatibility with amset 0.1.

Parameters

• filename (str) – amset transport json filepath.

• quantites (str or list, optional) – values to extract. Accepts AMSET keys and power_factor. All loads the whole file, power factor can be added if it is not in the file. Loads dependent properties. Default: all.

• doping (str, optional) – doing type (n or p). If there is more than one, defaults to n, else this is ignored.

Returns

extracted values.

Return type

dict

tp.data.load.amset_mesh(filename, quantities='all', doping='n', spin='avg')

Loads AMSET mesh data from h5.

Can also weight rates. Includes unit conversion and outputs units (see tp.settings). Swaps temperature and doping indices so temperature is first, for consistency with other codes.

Parameters

• filename (str) – amset mesh h5 filepath.

• quantites (str or list, optional) – values to extract. Accepts AMSET keys, without spin channels, which are dealt with in the spin variable. Also accepts ibz_weights, the weights of the irreducible k-points, fd_weights, the weights of the energies wrt the derivative of the Fermi-Dirac distribution, weighted_rates, scattering_rates weighted by fd_weights and averaged over kpoints and occupation, the Fermi-Dirac occupation. “all” loads all quantities in the file, which does not include ibz_weights, fd_weights, weighted_rates or occupation. Loads dependent properties. Default: all.

• doping (str, optional) – doing type (n or p). If there is more than one, defaults to n, else this is ignored.

• spin (str, optional) – spin. Accepts up, down or avg. If avg and there is only one spin channel, selects that, else averages both. If avg, assumes non-spin separated bands and so multiplies occupation by 2. Default: avg.

Returns

extracted values.

Return type

dict

tp.data.load.boltztrap(filename, quantities='all', doping='n')

Loads BoltzTraP data from the tp boltztrap.hdf5 file.

Includes unit conversion and outputs units (see tp.settings).

Parameters

• filename (str) – boltztrap.hdf5 filepath.

• quantites (str or list, optional) – values to extract. Accepts boltztrap.hdf5 keys or all. Default: all.

• doping (str, optional) – doping. Default: n.

Returns

extracted values.

Return type

dict

tp.data.load.get_path(yamldata)

Extracts the path from a phonopy yaml.

Works for the old and new phonopy and sumo yaml files.

Parameters

yamldata (dict) – raw phonopy dispersion data (i.e. from yaml.safe_load).

Returns

• list – x tick ordinates.

• list – x tick labels.

tp.data.load.phono3py(filename, quantities='all')

Loads Phono3py data from kappa hdf5.

Can also calculate lifetimes, mean free paths and occupations. Includes unit conversions and outputs units and index order for all the data (see tp.settings). Also corrects mode_kappa for different phono3py versions. Also converts the default 6x1 direction matrices into 3x3 ones for compatability with other codes.

Parameters

• filename (str) – phono3py kappa hdf5 filepath.

• quantities (str or list, optional) – values to extract. Accepts Phono3py keys, lifetime, mean_free_path and occupation. ‘all’ loads all Phono3py keys, but lifetime etc. must be loaded separately. Default: all.

Returns

output data.

Return type

dict

tp.data.load.phonopy_dispersion(filename, xdata=None)

Loads phonopy dispersion, and can scale the x values.

Scaling the x values is necessary to plot multiple dispersions on the same axes.

Parameters

• filename (str) – phonopy or sumo band.yaml filepath.

• xdata (dict, optional) – data for the dispersion to scale this to. Should have the same path, must have the same number of labels. Not necessary if using tp.plot.phonons.add_multi. Default: None.

Returns

dispersion data.

Return type

dict

tp.data.load.phonopy_dos(filename, poscar='POSCAR', atoms=None)

Loads phonopy DoS and collates data per atom and as a total.

By default reads atom names from a POSCAR, but can be overridden to allow for separation of environments.

Parameters

• filename (str) – path to phonopy projected_dos.dat or similar.

• poscar (str, optional) – path to POSCAR. Ignored if atoms specified. Default: POSCAR.

• atoms (str or array-like, optional) – atoms in POSCAR order. Atom names can be repeated, in which case their contributions are summed. Numbers can indicate repetition in the manner of a chemical formula, so the following are all acceptable and equivalent: “Ba 1 Sn 2 O 3”, “Ba Sn Sn O O O”, “Ba Sn O 3”. Different environments can be distinguised with different atom names. Default: read from POSCAR.

Returns

frequency, DoS per atom and total.

Return type

dict

tp.data.load.phonopy_gruneisen(filename)

Loads phonopy gruneisen data.

Does not load path data, but can load from files with a q-point path, which will often be preferable if projecting onto a phonon dispersion.

Parameters

filename (str) – phonopy gruneisen.yaml filepath.

Returns

gruneisen data.

Return type

dict

tp.data.load.scale_to_path(x, tickpos, scalepos)

Scales data to a path.

Useful to make different phonopy runs fit together or to map gruneisen data on a phonon dispersion.

Parameters

• x (list) – wavevector ordinates.

• tickpos (list) – tick wavevectors for scaling.

• scalepos (list) – scale tick wavevectors.

Returns

wavevector ordinates.

Return type

list

tp.data.utilities module

Utilities to manipulate data.

Reads variables and selects specific conditions. Requires [‘meta’][‘dimensions’] subdictionaries provided by tp load modules.

tp.data.utilities.merge(data, dependent)

Merges data dictionaries with shared dependent variables.

Particularly with amset in mind, to relieve memory constraints. Currently works for one dependent variable, so looping will often be required. An output in the form [ab,cd] would require three merges: a to b, c to d and ab to cd (or a to c etc.).

Parameters

• data (list of dicts) – data to merge. Requires tp metadata and dependent variable.

• dependent (string) – dependent variable.

Returns

merged data.

Return type

dict

tp.data.utilities.resolve(data, quantities, **kwargs)

Selects particular values of arbitrary quantities.

Requires the meta/dimensions dictionaries found in later versions of tp. Currently cannot accept dictionary keys (e.g. dtype=’n’) if they are not in the 0th index.

Parameters

• data (dict) – data with meta/dimensions dictionaries and quantities.

• quantities (array-like or str) – quantities to resolve

• kwargs –

  dimesions to resolve. Rounds to nearest available value. Common options include:

  direction

  direction to resolve, accepts x-z/, a-c, average/ avg/ mean/ arithmetic/ arith, or norm/ normal or harmonic/ harm.

  dtype

  n or p.

  stype

  codes from amset, e.g. IMP, or overall.

  doping

  concentration, not to be confused with dtype.

  temperature

  temperature.

Returns

resolved data.

Return type

dict

tp.data.run module

External code running tools.

tp.data.run.boltztrap(tmax=1001, tstep=50, tmin=None, doping=array([1e+18, 1.53992653e+18, 2.37137371e+18, 3.65174127e+18, 5.62341325e+18, 8.65964323e+18, 1.33352143e+19, 2.05352503e+19, 3.16227766e+19, 4.86967525e+19, 7.49894209e+19, 1.15478198e+20, 1.77827941e+20, 2.73841963e+20, 4.21696503e+20, 6.49381632e+20, 1e+21]), ke_mode='boltzmann', vasprun='vasprun.xml', kpoints=None, relaxation_time=1e-14, lpfac=10, run=True, analyse=True, output='boltztrap.hdf5', run_dir='.', clean=False, **kwargs)

Runs BoltzTraP from a VASP density of states (DoS).

Wrapper for pymatgen.electronic_structure.boltztrap but runs faster than using the built in from_files method and outputs an hdf5 file. Note: BoltzTraP can be a fickle friend, so if you’re getting errors, it may be worth reinstalling or trying on a different machine.

Parameters

• tmax (float, optional) – maximum temperature in K. Default: 1000.

• tstep (float, optional) – temperature step in K. Default: 50.

• tmin (float, optional) – minimum temperature in K. This does not reduce how many temperatures are run in BoltzTraP, only how many are saved to hdf5. Default: tstep.

• doping (array-like, optional) – doping concentrations in cm-1. Default: np.logspace(18, 21, 17).

• k_mode (str, optional) –

  method for calculating the electronic thermal conductivity. Options:

  boltzmann (default):

  standard boltztrap method. Madsen and Singh, Comput. Phys. Commun. 2006, 175, 67.

  wiedemann:

  Wiedemann-Franz law with constant L = 2.44E-8. Franz and Wiedemann, Ann. Phys. 1853, 165, 497.

  snyder:

  Wiedemann-Franz law, with L varying with Seebeck. Kim et al., APL Mat. 2015, 3, 041506.

• vasprun (str, optional) – path to vasprun. Default: vasprun.xml.

• kpoints (str, optional) – path to KPOINTS file if there are zero-weighted k-points. Default: KPOINTS.

• relaxation_time (float, optional) – charge carrier relaxation time. Default: 1e-14.

• lpfac (int, optional) – DoS interpolation factor. Default: 10.

• run (bool, optional) – run BoltzTraP. Default: True.

• analyse (bool, optional) – analyse BoltzTraP. Default: True.

• output (str, optional) – output hdf5 filename. Default: boltztrap.hdf5.

• run_dir (str, optional) – path to run boltztrap in. Default: current directory.

• clean (bool, optional) – remove boltztrap directory post-run. Default: False.

• kwargs – passed to pymatgen.electronic.structure.boltztrap.BoltztrapRunner.

Returns

instead prints to hdf5 (see below).

Return type

None

average_eff_massdict

the charge carrier effective mass in units of m_e, taking into account all bands, as opposed to the single parabolic band model. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations, 3, 3).

conductivitydict

electric conductivity in S m-1. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations, 3, 3).

dopingarray-like

carrier concentration in cm-1. Identical to input.

electronic_thermal_conductivitydict

electronic thermal conductivity in W m-1 K-1. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations, 3, 3).

fermi_leveldict

fermi level at different temperatures in units of eV. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations).

power_factordict

power factor in W m-1 K-2. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations, 3, 3).

seebeckdict

Seebeck coefficient in muV K-1. Data is a dictionary with an array each for n and p doping, of shape (temperatures, concentrations, 3, 3).

temperaturenumpy array

temperatures in K.

metadict

metadata:

interpolation_factorint

lpfac.

ke_modestr

as input.

relaxation_timefloat

as input.

socbool

spin-orbit coupling calculation.

unitsdict

units of each property above.

tp.data.save module

Utilities to save data.

tp.data.save.cumkappa(filename, mfp=False, temperature=300, direction='avg', output='tp-cumkappa', extension='dat', force=False)

Saves cumulated lattice thermal conductivity against frequency or mfp.

Saves in normal units and percent to a dat file.

Parameters

• filename (str) – data filepath

• mfp (bool, optional) – calculate against mean free path not frequency. Default: False.

• temperature (float or int, optional) – temperature in K. Default: 300.

• direction (str, optional) – crystal direction, accepts x-z/ a-c or average/ avg. Default: average.

• output (str, optional) – output filename (no extension). Default: tp-kappa-target.

• extension (str or list, optional) – output filetype. Must be dat and/ or csv. Default: dat.

• force (bool, optional) – force overwrite input file. Default: False.

Returns

instead writes to dat.

Return type

none

tp.data.save.hdf5(data, output)

Saves to hdf5.

Aims to make saving nested dictionaries easy, works for 3 layers.

Parameters

• data (dict) – data to save.

• output (str) – output filename.

Returns

instead writes to file.

Return type

None

tp.data.save.kappa_target(filename, zt=2, direction='avg', doping='n', tinterp=None, dinterp=None, kind='linear', output='tp-kappa-target', force=False)

Save target kappa_l to hdf5.

Also saves temperature and doping and metadata.

Parameters

• filename (str) – data filepath.

• zt (float, optional) – target ZT. Default: 2.

• direction (str, optional) – crystal direction, accepts x-z/ a-c or average/ avg. Default: average.

• doping (str, optional) – doping type for BoltzTraP. Must be n or p. Default: n.

• tinterp (int, optional) – density of interpolation for temperature. None turns it off. Default: 200.

• dinterp (int, optional) – density of interpolation for doping. None turns it off. Default: 200.

• kind (str, optional) – interpolation kind. Default: linear.

• output (str, optional) – output filename (no extension). Default: tp-kappa-target.

• force (bool, optional) – force overwrite input file. Default: False.

Returns

instead writes to hdf5.

Return type

none

tp.data.save.phono3py(filename, quantities, output='tp-phono3py', force=False)

Save calculated properties to hdf5.

Also saves dependent properties (temperature etc.) and metadata.

Parameters

• filename (str) – filepath.

• quantities (str or list) – values to save. Accepts any phonop3y properties, but only lifetime, mean_free_path and/ or occupation are recommended.

• output (str, optional) – output filename (no extension). Default: tp-phono3py.

• force (bool, optional) – force overwrite input file. Default: False.

Returns

instead writes to hdf5.

Return type

none

tp.data.save.prompt(filename, output)

Prompts before overwrite.

Parameters

• filename (str) – input filename.

• output (str or list) – output filename(s).

Returns

Return type

none

tp.data.save.zt(efile, kfile=None, direction='avg', doping='n', tinterp=None, dinterp=None, kind='linear', output='tp-zt', force=False)

Save ZT to hdf5 and highlights to yaml.

Also saves temperature and doping and metadata.

Parameters

• efile (str) – electronic data filepath.

• kfile (str or float or int) – phononic data filepath or lattice thermal conductivity value.

• direction (str, optional) – crystal direction, accepts x-z/ a-c or average/ avg. Default: average.

• doping (str, optional) – doping type for BoltzTraP. Must be n or p. Default: n.

• tinterp (int, optional) – density of interpolation for temperature. None turns it off. Default: 200.

• dinterp (int, optional) – density of interpolation for doping. None turns it off. Default: 200.

• kind (str, optional) – interpolation kind. Default: linear.

• output (str, optional) – output filename (no extension). Default: tp-zt.

• force (bool, optional) – force overwrite input file. Default: False.

Returns

instead writes to hdf5, yaml and stdout.

Return type

none