tp.plot package

Module contents

Plotting tools.

The main tools are called add_ something, which take a set of axes and data dictionaries as inputs, amoung other things; these are accompanied by ancillary scripts including formatting scripts and a module of colourmap generators.

Submodules

tp.plot.colour module

Colour scheme and colourmap generators.

tp.plot.colour.elbow(cmid, cmin='white', cmax='black', midpoint=0.7, alpha=1.0, density=512)

Generates bigradient colourmaps.

Allows for full customisation of colours and midpoint location. Accepts named, hex and RGB (values 0-1) formats.

Parameters

• cmid (str) – colour at midpoint.

• cmin (str, optional.) – colour at minimum. Default: white.

• cmax (str, optional) – colour at maximum. Default: black.

• midpoint (float, optional) – midpoint position (from 0-1). Default: 0.7.

• alpha (float, optional) – colour alpha (from 0-1). Default: 1.0.

• density (int, optional) – number of colours to output. Default: 512.

Returns

colourmap.

Return type

colormap

tp.plot.colour.highlight(cmap, colour, position=[0], density=512)

Highlights values in a colourmap.

Parameters

• cmap (colormap) – colourmap to edit

• colour (str or array-like) – colours.

• position (int or array-like, optional) – position of the colours within density. Default: 0.

• density (int, optional) – number of colours. Default: 512

Returns

highlighted colourmap.

Return type

colormap

tp.plot.colour.hsb2rgb(h, s, b, alpha=1)

Converts hsb to an rgba colour array.

Parameters

• h (float) – hue.

• s (float) – saturation.

• b (float) – brightness.

• alpha (float, optional) – colour alpha (from 0-1). Default: 1.

Returns

rgba.

Return type

list

tp.plot.colour.linear(cmax, cmin='white', alpha=1.0, density=512)

Generates single-gradient colour maps.

Accepts named, hex and RGB (values 0-1) formats.

Parameters

• cmax (str) – colour at maximum.

• cmin (str, optional) – colour at minimum. Default: white.

• alpha (float, optional) – colour alpha (from 0-1). Default: 1.0.

• density (int) – number of colours to output. Default: 512.

Returns

colourmap.

Return type

colourmap

tp.plot.colour.skelton(density=512, alpha=1.0)

Generates Jonathan Skelton’s rainbowy colourmap.

Parameters

• density (int, optional) – number of colours. Default: 512.

• alpha (float, optional) – alpha (from 0-1). Default: 1.

Returns

colourmap.

Return type

colourmap

tp.plot.colour.uniform(cmid, cmin='white', cmax='#333333', alpha=1.0, density=512)

Generates bigradient colourmaps.

Adjusts mid colour position to keep the overall gradient even. Accepts named, hex and RGB (values 0-1) formats.

Parameters

• cmid (str) – colour at midpoint.

• cmin (str, optional.) – colour at minimum. Default: white.

• cmax (str, optional) – colour at maximum. Default: #333333.

• alpha (float, optional) – colour alpha (from 0-1). Default: 1.0.

• density (int, optional) – number of colours to output. Default: 512.

Returns

colourmap.

Return type

colormap

tp.plot.frequency module

Functions which plot phonon frequency on the x-axis.

Each function takes a set of axes and data dictionary as its main input, and and an invert argument to plot sideways by a phonon dispersion, and a main argument, which determines if axes limits are set and sometimes how scaling is handled, which helps if plotting multiple quantities on the same axes.

tp.plot.frequency.add_cum_kappa(ax, data, temperature=300, direction='avg', label=None, main=True, invert=False, scale=False, colour=None, fill=False, fillcolour=0.2, line=True, linestyle='-', marker=None, verbose=False, **kwargs)

Cumulates and plots kappa against frequency.

Can plot data from multiple data dictionaries and directions. Colour, linestyle etc. are looped, so if you have two datasets and two directions, but only specify two colours, the first will apply to the first direction in both datasets, whereas if you want one for the first dataset and one for the second, you would repeat the first colour twice and the second twice too.

Parameters

• ax (axes) – axes to plot on.

• data (dict or list) – (list of sets of) Phono3py data including:

• temperature (float, optional) –

  temperature in K (finds nearest). Default: 300.

  mode_kappa: array-like

  frequency and q-point decomposed lattice thermal conductivity.

  frequencyarray-like

  frequencies.

  temperaturearray-like

  temperature.

• direction (str or list, optional) – (list of) direction(s) from anisotropic data, accepts x-z/ a-c or average/ avg. Default: average.

• label (str, optional) – (list of) legend label(s). Defaults to $mathregular{kappa_l}$ if there is only one line plotted, or direction if there are more.

• main (bool, optional) – set ticks, labels, limits. Default: True.

• invert (bool, optional) – plot frequency on y axis. Default: False.

• scale (bool, optional) – if main, scale to percent, else scale to axis limits. Default: True.

• colour (str or list, optional) – (list of) hex or named line colour(s). Default: default colour cycle.

• fill (bool, optional) – fill below lines. Default: False.

• fillcolour (int or str or list, optional) – if a float from 0-1 and colour in #RRGGBB format, sets fill colour opacity. Otherwise treats it as a colour. Default: 0.2.

• line (bool, optional) – plot lines. Default: True.

• linestyle (str or list, optional) – (list of) linestyle(s). Default: “-“.

• marker (str or list, optional) – (list of) markers. Default: None.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.fill_between if filled or matplotlib.pyplot.plot otherwise. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Default:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.frequency.add_density(ax, data, quantity, xquantity='frequency', temperature=300, direction='avg', main=True, invert=False, colour='Blues', verbose=False, **kwargs)

Adds a density plot of quantities against frequency.

Has an option to change the x-quantity.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – data including frequency and quantity.

• quantity (str) – y-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength.

• xquantity (str, optional) – x-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength. Default: frequency.

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

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

• main (bool, optional) – set ticks, labels, limits. Default: True.

• invert (bool, optional) – invert x- and y-axes. Default: False.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or highlight colour or highlight, min, max colours in that order, or dictionary with cmid and cmin and/or cmax keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: Blues.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.scatter. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  s: 1 rasterized: True

Returns

adds plot directly to ax.

Return type

None

tp.plot.frequency.add_dos(ax, data, sigma=None, projected=True, total=False, totallabel='Total', main=True, invert=False, scale=False, colour='tab10', totalcolour=None, fill=True, fillalpha=0.2, line=True, linestyle='-', marker=None, **kwargs)

Adds a phonon density of states (DoS) to a set of axes.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – DoS data.

• sigma (float) – Gaussian broadening. 0.2 is a good place to start. Does not know if you’ve already broadened it. Default: None.

• projected (bool, optional) – plot atom-projected DoS. Default: True.

• total (bool, optional) – plot total DoS. Default: False

• totallabel (str, optional) – label for the total line. Other labels are taken directly from the input dictionary. Default: Total.

• main (bool, optional) – set ticks, labels, limits. Default: True.

• invert (bool, optional) – plot frequency on y axis. Default: False.

• scale (bool, optional) – if main, scale to percent. If not main, scale to axis limits. Default: False.

• colour (dict or list or str or colourmap, optional) – RGB colours per atom as a dictionary or a list in POSCAR order, with total as the last colour. Can instead provide a colourmap or colourmap name, which don’t include a total colour. If not projected, can specify a single total colour. Total colour is overridden by totalcolour. Default: tab10.

• totalcolour (str, optional) – colour for the total line. Overrides specifying as part of colour. Default: black.

• fill (bool, optional) – fill below lines. Default: True.

• fillalpha (float, optional) – fill alpha scaled to 0-1. Default: 0.2.

• line (bool, optional) – plot lines. Default: True.

• linestyle (dict or list or str, optional) – linestyle or dictionary of linestyles per atom and total, or list in POSCAR order, with total as the last linestyle. Default: -.

• marker (dict or list or str or tuple, optional) – marker or dictionary of markers per atom and total, or list in POSCAR order, with total as the last marker. Default: None.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.plot, unless line=False, in which case they are passed to fill_between instead. rasterized is always passed to both. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.frequency.add_projected_waterfall(ax, data, quantity, projected, xquantity='frequency', temperature=300, direction='avg', main=True, invert=False, colour='viridis', cmin=None, cmax=None, cscale=None, unoccupied='grey', verbose=False, **kwargs)

Adds a waterfall plot against frequency with a colour axis.

Has an option to change the x-quantity.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – data including frequency and quantity.

• quantity (str) – y-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength.

• projected (str) – colour-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength.

• xquantity (str, optional) – x-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength. Default: frequency.

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

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

• main (bool, optional) – set ticks, labels, limits. Default: True.

• invert (bool, optional) – invert x- and y-axes. Default: False.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or highlight colour or highlight, min, max colours in that order, or dictionary with cmid and cmin and/or cmax keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis.

• cmin (float, optional) – colour scale minimum. Default: display 99 % data.

• cmax (float, optional) – colour scale maximum. Default: display 99.9 % data.

• cscale (str optional) – override colour scale (linear/ log). Default: None.

• unoccupied (str or array-like, optional) – if the colour variable is occupation, values below 1 are coloured in this colour. If set to None, or cmin is set, this feature is turned off. Default: grey.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.scatter. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  alpha: 0.3 s: 2 edgecolors: black linewidth: 0 marker: . rasterized: True

Returns

colourbar for projected data.

Return type

colorbar

tp.plot.frequency.add_waterfall(ax, data, quantity, xquantity='frequency', temperature=300, direction='avg', main=True, invert=False, colour='viridis', verbose=False, **kwargs)

Adds a waterfall plot of quantities against frequency.

Has an option to change the x-quantity.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – data including frequency and quantity.

• quantity (str) – y-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength.

• xquantity (str, optional) – x-axis quantity. Accepts frequency, gamma, group_velocity, gv_by_gv, heat_capacity, lifetime, mean_free_path, mode_kappa, occupation or ph_ph_strength. Default: frequency.

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

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

• main (bool, optional) – set ticks, labels, limits. Default: True.

• invert (bool, optional) – invert x- and y-axes. Default: False.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or list of colours (one for each band or one for each point) or two colours for a linear colourmap (required hex or rgb or named colours) or a dictionary with cmin and cmax keys or a single colour. Default: viridis.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.scatter. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  alpha: 0.3 s: 2 edgecolors: black linewidth: 0 marker: ‘.’ rasterized: True

Returns

adds plot directly to ax.

Return type

None

tp.plot.frequency.format_waterfall(ax, data, yquantity, xquantity='frequency', temperature=300, direction='avg', invert=False)

Formats axes for waterfall plots.

Parameters

• ax (axes) – axes to format.

• data (dict) – data.

• yquantity (str) – y quantity name.

• xquantity (str, optional) – x quantity name. Default: frequency.

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

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

• invert (bool, optional) – invert x- and y-axes. Default: False.

Returns

formats ax directly.

Return type

None

tp.plot.heatmap module

Heatmap plotters.

add_heatmap is a base function, which handles axes limits, colourbar formatting and extra colourmap options compared to matplotlib.pyplot.pcolormesh. The other functions plot specific quantites using this function.

tp.plot.heatmap.add_heatmap(ax, x, y, c, xinterp=None, yinterp=None, kind='linear', xscale='linear', yscale='linear', cscale='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=None, cmax=None, colour='viridis', undercolour=None, overcolour=None, discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Adds a heatmap to a set of axes.

Formats limits, parses extra colourmap options, makes sure data isn’t obscured.

Parameters

• ax (axes) – axes to plot on.

• x (array-like) – x data.

• y (array-like) – y data.

• c (array-like (shape: x, y)) – colour data.

• xinterp (int, optional) – density of interpolation. None turns it off. Default: None.

• yinterp (int, optional) – density of interpolation. None turns it off. Default: None.

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

• xscale (str, optional) – x scale (linear or log). Default: linear.

• yscale (str, optional) – y scale (linear or log). Default: linear

• cscale (str, optional) – colour scale (linear or log). Default: linear.

• xmin (float, optional) – override x minimum. Default: None.

• xmax (float, optional) – override x maximum. Default: None.

• ymin (float, optional) – override y minimum. Default: None.

• ymax (float, optional) – override y maximum. Default: None.

• cmin (float, optional) – override colour scale minimum. Default: None.

• cmax (float, optional) – override colour scale maximum. Default: None.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or highlight colour or highlight, min, max colours in that order, or dictionary with mid and min and/or max keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: Blues.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• undercolour (str or array-like, optional) – colour for values under cmin. Default: None.

• overcolour (str or array-like, optional) – colour for values over cmax. Default: None.

• contours (int or float or array-like, optional) – contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

colourbar.

Return type

colourbar

tp.plot.heatmap.add_kappa_target(ax, data, zt=2, direction='avg', xinterp=200, yinterp=200, kind='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=0, cmax=None, colour='viridis', negativecolour='grey', discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Plots a heatmap of k_latt required for a target ZT

Calculates lattice thermal conductivity, plots and formats labels etc. May be useful to screen materials to calculate kappa_l for.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – dictionary containing temperature and doping, and either zt or conductivity, seebeck and electronic_thermal_conductivity.

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

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

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

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

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

• xmin (float, optional) – override temperature minimum. Default: None.

• xmax (float, optional) – override temperature maximum. Default: None.

• ymin (float, optional) – override doping minimum. Default: None.

• ymax (float, optional) – override doping maximum. Default: None.

• cmin (float, optional) – override kappa minimum. Default: 0.

• cmax (float, optional) – override kappa maximum. Default: None.

• colour (colourmap or str or array-like, optional) – colourmap or colourmap name; or key colour or min and max RGB colours to generate a colour map. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis.

• negativecolour (str or array-like, optional) – colour for values under cmin. Default: grey.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• contours (int or float or array-like, optional) – kappa contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the kappa contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

colourbar.

Return type

colourbar

tp.plot.heatmap.add_pfdiff(ax, data1, data2, direction='avg', xinterp=200, yinterp=200, kind='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=None, cmax=None, colour1='#800080', colour2='#FF8000', midcolour='#FFFFFF', label1=None, label2=None, discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Plots a difference of two power factors heatmap.

Calculates power factor, plots and formats labels etc.

Parameters

• ax (axes) – axes to plot on.

• data(1,2) (dict) – dictionaries containing temperature and doping, and either power_factor or conductivity and seebeck. The result is data1 - data2.

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

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

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

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

• xmin (float, optional) – override temperature minimum. Default: None.

• xmax (float, optional) – override temperature maximum. Default: None.

• ymin (float, optional) – override doping minimum. Default: None.

• ymax (float, optional) – override doping maximum. Default: None.

• cmin (float, optional) – override ZT minimum. Default: None.

• cmax (float, optional) – override ZT maximum. Default: None.

• colour(1,2) (str, optional) – colours for data(1,2). Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Deault: #800080, #FF8000.

• midcolour (str, optional) – colour at 0 difference. Default: #FFFFFF.

• label(1,2) (str, optional) – labels for data(1,2) to go in a legend. Default: None.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• contours (int or float or array-like, optional) – PF contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the PF contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

• colourbar – colourbar.

• list – legend handles.

• list – legend labels.

tp.plot.heatmap.add_pfmap(ax, data, direction='avg', xinterp=200, yinterp=200, kind='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=None, cmax=None, colour='viridis', discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Convenience wrapper for plotting power factor heatmaps.

Calculates power factor, plots and formats labels etc.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – dictionary containing temperature and doping, and either power_factor or conductivity and seebeck.

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

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

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

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

• xmin (float, optional) – override temperature minimum. Default: None.

• xmax (float, optional) – override temperature maximum. Default: None.

• ymin (float, optional) – override doping minimum. Default: None.

• ymax (float, optional) – override doping maximum. Default: None.

• cmin (float, optional) – override ZT minimum. Default: None.

• cmax (float, optional) – override ZT maximum. Default: None.

• colour (colourmap or str or array-like, optional) – colourmap or colourmap name; or key colour or min and max RGB colours to generate a colour map. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• contours (int or float or array-like, optional) – PF contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the PF contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

colourbar.

Return type

colourbar

tp.plot.heatmap.add_ztdiff(ax, data1, data2, kdata1=1.0, kdata2=1.0, direction='avg', xinterp=200, yinterp=200, kind='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=None, cmax=None, colour1='#800080', colour2='#FF8000', midcolour='#FFFFFF', label1=None, label2=None, discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Plots a difference of two ZTs heatmap.

Calculates ZT, plots and formats labels etc.

Parameters

• ax (axes) – axes to plot on.

• data(1,2) (dict) – dictionaries containing temperature and doping, and either zt or conductivity, seebeck and electronic_thermal_conductivity. The result is data1 - data2.

• kdata(1,2) (dict or int or float, optional) – dictionaries containing lattice_thermal_conductivity and temperature. Ignored if zt in data. Can specify constant values instead. Default: 1.

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

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

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

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

• xmin (float, optional) – override temperature minimum. Default: None.

• xmax (float, optional) – override temperature maximum. Default: None.

• ymin (float, optional) – override doping minimum. Default: None.

• ymax (float, optional) – override doping maximum. Default: None.

• cmin (float, optional) – override ZT minimum. Default: None.

• cmax (float, optional) – override ZT maximum. Default: None.

• colour(1,2) (str, optional) – colours for data(1,2). Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: #800080, #FF8000.

• midcolour (str, optional) – colour at 0 difference. Default: #FFFFFF.

• label(1,2) (str, optional) – labels for data(1,2) to go in a legend. Default: None.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• contours (int or float or array-like, optional) – ZT contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the ZT contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

• colourbar – colourbar.

• list – legend handles.

• list – legend labels.

tp.plot.heatmap.add_ztmap(ax, data, kdata=1.0, direction='avg', xinterp=200, yinterp=200, kind='linear', xmin=None, xmax=None, ymin=None, ymax=None, cmin=None, cmax=None, colour='viridis', discrete=False, levels=None, contours=None, contourcolours='black', contourkwargs=None, **kwargs)

Convenience wrapper for plotting ZT heatmaps.

Calculates ZT, plots and formats labels etc.

Parameters

• ax (axes) – axes to plot on.

• data (dict) – dictionary containing temperature and doping, and either zt or conductivity, seebeck and electronic_thermal_conductivity.

• kdata (dict or int or float, optional) – dictionary containing lattice_thermal_conductivity and temperature. Ignored if zt in data. Can specify a constant value instead. Default: 1.

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

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

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

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

• xmin (float, optional) – override temperature minimum. Default: None.

• xmax (float, optional) – override temperature maximum. Default: None.

• ymin (float, optional) – override doping minimum. Default: None.

• ymax (float, optional) – override doping maximum. Default: None.

• cmin (float, optional) – override ZT minimum. Default: None.

• cmax (float, optional) – override ZT maximum. Default: None.

• colour (colourmap or str or array-like, optional) – colourmap or colourmap name; or key colour or min and max colours to generate a colour map. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis.

• discrete (bool, optional) – use colour bands rather than a continuously shifting colour sequence. Default: False.

• levels (int or array-like, optional) – sets levels for discrete plots. Lists directly specify the contour levels while integers specify the maximum-1 number of “nice” levels to plot. Default: None.

• contours (int or float or array-like, optional) – ZT contours to plot. Default: None.

• contourcolours (string or array-like, optional) – colours of the ZT contours. If fewer are supplied, they repeat. Default: black.

• contourkwargs (dict, optional) – keyword arguments passed to matplotlib.pyplot.contour. Default: None

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh or matplotlib.pyplot.contourf. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True

Returns

colourbar.

Return type

colourbar

tp.plot.mfp module

Function for plotting mean free path on the x-axis.

tp.plot.mfp.add_cum_kappa(ax, data, kmin=1, temperature=300, direction='avg', label=None, xmarkers=None, ymarkers=None, add_xticks=False, add_yticks=False, main=True, scale=False, colour=None, fill=False, fillcolour=0.2, line=True, linestyle='-', marker=None, markerkwargs={}, verbose=False, **kwargs)

Cumulates and plots kappa against mean free path.

Can plot data from multiple data dictionaries and directions. Colour, linestyle etc. are looped, so if you have two datasets and two directions, but only specify two colours, the first will apply to the first direction in both datasets, whereas if you want one for the first dataset and one for the second, you would repeat the first colour twice and the second twice too.

Parameters

• ax (axes) – axes to plot on.

• data (dict) –

  (list of sets of) Phono3py data including:

  mode_kappa: array-like

  frequency and q-point decomposed lattice thermal conductivity.

  mean_free_patharray-like

  mean free paths.

  temperaturearray-like

  temperature.

• kmin (float or int, optional) – minimum kappa to plot in percent. Default: 1.

• temperature (float, optional) – temperature in K (finds nearest). Default: 300.

• direction (str, optional) – (list of) direction(s) from anisotropic data, accepts x-z/ a-c or average/ avg. Default: average.

• label (str, optional) – (list of) legend label(s). Defaults to $mathregular{kappa_l}$ if there is only one line plotted, or direction if there are more.

• xmarkers (array-like, optional) – mark kappa at certain mean free paths.

• ymarkers (array-like, optional) – mark mean free path at certain kappas.

• add_xticks (bool, optional) – add x_ticks for each marker. Doesn’t work on log axes. Default: False.

• add_yticks (bool, optional) – add y_ticks for each marker. Doesn’t work on log axes. Default: False.

• main (bool, optional) – set ticks, labels, limits. Default: True.

• scale (bool, optional) – if main, scale to percent. If not main, scale to axis limits. Default: False.

• colour (str or list, optional) – (list of) RGB line colour(s). Default: default colour cycle.

• fill (bool, optional) – fill below lines. Default: False.

• fillcolour (int or str or list, optional) – if a float from 0-1 and colour in #RRGGBB format, sets fill colour opacity. Otherwise treats it as a colour. Default: 0.2.

• line (bool, optional) – plot lines. Default: True.

• linestyle (str or list, optional) – (list of) linestyle(s). Default: “-“.

• marker (str or list, optional) – (list of) markers. Default: None.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• markerkwargs (dict, optional) –

  keyword arguments for the markers, passed to matplotlib.pyplot.plot. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.fill_between if filled or matplotlib.pyplot.plot otherwise. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Default:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.mfp.add_markers(ax, x, y, xmarkers=None, ymarkers=None, **kwargs)

Adds marker lines linking a linear plot to the axes.

Parameters

• ax (axes) – axes to plot on.

• x (array-like) – x data.

• y (array-like) – y data.

• xmarkers (array-like, int or float, optional) – where on the x axis to mark.

• ymarkers (array-like, int or float, optional) – where on the y axis to mark.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.plot. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axes line width rasterized: False

Returns

• list – added x locations.

• list – added y locations.

tp.plot.phonons module

Tools for dealing with phonon dispersions.

Contains the traditional phonon dispersion plotter, as well as various ways of projecting other quantitites onto a high-symmetry path.

tp.plot.phonons.add_alt_dispersion(ax, data, pdata, quantity, bandmin=None, bandmax=None, temperature=300, direction='avg', label=['Longitudinal', 'Transverse$_1$', 'Transverse$_2$', 'Optic'], poscar='POSCAR', scatter=False, main=True, log=False, interpolate=10000, smoothing=5, colour=['#44ffff', '#ff8044', '#ff4444', '#00000010'], linestyle='-', marker=None, workers=8, xmarkkwargs={}, verbose=False, **kwargs)

Plots a phono3py quantity on a high-symmetry path.

Labels, colours and linestyles can be given one for the whole dispersion, or one for each band, with the last entry filling all remaining bands. Requires a POSCAR.

Parameters

• ax (axes) – axes to plot on.

• data (dict) –

  Phono3py-like data containing:

  qpointarray-like

  q-point locations.

  (quantity)array-like

  plotted quantity.

  temperaturearray-like, optional

  temperature, if necessary for quantity.

• pdata (dict) –

  phonon dispersion data containing:

  q-pointarray-like

  qpoint locations.

  xarray-like

  high-symmetry path.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• quantity (str) – quantity to plot.

• bandmin (int, optional) – Zero-indexed minimum band index to plot. Default: 0.

• bandmax (int, optional) – Zero-indexed maximum band index to plot. Default: max index.

• temperature (float, optional) – approximate temperature in K (finds closest). Default: 300.

• direction (str, optional) – direction from anisotropic data, accepts x-z/ a-c, average/ avg or normal/ norm. Default: average.

• label (array-like, optional) – labels per line. A single dataset could have a single label, or the default labels the lines by type. You’ll want to change this if a minimum band index is set. Default: [‘Longitudinal’, ‘Transverse$_1$’, ‘Transverse$_2$’, ‘Optic’].

• scatter (bool, optional) – plot scatter rather than line graph. Default: False.

• poscar (str, optional) – VASP POSCAR filepath. Default: POSCAR.

• main (bool, optional) – set axis ticks, label, limits. Default: True.

• log (bool, optional) – log the y scale. Default: False.

• interpolate (int, optional) – number of points per line. Default: 10,000.

• smoothing (int, optional) – every n points to sample. Default: 5.

• colour (str or array-like, optional) – line colour(s). Note if retrieved from a colourmap or in [r,g,b] notation, the colour should be enclosed in [], e.g. colour = plt.get_cmap(‘winter_r’)(linspace(0, 1, len(files))) tp.plot.phonons.add_dispersion(…, colour=[colour[0]], …) Default: [‘#44ffff’, ‘#ff8044’, ‘#ff4444’, ‘#00000010’].

• linestyle (str or array-like, optional) – linestyle(s) (‘-‘, ‘–’, ‘.-‘, ‘:’). Default: solid.

• marker (str or array-like, optional) – marker(s). Default: None.

• workers (int, optional) – number of workers for paralellised section. Default: 8.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.plot. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.phonons.add_alt_projected_dispersion(ax, data, pdata, quantity, projected, bandmin=None, bandmax=None, temperature=300, direction='avg', poscar='POSCAR', main=True, log=False, interpolate=10000, smoothing=10, colour='viridis_r', cmin=None, cmax=None, cscale=None, unoccupied='grey', workers=8, xmarkkwargs={}, verbose=False, **kwargs)

Plots a phono3py quantity on a high-symmetry path and projection.

Just because you can, doesn’t mean you should. A maxim I may fail to live up to, so I leave it to you, dear reader, to decide for yourself. Requires a POSCAR.

Parameters

• ax (axes) – axes to plot on.

• data (dict) –

  Phono3py-like data containing:

  qpointarray-like

  q-point locations.

  (quantities)array-like

  plotted and projected quantities.

  temperaturearray-like, optional

  temperature, if necessary for quantities.

• pdata (dict) –

  phonon dispersion data containing:

  q-pointarray-like

  qpoint locations.

  xarray-like

  high-symmetry path.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• quantity (str) – quantity to plot.

• projected (str) – quantity to project.

• bandmin (int, optional) – Zero-indexed minimum band index to plot. Default: 0.

• bandmax (int, optional) – Zero-indexed maximum band index to plot. Default: max index.

• temperature (float, optional) – approximate temperature in K (finds closest). Default: 300.

• direction (str, optional) – direction from anisotropic data, accepts x-z/ a-c, average/ avg or normal/ norm. Default: average.

• poscar (str, optional) – VASP POSCAR filepath. Default: POSCAR.

• main (bool, optional) – set axis ticks, label, limits. Default: True.

• log (bool, optional) – log the y scale. Default: False.

• interpolate (int, optional) – number of points per line. Default: 10,000.

• smoothing (int, optional) – every n points to sample. Default: 10.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or highlight colour or highlight, min, max colours in that order, or dictionary with cmid and cmin and/or cmax keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis_r.

• cmin (float, optional) – colour scale minimum. Default: display 99 % data.

• cmax (float, optional) – colour scale maximum. Default: display 99.9 % data.

• cscale (str, optional) – override colour scale (linear/ log). Default: None.

• unoccupied (str, optional) – if the colour variable is occuption, values below 1 are coloured in this colour. Id set to None, or cmin is set, this feature is turned off. Default: grey.

• workers (int, optional) – number of workers for paralellised section. Default: 8.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.scatter. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  marker: . rasterized: True

Returns

colour bar for projected data.

Return type

colorbar

tp.plot.phonons.add_dispersion(ax, data, sdata=None, bandmin=None, bandmax=None, main=True, label=None, colour='#800080', linestyle='solid', marker=None, xmarkkwargs={}, **kwargs)

Adds a phonon band structure to a set of axes.

Labels, colours and linestyles can be given one for the whole dispersion, or one for each band, with the last entry filling all remaining bands.

Parameters

• ax (axes) – axes to plot on.

• data (dict) –

  dispersion data containing:

  xarray-like

  high-symmetry path.

  frequencyarray-like

  phonon frequencies.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• sdata (dict, optional) – dispersion data to scale to, same format as data. Default: None.

• bandmin (int, optional) – zero-indexed minimum band index to plot. Default: None.

• bandmax (int, optional) – zero-indexed maximum band index to plot. Default: None.

• main (bool, optional) – set axis ticks, labels, limits. Default: True.

• label (str, optional) – legend label(s). Default: None

• colour (str or array-like, optional) – line colour(s). Note if retrieved from a colourmap or in [r,g,b] notation, the colour should be enclosed in [], e.g. colour = plt.get_cmap(‘winter_r’)(linspace(0, 1, len(files))) tp.plot.phonons.add_dispersion(…, colour=[colour[0]], …) Default: #800080.

• linestyle (str or array-like, optional) – linestyle(s) (‘-‘, ‘–’, ‘.-‘, ‘:’). Default: solid.

• marker (str or array-like, optional) – marker(s). Default: None.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.plot. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.phonons.add_multi(ax, data, bandmin=None, bandmax=None, main=True, label=None, colour='winter_r', linestyle='solid', marker=None, xmarkkwargs={}, **kwargs)

Adds multiple phonon band structures to a set of axes.

Scales the x-scales to match.

Parameters

• ax (axes) – axes to plot on.

• data (array-like) –

  dictionaries of dispersion data containing:

  xarray-like

  high-symmetry path.

  frequencyarray-like

  phonon frequencies.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• bandmin (int, optional) – Zero-indexed minimum band index to plot. Default: 0.

• bandmax (int, optional) – Zero-indexed maximum band index to plot. Default: max index.

• main (bool, optional) – set axis ticks, labels, limits. Default: True.

• label (array-like, optional) – legend labels. Default: None

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or list of colours, one for each dispersion or a min and max colour to generate a linear colourmap between or a dictionary with cmin and cmax keys. Note [r,g,b] format colours should be enclosed in an additional [], i.e. [[[r,g,b]],…]. Default: winter_r.

• linestyle (str or array-like, optional) – linestyle(s) (‘-‘, ‘–’, ‘.-‘, ‘:’). Default: solid.

• marker (str or array-like, optional) – marker(s). Default: None.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.plot. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: False

Returns

adds plot directly to ax.

Return type

None

tp.plot.phonons.add_projected_dispersion(ax, data, pdata, quantity, bandmin=None, bandmax=None, temperature=300, direction='avg', poscar='POSCAR', main=True, interpolate=500, colour='viridis_r', cmin=None, cmax=None, cscale=None, unoccupied='grey', workers=8, xmarkkwargs={}, verbose=False, **kwargs)

Plots a phonon dispersion with projected colour.

Plots a phonon dispersion, and projects a quantity onto the colour axis. Requires a POSCAR.

Parameters

• ax (axes) – axes to plot on.

• data (dict) –

  Phono3py-like data containing:

  qpointarray-like

  q-point locations.

  (quantity)array-like

  projected quantity.

  temperaturearray-like, optional

  temperature, if necessary for quantity.

• pdata (dict) –

  phonon dispersion data containing:

  q-pointarray-like

  qpoint locations.

  xarray-like

  high-symmetry path.

  frequencyarray-like

  phonon frequencies.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• quantity (str) – quantity to project.

• bandmin (int, optional) – Zero-indexed minimum band index to plot. Default: 0.

• bandmax (int, optional) – Zero-indexed maximum band index to plot. Default: max index.

• temperature (float, optional) – approximate temperature in K (finds closest). Default: 300.

• direction (str, optional) – direction from anisotropic data, accepts x-z/ a-c, average/ avg or normal/ norm. Default: average.

• poscar (str, optional) – VASP POSCAR filepath. Default: POSCAR.

• main (bool, optional) – set axis ticks, label, limits. Default: True.

• interpolate (int, optional) – number of points per path (e.g. gamma -> X) per line. Default: 500.

• colour (colourmap or str or array-like or dict, optional) – colourmap or colourmap name or highlight colour or highlight, min, max colours in that order, or dictionary with cmid and cmin and/or cmax keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis_r.

• cmin (float, optional) – colour scale minimum. Default: display 99 % data.

• cmax (float, optional) – colour scale maximum. Default: display 99.9 % data.

• cscale (str, optional) – override colour scale (linear/ log). Default: None.

• unoccupied (str or array-like, optional) – if the colour variable is occuption, values below 1 are coloured in this colour. If set to None, or cmin is set, this feature is turned off. Default: grey.

• workers (int, optional) – number of workers for paralellised section. Default: 8.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Default

  color: black linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.scatter. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  marker: . rasterized: True

Returns

colour bar for projected data.

Return type

colorbar

tp.plot.phonons.add_wideband(ax, kdata, pdata, temperature=300, poscar='POSCAR', main=True, smoothing=5, colour='viridis', workers=8, xmarkkwargs={}, verbose=False, **kwargs)

Plots a phonon dispersion with broadened bands.

Requires a POSCAR.

Parameters

• ax (axes) – axes to plot on.

• kdata (dict) –

  Phono3py-like data containing:

  qpointarray-like

  q-point locations.

  gammaarray-like

  imaginary component of the self-energy.

  temperaturearray-like

  temperature.

• pdata (dict) –

  phonon dispersion data containing:

  q-pointarray-like

  qpoint locations.

  xarray-like

  high-symmetry path.

  frequencyarray-like

  phonon frequencies.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• temperature (float, optional) – approximate temperature in K (finds closest). Default: 300.

• poscar (str, optional) – VASP POSCAR filepath. Default: POSCAR.

• main (bool, optional) – set axis ticks, label, limits. Default: True.

• smoothing (int, optional) – every n points to sample. Default: 5.

• colour (colormap or str or list, optional) – colourmap or colourmap name or max colour (fades to white) or min and max colours or dictionary with cmin and cmax keys. Colour format must be hex or rgb (array) or a named colour recognised by matplotlib. Default: viridis.

• workers (int, optional) – number of workers for paralellised section. Default: 8.

• verbose (bool, optional) – Write actual temperature used if applicable. Default: False.

• xmarkkwargs (dict, optional) –

  keyword arguments for x markers passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: None linewidth: axis line width rasterized: False

• kwargs –

  keyword arguments passed to matplotlib.pyplot.pcolormesh. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  rasterized: True shading: auto

Returns

adds plot directly to ax.

Return type

None

tp.plot.phonons.formatting(ax, data, yquantity='frequency', log=False, **kwargs)

Formats the axes of phonon plots.

Parameters

• ax (axes) – axes to format.

• pdata (dict) –

  phonon dispersion data containing:

  xarray-like

  high-symmetry path.

  tick_positionarray-like

  x-tick positions.

  tick_labelarray-like

  x-tick labels.

• yquantity (str, optional) – y variable. Default: frequency.

• log (bool, optional) – log the y scale. Default: False.

• kwargs –

  keyword arguments passed to matplotlib.pyplot.axvline. Set color to None to turn off. Defaults are defined below, which are overridden by those in ~/.config/tprc.yaml, both of which are overridden by arguments passed to this function. Defaults:

  color: black linewidth: axis line width rasterized: False

Returns

formats ax directly.

Return type

None

tp.plot.phonons.get_equivalent_qpoint(qk, symops, qp, tol=0.01)

Finds the closest phono3py qpoint to a phonopy qpoint.

Parameters

• qk (array-like) – all qpoints from the phono3py kappa file.

• symmops – symmetry operations (e.g. from Pymatgen)

• qp (array-like) – single qpoint from the phonon dispersion.

• tol (float, optional) – tolerance. Default: 1e-2.

Returns

nearest qpoint index.

Return type

int

tp.plot.phonons.tile_properties(properties, bandmin, bandmax)

Tiles properties for dispersion and alt_dispersion

Allows for different colour formats and fills out arrays with the last element or selects a subset.

Parameters

• property (array-like or str) – array or string to tile.

• bandmin (int) – minimum band.

• bandmax (int) – maximum band.

Returns

array.

Return type

tiled

tp.plot.utilities module

Utilities to aid the plotting scripts.

tp.plot.utilities.colour_scale(c, name, cmap, cmin=None, cmax=None, cscale=None, unoccupied='grey')

Formats the colour scale for phono3py quantities.

Attempts to set the limits to maximise visibility of the most important data and determines if the colourbar should be extended.

Parameters

• c (array-like) – colour data.

• name (str) – name of colour variable.

• cmap (colormap) – colourmap.

• cmin (float, optional) – colour scale minimum. Default: display 99 % data.

• cmax (float, optional) – colour scale maximum. Default: display 99.9 % data.

• cscale (str, optional) – override colour scale (linear/ log). Default: None.

• unoccupied (str, optional) – if the colour variable is occupation, values below 1 are coloured in this colour. If set to None, or cmin is set, this feature is turned off. Default: grey.

Returns

• cnorm – colour normalisation object.

• extend – which direction to extend the colourbar in.

tp.plot.utilities.parse_colours(colour)

Parses a range of inputs into a colourmap

colourcolourmap or str or array-like or dict

colourmap or colourmap name or #rrggbb highlight colour or highlight, min, max colours in that order, or dictionary with cmid and cmin and/or cmax keys.

Returns

colourmap

Return type

colourmap

tp.plot.utilities.scale_to_axis(ax, data, exclude=[], scale=None, axis='y')

Scale data to fit an axis.

Assumes data is linear, but still works for linear and log axes.

Parameters

• ax (axes) – axes to fit to.

• data (array-like or dict) – data to scale.

• exclude (array-like, optional) – keys to exclude from scaling. Default: none.

• scale (array-like, optional) – force scaling limits to [min, max]. Default: axis limits.

• axis (bool, optional) – axis to scale to. Default: y.

Returns

scaled data.

Return type

data

tp.plot.utilities.set_locators(ax, x=None, y=None, dos=False)

Set locators quickly.

If log, sets scale as well.

Parameters

• ax (axes) – axes to format

• x (str, optional) – locator on x axis. Accepts linear, log or null. Default: do nothing.

• y (str, optional) – locator on y axis. Accepts linear, log or null. Default: do nothing.

• dos (bool, optional) – removes axes ticks and ticklabels and y axis label. Runs first, so ticks can be reinstated on x, e.g. for waterfall plots using x=’log’. Default: False.

Returns

formats ax directly.

Return type

None