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.
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,spherical-polar-improved,sphere-projected-grid,golden,random-sphere}]
[--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]
[--shape [{gauss,lorentz}]]
[--length-unit LENGTH_UNIT] [--q-spacing Q_SPACING]
[--q-broadening Q_BROADENING] [--v-min VMIN]
[--v-max VMAX] [--c-map CMAP] [--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, spherical-polar-improved, sphere-projected-grid, golden, random-sphere
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, --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
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]