\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.transport module

The module for electron transport property analysis.

class Tensor(temperature, potential, carrier_density, tensor, struc, type, unit)

Bases: object

The basic class for electron transport properties described by tensors, including ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’ and ‘SEEBECK’. Units must be consistent with the output files.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • type (str) – ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’ or ‘SEEBECK’.

  • unit (str) – Same as output file.

Returns:

self (Tensor) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(*file, output=None, method='normal')

Read electron transport properties by the BOLTZTRA keyword, including ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’, and ‘SEEBECK’. Though currently the geometry information is not required, it is saved if the standard output file is given.

Also allow for generating the following properties not printed by CRYSTAL:

  • Power Factor: \(S^{2}\sigma\). Any 2 from ‘SEEBECK’, ‘SIGMA’ and

    ‘SIGMAS’ are required.

  • ZT: \(\frac{S^{r}\sigma T}{\kappa}\). ‘KAPPA’ and any 2

    from ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’ are required.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors.

Note

For ‘SEEBECK’, all the 9 elements of the tensor was printed. As far as the developers have been aware of, it is symmetrized. Therefore the redundant ‘yx’, ‘zx’ and ‘zy’ dimensions are removed to keep consistent with other outputs.

Parameters:

  • file (str) – ‘DAT’ files by CRYSTAL BOLTZTRA keyword. Extendable only when method='power factor' or method='zt'.

  • output (str) – Properties output file.

  • method (str) – ‘normal’ to read 1 file, or ‘power factor’ or ‘zt’. For meanings, see above.

Returns:

cls (Tensor)

classmethod get_power_factor(obj1, obj2)

Get thermoelectric power factor object from any 2 objects of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

\[\text{Power Factor} = S^{2}\sigma\]

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

  • obj1 (Tensor) – Tensor object 1 of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

  • obj2 (Tensor) – Tensor object 2 of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

Returns:

cls (PowerFactor) – ‘POWERFACTOR’ type of object, in ‘W/m/K^2’.

classmethod get_zt(obj1, obj2, obj3)

Get thermoelectric dimensionless figure of merit (ZT) object from a ‘KAPPA’ object and any 2 from ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’.

\[ZT = \frac{S^{r}\sigma T}{\kappa}\]

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the ‘KAPPA’ entry.

Parameters:

  • obj1 (Tensor) – Tensor object 1 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

  • obj2 (Tensor) – Tensor object 2 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

  • obj3 (Tensor) – Tensor object 3 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

Returns:

cls (ZT) – ‘ZT’ type of object, in ‘dimensionless’.

plot(x_axis='potential', x_range=[], direction='xx', spin='sum', plot_series=[], plot_label=None, plot_color=None, plot_linestyle=None, plot_linewidth=None, zero_color='tab:gray', zero_linestyle='-', zero_linewidth=1.0, layout=None, title='default', figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, fig=None, ax_index=None, **kwargs)

Plot tensor-like transport properties in multiple ways:

  1. X_axis: Chemical potential \(\mu\); Plot series: Temperature \(T\).

  2. X_axis: Carrier density \(\rho(\mu; T)\); Plot series: Temperature \(T\).

  3. X_axis: Temperature \(T\); Plot series: Chemical potential \(\mu\).

For comparison of multiple systems, please refer to the plot.plot_transport_tensor() method.

Parameters:

  • x_axis (str) – X axis options, ‘potential’, ‘carrier’ or ‘temperature’. For meanings, see above.

  • x_range (list) – Display range of x axis. Y axis is self-adaptive.

  • direction (str|list) – Depending on the dimensionality of the system, including ‘xx’, ‘xy’, ‘xz’, ‘yx’, ‘yy’, ‘yz’, ‘zx’, ‘zy’ and ‘zz’. A list of options will generate nDirect*1 subplots. The direction of each subplot is annotated on the upper left corner.

  • spin (str) – Spin-polarized systems only. Electron spins to plot. ‘up’, ‘down’ or ‘sum’.

  • plot_series (list|array|float) – Values of the plot series. Should be commensurate with the choice of x_axis.

  • plot_label (list|str|None) – None for default values: plot_series and its unit. If str, prefixing that entry in front of the default value. If list, it should be 1*nPlotSeries for every plot line.

  • plot_color (list|str|None) – Similar to electronics.ElectronDOS.plot(). If str, use the same color for all the plot lines. If 1*nPlotSeries, use the same color for every plot line. If 2*nPlotSeries, use different colors for p-type and n-type carrier properties.

  • plot_linestyle (list|str|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.

  • plot_linewidth (list|float|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.

  • zero_color (str) – Color of the 0 value line.

  • zero_linestyle (str) – Linestyle of the 0 value line.

  • zero_linewidth (float) – Linewidth of the 0 value line.

  • layout (list[int]) – Layout of subplots. By default it is nDirection*1 gird of figures.

  • title (str|None) – Plot title. ‘default’ for the property plotted. ‘None’ for no title.

  • figsize (list) – Figure size.

  • legend (str|None) – Location of legend. None for not adding legend.

  • sharey (bool) – Share y axis for multiple subplots. Share x is enforced.

  • fontsize (float|int) – Font size of the title, subplot capations (direction), x and y axis capations.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (list[int]) – Developer Only, indices of axes in fig.axes.

  • **kwargs – Other arguments passed to the matplotlib Axes.plot() method. Applied to all the plots.

Returns:

fig (Figure) – Matplotlib Figure object.

class Distribution(energy, distr, struc, type, unit)

Bases: object

The class for electron transport properties described by distribution, currently transport distribution function (TDF) only. Units must be consistent with the output files.

Parameters:

  • energy (array) – Energy in eV.

  • distr (array) – nEnergy*nDimen*nSpin Distribution function

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\). nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • type (str) – ‘TDF’.

  • unit (str) – Same as output file.

Returns:

self (Distribution) – Attributes: ‘energy’, ‘function’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(boltztra_out, output=None)

Read electron transport distribution functions (‘TDF.DAT’) by the BOLTZTRA keyword. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

boltztra_out (str) – ‘DAT’ files by CRYSTAL BOLTZTRA keyword.

Returns:

cls (Distribution)

class Kappa(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Themal conductivity \(\kappa\). Inherited from transport.Tensor. Unit: W/m/K.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Kappa) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘KAPPA.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

  • file (str) – ‘KAPPA.DAT’ file.

  • output (str) – Properties output file.

Returns:

cls (Kappa)

class Sigma(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Electrical conductivity \(\sigma\). Inherited transport.Tensor. Unit: 1/Ohm/m.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Sigma) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SIGMA.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

  • file (str) – ‘SIGMA.DAT’ file.

  • output (str) – Properties output file.

Returns:

cls (Sigma)

class Seebeck(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Seebeck coefficient \(S\). Inherited transport.Tensor. Unit: V/K.

Note

For Seebeck, spin is always 1 but its dimension is kept to be commensurate with other classes.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*1 array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*1 array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Seebeck) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SEEBECK.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

  • file (str) – ‘SEEBECK.DAT’ file.

  • output (str) – Properties output file.

Returns:

cls (Seebeck)

class SigmaS(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Electrical conductivity times Seebeck coefficient \(\sigma S\). Inherited transport.Tensor. Unit: A/m/K.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (SigmaS) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SIGMAS.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

  • file (str) – ‘SIGMAS.DAT’ file.

  • output (str) – Properties output file.

Returns:

cls (SigmaS)

class PowerFactor(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Thermoelectrical power factor \(S^{2}\sigma\). Inherited transport.Tensor. Unit: W/m/K^2.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (PowerFactor) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file1, file2, output=None)

Get thermoelectric power factor object from any 2 files of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types. Though currently the geometry information is not required, it is saved if the standard output file is given.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

  • file1 (str) – File 1 in ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.

  • file2 (str) – File 2 in ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.

  • output (str) – Properties output file.

Returns:

cls (PowerFactor)

class ZT(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Thermoelectric dimensionless figure of merit (ZT) \(\frac{S^{r}\sigma T}{\kappa}\). Inherited transport.Tensor. Unit: dimensionless.

Parameters:

  • temperature (array) – Temperature in K

  • potential (array) – Chemical potential in eV.

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\).

  • tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (ZT) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file1, file2, file3, output=None)

Get ZT object from a ‘KAPPA’ file and any 2 files of ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’. Though currently the geometry information is not required, it is saved if the standard output file is given.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

  • file1 (str) – File 1 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.

  • file2 (str) – File 2 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.

  • file3 (str) – File 3 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.

  • output (str) – Properties output file.

Returns:

cls (PowerFactor)

class TDF(energy, distr, struc)

Bases: Distribution

Themal distribution function. Inherited from transport.Distribution. Unit: eV and 1/hbar^2*eV*fs/angstrom.

Parameters:

  • energy (array) – Energy in eV.

  • distr (array) – nEnergy*nDimen*nSpin Distribution function

  • carrier_density (array) – nT*nPot*nSpin array of carrier density in cm \(^{-3}\). nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.

  • struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Distribution) – Attributes: ‘energy’, ‘function’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘TDF.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

  • file (str) – ‘TDF.DAT’ file.

  • output (str) – Properties output file.

Returns:

cls (SigmaS)