phono3py-mode-plot.md

phono3py-mode-plot

phono3py-mode-plot is a command-line script for visualising the data from Phono3py kappa-m*.hdf5 files.

Theory

To better understand how to use the script, users are encouraged to read the "official" Phono3py paper for a description of how the calculations are performed Ref. 1. A brief summary is provided here for convenience.

Using the single-mode relaxation-time approximation (RTA), the macroscopic thermal conductivity tensor κ_latt is calculated as a sum of contributions from individual phonon modes λ according to:

where κ_λ are the modal thermal conductivities, C_λ are the (volumetric) heat capacities, v_λ ⊗ v_λ are the tensor products of the group velocities, τ_λ are the lifetimes, V is the volume of the unit cell and N is the number of phonon wavevectors (q) included in the summation.

The C_λ and v_λ are calculated within the harmonic approximation. τ_λ are calculated as the inverse of the phonon linewidths Γ_λ as:

Γ_λ are calculated as a sum of three-phonon scattering processes (collision and decay events) whose probabilities are determined as the product of a three-phonon interaction strength Φ_λλ'λ'' and a set of conservation of energy terms:

where ω_λ are the phonon frequencies and n_λ are the mode occupation numbers.

The averaged three-phonon interaction strength P_λ are a useful quantitative measure of how strongly the phonons in a given material interact:

where n_a is the number of atoms in the primitive cell and there are thus 3n_a at each wavevector.

Analysing the various modal properties can extract additional information from Phono3py calculations, and when comparing materials can be used to explain why a material has a particularly high or low thermal conductivity. The aim of phono3py-mode-plot is to provide an easy-to-use, but flexible, tool to do this.

Brief tutorial

a. Typical usage

A typical usage of phono3py-mode-plot is to generate scatter plots showing the frequncy dependence of modal quantities. Invoking the script with just an input file plots the frequency spectrum of the averaged modal thermal conductivity κ_λ = (κ_xx + κ_yy + κ_zz) / 3:

$ phono3py-mode-plot kappa-m161616.hdf5

By default, the output file is named as kappa-m161616.png, but this can be changed using the -o option:

$ phono3py-mode-plot kappa-m161616.hdf5 -o SnSe-Kappa.png

phono3py-mode-plot can plot a range of modal quantities by setting the --plot-y option. The available keywords are summarised in the following table:

Keyword	Description
freq	Frequencies νλ
kappa	Averaged thermal conductivity κλ
cv	Heat capacity Cλ
gv	Group velocity norms |vλ|
gamma	Linewidths Γλ
tau	Lifetimes τλ
mfp	Mean-free path norms |Λλ|
pp	Averaged ph-ph interaction strengths Pλ

Our first port of call is generally to compare the modal terms in the κ_latt equation above. We also use the --x-range, --y-range and --scatter-marker options to customise the plots:

$ phono3py-mode-plot kappa-m161616.hdf5 \
    --x-range="0 5.5" -o SnSe-Kappa.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='cv' \
    --x-range="0 5.5" --y-range="8.0 8.7" --scatter-marker='o' \
    -o SnSe-CV.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' \
    --x-range="0 5.5" --scatter-marker='s' \
    -o SnSe-GV.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='tau' \
    --x-range="0 5.5" --scatter-marker='p' \
    -o SnSe-Tau.png

The analagous --plot-x option can be used to select a different modal quantity to plot on the x axis - for example, there is usually a good correlation between κ_λ and the mean-free paths |Λ_λ| = |v_λ| × τ_λ:

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-x='mfp' -o SnSe-MFP-Kappa.png

The program can also be used to compare the Γ_λ to the P_λ (note that the P_λ are only calculated if the --full-pp option was set during the Phono3py calculation):

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gamma' \
    --x-range="0 5.5" -o SnSe-Gamma.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='pp' \
    --x-range="0 5.5" --y-range="5e-12 1e-9" --scatter-marker='o' \
    -o SnSe-PP.png

Finally, for T-dependent quantities a temperature can be selected with the --temp option (the default is 300 K):

$ phono3py-mode-plot --plot-y='tau' --x-range="0 5.5" -o SnSe-Tau-750.png
$ phono3py-mode-plot --plot-y='tau' --temp=750 --x-range="0 5.5" -o SnSe-Tau-750.png

b. Histogram plots

As an alternative to scatter plots, phono3py-mode-plot can also generate 2D histograms, which can show additional information with a colour map. Histogram plots are selected with the --hist argument:

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --hist \
    --x-range="0 5.5" -o SnSe-GV-Hist.png

By default, the histogram is coloured by the number (density) of modes. However, the individual modes can be weighted by any of the modal quantities using the --plot-c option - e.g.:

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --plot-c='kappa' \
    --hist --x-range="0 5.5" -o SnSe-GV-Hist-Kappa.png

This plot not only shows the frequency spectrum of the |v_λ|, but also provides information on how modes with different ν_λ and |v_λ| contribute to the thermal conductivity.

If plotting multiple quantities, it is usually desirable to treat the colour scale "qualitatively" and remove the colour bar. The colour bar can be omitted by specifying the --hist-no-cbar option. To obtain a consistent colour gradient across a set of plots, it is useful to set a common minimum and maximum value for colour normalisation using the --hist-norm option (appropriate values can be found by inspecting individual plots):

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-c='kappa' --hist \
    --hist-no-cbar --hist-norm="1e-8 1e-2" --x-range="0 5.5" \
    -o SnSe-Kappa-Hist-Kappa.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='cv' --plot-c='kappa' --hist \
    --hist-no-cbar --hist-norm="1e-8 1e-2" --x-range="0 5.5" --y-range="8.0 8.7" \
    -o SnSe-CV-Hist-Kappa.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --plot-c='kappa' --hist \
    --hist-no-cbar --hist-norm="1e-8 1e-2" --x-range="0 5.5" \
    -o SnSe-GV-Hist-Kappa.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='tau' --plot-c='kappa' --hist \
    --hist-no-cbar --hist-norm="1e-8 1e-2" --x-range="0 5.5" \
    -o SnSe-Tau-Hist-Kappa.png

Finally, the colour map used for plotting can be set using the --hist-cmap parameter:

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --plot-c='kappa' \
    --hist --hist-cmap='plasma' --x-range="0 5.5" \
    -o SnSe-GV-Hist-Kappa-Plasma.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --plot-c='kappa' \
    --hist --hist-cmap='jet' --x-range="0 5.5" \
    -o SnSe-GV-Hist-Kappa-Jet.png

c. Additional customisation

phono3py-mode-plot provides a number of parameters that can be used to customise the plots it generates - a full list can be seen with the -h option. Particularly useful options are summarised in the following table, some of which appear in the examples in the previous two sections:

--x-range, --y-range	Set the x/y-axis ranges
--x-scale, --y-scale, --c-scale	Set the x/y-axis scales and colour scale for histogram plots	linear, log
--hist-res	Set the resolution (number of bins) for histogram plots
--scatter-marker	Set the marker style for scatter plots
--scatter-colour-by-band	Set the gradient scheme used to colour markers in scatter plots by band index	fire, ice
--scatter-colour	Set a solid colour for markers in scatter plots (overrides --colour-by-band
--scatter-marker-size	Set the marker size for scatter plots
--hist-cmap	Set the colour map for histogram plots
--hist-no-cbar	Omit the colour bar from histogram plots
--hist-norm	Set the minimum/maximum values used to normalise the colour scale in histogram plots

Most of the modal properties typically vary by several orders of magnitue and are therefore plotted on a logarithmic scale by default. This can be changed by setting the --x-scale and --y-scale options to linear or log:

$ phono3py-mode-plot kappa-m161616.hdf5 --x-range="0 5.5" -o SnSe-Kappa-Log.png

$ phono3py-mode-plot kappa-m161616.hdf5 --x-range="0 5.5" --y-range="0 0.7" \
    --y-scale=linear -o SnSe-Kappa-Linear.png

Note that when using a linear scale quantities with characteristically small values are scaled to a sensible "order of magnitude" - for example the κ_λ are plotted in units of 10^-2 W m^-1 K^-1.

An analagous --c-scale parameter can be used to select linear or logarithmic colour scales for colouring histogram plots:

$ phono3py-mode-plot kappa-m161616.hdf5 --hist --x-range="0 5.5" \
    -o SnSe-Kappa-Hist-Kappa-LogColour.png

$ phono3py-mode-plot kappa-m161616.hdf5 --hist --x-range="0 5.5" \
    --c-scale='linear' -o SnSe-Kappa-Hist-LinearColour.png

For scatter plots, the default colour scheme is to colour the markers by band index, which produces a colour gradient when the frequencies are used as the x axis. The default scheme for doing this is the blue -> red fire scheme. An alternative blue -> cyan ice scheme can be selected using the --colour-by-band option:

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --x-range="0 5.5" \
    -o SnSe-GV-Fire.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' --x-range="0 5.5" \
    --scatter-colour-by-band='ice' -o SnSe-GV-Ice.png

Alternatively, a single solid colour can be selected with the --scatter-marker-colour option, which overrides --colour-by-band:

$ phono3py-mode-plot kappa-m161616.hdf5 --x-range="0 5.5" \
    --scatter-marker-colour='b' -o SnSe-Kappa.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='cv' \
    --x-range="0 5.5" --y-range="8.0 8.7" --scatter-marker='o' \
    --scatter-marker-colour='r' -o SnSe-CV.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='gv' \
    --x-range="0 5.5" --scatter-marker='s' --scatter-marker-colour='g' \
    -o SnSe-GV.png

$ phono3py-mode-plot kappa-m161616.hdf5 --plot-y='tau' \
    --x-range="0 5.5" --scatter-marker='p' --scatter-marker-colour='orange' \
    -o SnSe-Tau.png

FAQs and Troubleshooting

I want a PDF/EPS/TIFF/JPEG file instead of a PNG

You can do this by setting an output file name (-o) with the extension of the file type you want - e.g.:

$ phono3py-mode-plot kappa-m161616.hdf5 -o SnSe-Kappa.pdf
$ phono3py-mode-plot kappa-m161616.hdf5 -o SnSe-Kappa.eps
$ phono3py-mode-plot kappa-m161616.hdf5 -o SnSe-Kappa.tiff
$ phono3py-mode-plot kappa-m161616.hdf5 -o SnSe-Kappa.jpg

I get runtime warnings about masked data points and/or division by zero

You may see warnings similar to either or both of the following while running the script - provided the data in the input file is "sane" these should not affect the output and can be safely ignored:

/Volumes/Data/Repositories/Phono3py-Power-Tools/phono3py-mode-plot:492:
 RuntimeWarning: An additional 21 data points with values <= 0 were masked.
  "An additional {0} data points with values <= 0 were masked.".format(num_mask_2 - num_mask_1), RuntimeWarning

/Volumes/Data/Repositories/Phono3py-Power-Tools/Phono3pyPowerTools/Phono3pyIO.py:246:
 RuntimeWarning: divide by zero encountered in divide
  mode_gamma > 0.0, 1.0 / (2.0 * 2.0 * math.pi * mode_gamma), 0.0

I get warnings about missing fonts and my plot renders in DejaVu Sans

Unless the --mpl-default option is set, phono3py-mode-plot tries to render plots using the Times New Roman font. On some Python installations you will see an error message such as the following and the plot will be rendered in (fairly plain) DejaVu Sans:

/mnt/iusers01/fatpou01/chem02/w35422js/Miniconda/miniconda2/lib/python2.7/site-packages/matplotlib/font_manager.py:1331:
 UserWarning: findfont: Font family [u'Times New Roman'] not found. Falling back to DejaVu Sans
  (prop.get_family(), self.defaultFamily[fontext]))

Fixing "missing" Matplotlib fonts can be tricky - as a quick Google search will attest - but if you are using Anaconda or Miniconda (recommended) you can install Times New Roman to the right place by installing the mscorefonts package:

conda install -c conda-forge mscorefonts

Notes and references

The equations in this document were produced using the Online LaTeX Equation Editor from CodeCogs.

1. A. Togo, L. Chaput and I. Tanaka, Physical Review B 91, 093206 (2015), DOI: 10.1103/PhysRevB.91.094306