euphonic-powder-map¶

The euphonic-powder-map program can be used to sample spherically-averaged properties from force constants data over a range of \(|q|\). The results are plotted as a 2-dimensional map in \((|q|, \omega)\).

For example, to plot a coherent neutron-weighted powder spectrum from CASTEP force constants over a recommended \(|q|\) range, one could run:

euphonic-powder-map --weighting coherent --energy-broadening 1.5 quartz.castep_bin

Or, to plot a DOS-weighted intensity from Phonopy phonon frequencies over a specified q range with denser sampling:

euphonic-powder-map --weighting dos --energy-unit THz --energy-broadening 0.15 --q-min 0.01 --q-max 4. --q-spacing 0.1 phonopy.yaml

To see all the command line options, run:

euphonic-powder-map -h

You can also see the available command line options at the bottom of this page.

Spherical averaging options¶

Spherical averaging is performed in a series of constant-q shells. The --npts, --npts-density, --npts-min and --npts-max options control the number of samples in each shell, while the --sampling and --jitter options control the sampling scheme. The euphonic-show-sampling tool can be used to visualise different sampling schemes.

While the default scheme is recommended for all production calculations, it is generally necessary to tune the NPTS parameters. While --npts sets a constant number of samples for each shell, --npts-density sets the number of samples at a 1/LENGTH_UNIT-radius sphere, and applies quadratic scaling for other distances. This may lead to inappropriately small or large numbers of samples at low or high \(|q|\), so the range is limited by --npts-min and --npts-max. The program will print “Final npts:” with the number of samples used at the largest sampling sphere. If this is equal to --npts-max then the upper limit is in use; you may wish to experiment with reducing --npts-density or increasing --npts-max in such cases.

Progress bars¶

Sampling many q-points can be computationally expensive, so a progress bar will automatically be displayed if tqdm is installed

Command Line Options¶

usage: euphonic-powder-map [-h] [--asr [{reciprocal,realspace}]]
                           [--dipole-parameter DIPOLE_PARAMETER]
                           [--use-c | --disable-c] [--n-threads N_THREADS]
                           [--pdos PDOS]
                           [--weights {dos,coherent-dos,incoherent-dos,coherent-plus-incoherent-dos,coherent}]
                           [--weighting {dos,coherent-dos,incoherent-dos,coherent-plus-incoherent-dos,coherent}]
                           [--temperature TEMPERATURE]
                           [--grid GRID GRID GRID | --grid-spacing GRID_SPACING]
                           [--npts NPTS | --npts-density NPTS_DENSITY]
                           [--npts-min NPTS_MIN] [--npts-max NPTS_MAX]
                           [--sampling {spherical-polar-grid,sphere-projected-grid,random-sphere,spherical-polar-improved,golden}]
                           [--jitter] [-s SAVE_TO] [--title TITLE]
                           [--x-label X_LABEL] [--y-label Y_LABEL]
                           [--e-min E_MIN] [--e-max E_MAX]
                           [--energy-unit ENERGY_UNIT] [--ebins EBINS]
                           [--energy-broadening ENERGY_BROADENING]
                           [--shape [{gauss,lorentz}]]
                           [--length-unit LENGTH_UNIT] [--q-spacing Q_SPACING]
                           [--q-broadening Q_BROADENING] [--v-min V_MIN]
                           [--v-max V_MAX] [--cmap CMAP] [--q-min Q_MIN]
                           [--q-max Q_MAX] [--no-widgets]
                           filename

File I/O arguments¶

filename: Phonon data file. This should contain force constants data. Accepted formats: .yaml, force_constants.hdf5 (Phonopy); .castep_bin, .check (Castep); .json (Euphonic).

q-point sampling arguments¶

“GRID” options relate to Monkhorst-Pack sampling for the Debye-Waller factor, and only apply when –weighting=coherent and –temperature is set. “NPTS” options determine spherical groups of q-points for powder-averaging. “Q” options relate to the sphere sizes (i.e. radial distances).

--grid

Defines a Monkhorst-Pack grid.

--grid-spacing

q-point spacing of Monkhorst-Pack grid.

Default: 0.1

--npts, -n

Number of samples at each |q| sphere.

Default: 1000

--npts-density

NPTS specified as the number of points at surface of 1/LENGTH_UNIT-radius sphere; otherwise scaled to equivalent area density at sphere surface.

--npts-min

Minimum number of samples per sphere. This ensures adequate sampling at small q when using –npts-density.

Default: 100

--npts-max

Maximum number of samples per sphere. This avoids diminishing returns at large q when using –npts-density.

Default: 10000

--sampling

Possible choices: spherical-polar-grid, sphere-projected-grid, random-sphere, spherical-polar-improved, golden

Spherical sampling scheme; “golden” is generally recommended uniform quasirandom sampling.

Default: “golden”

--jitter

Apply additional jitter to sample positions in angular direction. Recommended for sampling methods other than “golden” and “random-sphere”.

Default: False

--length-unit

Length units; these will be inverted to obtain units of distance between q-points (e.g. “bohr” for bohr^-1).

Default: “angstrom”

--q-spacing

Target distance between q-point samples in 1/LENGTH_UNIT

Default: 0.025

--q-broadening, --qb

FWHM of broadening on q axis in 1/LENGTH_UNIT (no broadening if unspecified).

--q-min

Minimum |q| in 1/LENGTH_UNIT

Default: 0.0

--q-max

Maximum |q| in 1/LENGTH_UNIT

Default: 3.0

energy/frequency arguments¶

--e-min

Energy range minimum in ENERGY_UNIT

--e-max

Energy range maximum in ENERGY_UNIT

--energy-unit, -u

Energy units

Default: “meV”

--ebins

Number of energy bins

Default: 200

--energy-broadening, --eb

The FWHM of broadening on energy axis in ENERGY_UNIT (no broadening if unspecified).

--shape

Possible choices: gauss, lorentz

The broadening shape

Default: “gauss”

Force constants interpolation arguments¶

--asr

Possible choices: reciprocal, realspace

Apply an acoustic-sum-rule (ASR) correction to the data: “realspace” applies the correction to the force constant matrix in real space. “reciprocal” applies the correction to the dynamical matrix at each q-point.

--dipole-parameter

Set the cutoff in real/reciprocal space for the dipole Ewald sum; higher values use more reciprocal terms. If tuned correctly this can result in performance improvements. See euphonic-optimise-dipole-parameter program for help on choosing a good DIPOLE_PARAMETER.

Default: 1.0

Property-calculation arguments¶

--pdos

Plot PDOS for a specific species e.g. –pdos Si

--weights

Possible choices: dos, coherent-dos, incoherent-dos, coherent-plus-incoherent-dos, coherent

–weights is deprecated, please use –weighting instead

Default: “dos”

--weighting, -w

Possible choices: dos, coherent-dos, incoherent-dos, coherent-plus-incoherent-dos, coherent

Spectral weighting to plot: DOS, coherent neutron-weighted DOS, incoherent neutron-weighted DOS or total (coherent + incoherent) neutron-weighted DOS, coherent inelastic neutron scattering

Default: “dos”

--temperature

Temperature in K; enable Debye-Waller factor calculation. (Only applicable when –weighting=coherent).

Plotting arguments¶

-s, --save-to

Save resulting plot to a file with this name

--title

Plot title

Default: “”

--x-label

Plot x-axis label

--y-label

Plot y-axis label

--v-min

Minimum of data range for colormap.

--v-max

Maximum of data range for colormap.

--cmap

Matplotlib colormap

Default: “viridis”

--no-widgets

Don’t use Matplotlib widgets to enable interactive setting of colormap intensity limits