euphonic-powder-map

Overview

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 quartz.castep_bin --weighting coherent --energy-broadening 1.5

Note the text boxes below the intensity map, which allow the intensity limits of the plot to be adjusted without having to re-run the expensive powder calculation. To plot a DOS-weighted intensity from Phonopy force constants over a specified q range with denser sampling, in THz and with the intensity widget disabled:

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

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. For information on advanced plot styling, see Customising plots.

Progress bars

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

Kinematic constraints

Inelastic neutron-scattering measurements have an accessible \((\mathbf{q}, \omega)\) range depending on the instrument geometry: either the incident energy is fixed (direct geometry) or the final energy is fixed (indirect geometry), and the scattering angles are determined by reflector/analyzer/detector positions. The remaining degrees of freedom (e.g. time-of-flight) are used to determine the \((\mathbf{q}, \omega)\) transfer. To simulate these constraints, the parameter --e-incident or --e-final can be used to set the constrained energy, and --angle-range can be used to fix the detector range. So, for example, to simulate the MARI instrument at ISIS with a 60 meV incident energy:

euphonic-powder-map quartz.castep_bin --angle-range 3 135 --e-incident 60 --q-max 11 --energy-unit meV --weights coherent

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.

Output to file

The --save-json option can be used to output the produced Spectrum2D object as a Euphonic .json file with a specified name for further use in Euphonic or other programs.

Faster Interpolation with Brille

The Brille library allows linear interpolation of phonon frequencies and eigenvectors, as opposed to the Fourier interpolation used by Euphonic. Linear interpolation should be faster, but less accurate, than Fourier interpolation, so can provide a performance improvement of the euphonic-powder-map script. To use Brille with this script use the --use-brille argument, which by default will create a Brille trellis grid with approximately 5000 points from which to perform linear interpolation. The grid type and number or number density of points on the grid can be changed using the --brille-grid-type and --brille-npts or --brille-npts-density arguments. For more information on how Brille works with Euphonic and help choosing the number of grid points, see Brille Interpolator and euphonic-brille-convergence.

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]
                           [--weighting {dos,coherent-dos,incoherent-dos,coherent-plus-incoherent-dos,coherent}]
                           [--temperature TEMPERATURE]
                           [--grid GRID GRID GRID | --grid-spacing GRID_SPACING]
                           [--scale SCALE]
                           [--npts NPTS | --npts-density NPTS_DENSITY]
                           [--npts-min NPTS_MIN] [--npts-max NPTS_MAX]
                           [--sampling {spherical-polar-grid,random-sphere,golden,sphere-projected-grid,spherical-polar-improved}]
                           [--jitter] [--save-json SAVE_JSON] [-s SAVE_TO]
                           [--title TITLE] [--x-label XLABEL]
                           [--y-label YLABEL] [--style STYLE [STYLE ...]]
                           [--no-base-style] [--font FONT]
                           [--font-size FONTSIZE] [--fig-size FIGSIZE FIGSIZE]
                           [--fig-size-unit FIGSIZE_UNIT] [--e-min E_MIN]
                           [--e-max E_MAX] [--energy-unit ENERGY_UNIT]
                           [--ebins EBINS]
                           [--energy-broadening ENERGY_BROADENING [ENERGY_BROADENING ...]]
                           [--shape [{gauss,lorentz}]]
                           [--length-unit LENGTH_UNIT] [--q-spacing Q_SPACING]
                           [--q-broadening Q_BROADENING [Q_BROADENING ...]]
                           [--v-min VMIN] [--v-max VMAX] [--c-map CMAP]
                           [--use-brille]
                           [--brille-grid-type {trellis,mesh,nest}]
                           [--brille-npts BRILLE_NPTS]
                           [--brille-npts-density BRILLE_NPTS_DENSITY]
                           [--q-min Q_MIN] [--q-max Q_MAX] [--no-widgets]
                           [--e-incident E_I | --e-final E_F]
                           [--angle-range ANGLE_RANGE ANGLE_RANGE]
                           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).

--save-json

Save spectrum to a .json file with this name

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, random-sphere, golden, sphere-projected-grid, spherical-polar-improved

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).If multiple values are provided, these will be interpreted as polynomial coefficients to be evaluated in 1/LENGTH_UNIT base.

--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). If multiple values are provided, these will be interpreted as polynomial coefficients to be evaluated in ENERGY_UNIT base, e.g. –energy-broadening 1. 0.01 1e-6 –energy-unit meV will apply FWHM of (1. + 0.01 (energy / meV) + 1e-6 (energy / meV)^2) meV.

--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

--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).

--scale

Intensity scale factor

Plotting arguments

-s, --save-to

Save resulting plot to a file with this name

--title

Plot title

Default: “”

--x-label, --xlabel

Plot x-axis label

--y-label, --ylabel

Plot y-axis label

--style

Matplotlib styles (name or file)

--no-base-style

Remove all default formatting before applying other style options.

Default: False

--font

Select text font. (This has to be a name known to Matplotlib. font-family will be set to sans-serif; it doesn’t matter if)the font is actually sans-serif.

--font-size, --fontsize

Set base font size in pt.

--fig-size, --figsize

Figure canvas size in FIGSIZE-UNITS

--fig-size-unit, --figsize-unit

Unit of length for –figsize

Default: “cm”

--v-min, --vmin

Minimum of data range for colormap.

--v-max, --vmax

Maximum of data range for colormap.

--c-map, --cmap

Matplotlib colormap

--no-widgets

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

Default: False

Performance-related arguments

--use-c

Force use of compiled C extension when computing phonon frequencies/eigenvectors (or raise error).

--disable-c

Do not attempt to use compiled C extension when computing phonon frequencies/eigenvectors.

--n-threads

Number of parallel processes for computing phonon modes. (Only applies when using C extension.)

Brille interpolation related arguments. Only applicable if Brille has been installed.

--use-brille

Use a BrilleInterpolator object to calculate phonon frequencies and eigenvectors instead of ForceConstants

Default: False

--brille-grid-type

Possible choices: trellis, mesh, nest

Type of Brille grid to use, passed to the “grid_type” kwarg of BrilleInterpolator.from_force_constants

Default: “trellis”

--brille-npts

Approximate number of q-points to generate on the Brille grid, is passed to the “n_grid_points” kwarg of BrilleInterpolator.from_force_constants

Default: 5000

--brille-npts-density

Approximate density of q-points to generate on the Brille grid, is passed to the “grid_density” kwarg of BrilleInterpolator.from_force_constants

Kinematic constraints

--e-incident, --e-i

Incident energy for direct-geometry constraints

--e-final, --e-f

Final energy for indirect-geometry constraints

--angle-range

Range of scattering angles (2θ) in degrees. These lower/upper bounds are used with incident/final energy to determine accessible (|q|, ω) region.

Default: [0.0, 180.0]