euphonic-dos

The euphonic-dos program can be used to plot density of states, partial density of states, and/or neutron-weighted density of states. It can use pre-calculated frequencies, or use force constants to generate frequencies and DOS over a Monkhorst-Pack grid. For example, to plot DOS from a Phonopy mesh.yaml file in units of THz, run:

euphonic-dos NaCl/mesh.yaml --energy-unit THz

Or, to plot coherent neutron-weighted DOS from CASTEP force constants in a .castep_bin file on a 15x15x12 grid with 1.5 meV broadening, run:

euphonic-dos quartz.castep_bin --weighting coherent-dos --grid 15 15 12 --energy-broadening 1.5

To see all the command line options, run:

euphonic-dos -h

You can also see the available command line options below. For information on advanced plot styling, see Customising plots.

Command Line Options

Plots a DOS from the file provided. If a force constants file is provided, a DOS is generated on the Monkhorst-Pack grid specified by the grid (or grid-spacing) argument.

usage: euphonic-dos [-h] [--asr [{reciprocal,realspace}]]
                    [--dipole-parameter DIPOLE_PARAMETER]
                    [--use-c | --disable-c] [--n-threads N_THREADS]
                    [--pdos [PDOS [PDOS ...]]]
                    [--weighting {dos,coherent-dos,incoherent-dos,coherent-plus-incoherent-dos}]
                    [--grid GRID GRID GRID | --grid-spacing GRID_SPACING]
                    [--scale SCALE] [--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] [--line-width LINEWIDTH]
                    [--e-min E_MIN] [--e-max E_MAX]
                    [--energy-unit ENERGY_UNIT] [--ebins EBINS] [--adaptive]
                    [--adaptive-method {reference,fast}]
                    [--adaptive-error ADAPTIVE_ERROR]
                    [--adaptive-scale ADAPTIVE_SCALE]
                    [--adaptive-fit {cubic,cheby-log}]
                    [--instrument-broadening INST_BROADENING [INST_BROADENING ...]]
                    [--energy-broadening ENERGY_BROADENING [ENERGY_BROADENING ...]]
                    [--shape [{gauss,lorentz}]] [--length-unit LENGTH_UNIT]
                    filename

File I/O arguments

filename

Phonon data file. This should contain force constants or phonon mode data. Force constants formats: .yaml, force_constants.hdf5 (Phonopy); .castep_bin , .check (Castep); .json (Euphonic). Phonon mode data formats: {band,qpoints,mesh}.{hdf5,yaml} (Phonopy); .phonon (Castep); .json (Euphonic)

--save-json

Save spectrum to a .json file with this name

q-point sampling arguments

--grid

Defines a Monkhorst-Pack grid.

--grid-spacing

q-point spacing of Monkhorst-Pack grid.

Default: 0.1

--length-unit

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

Default: “angstrom”

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

--adaptive

Use adaptive broadening on the energy axis to broaden based on phonon mode widths, rather than using fixed width broadening

Default: False

--adaptive-method

Possible choices: reference, fast

Adaptive broadening method. “Reference” is default for compatibility purposes: “Fast” method is approximate with much better performance.

Default: “reference”

--adaptive-error

Maximum absolute error for gaussian approximations when using the fast adaptive broadening method

Default: 0.01

--adaptive-scale

Scale factor applied to adaptive broadening width

--adaptive-fit

Possible choices: cubic, cheby-log

Select parametrisation for fast adaptive broadening. “cheby-log” is generally recommended, “cubic” is default retained for backward-compatibility. This only applies when adaptive broadening is used; if variable-width instrument broadening is used alone then “cheby-log” will be used.

Default: “cubic”

--instrument-broadening

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.

--energy-broadening, --eb

If using adaptive broadening and a single (i.e. scalar) value is provided, this is an alias for –adaptive-scale. Otherwise, this is an alias for –instrument-broadening.

--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. With –pdos, per-species PDOS will be plotted alongside total DOS. A subset of species can also be selected by adding more arguments e.g. –pdos Si O

--weighting, -w

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

Type of DOS to plot: DOS, coherent neutron-weighted DOS, incoherent neutron-weighted DOS or total (coherent + incoherent) neutron-weighted DOS

Default: “dos”

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

--line-width, --linewidth

Set line width in pt.

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