euphonic-brille-convergence

The euphonic-brille-convergence program is useful for determining grid density or number of grid points that should be used in BrilleInterpolator.from_force_constants to achieve the desired accuracy. It requires a force constants file as input. By default will create a Brille trellis grid with approximately 5000 grid points, and use this grid to calculate q-point frequencies and eigenvectors at 1000 quasirandom q-points, comparing these to the Euphonic-calculated frequencies and eigenvectors for the same 1000 points. The comparison is shown in 3 figures:

• A scatter plot showing the difference between Euphonic-interpolated and Brille-interpolated frequencies (the frequency residual)

• A 3D scatter plot showing the difference between the structure factors calculated from the Euphonic-interpolated and Brille-interpolated frequencies and eigenvectors (the structure factor residual)

• A line plot with 2 axes. The top axis is a line plot of the 1D-averaged intensity calculated from the Euphonic-interpolated and Brille-interpolated frequencies and eigenvectors for the 1000 quasirandom q-points. The bottom axis shows the difference between the Euphonic 1D average and the Brille 1D average (the residual).

Additionally, there may some extra figures, depending on the value of the -n argument (default 0):

• A line plot with 2 axes. The top axis shows a line plot of the intensity for a particular q-point (not 1D-averaged) calculated from the Euphonic-interpolated and Brille-interpolated frequencies and eigenvectors. The bottom axis shows the difference between the Euphonic intensity and the Brille intensity (the residual).

The --brille-npts or --brille-npts-density arguments can be used to change the number or number density of Brille grid points respectively. Note that one or the other should be used, not both. Multiple values can be used for each of these to see the convergence between Euphonic-interpolated and Brille-interpolated values as the number of Brille grid points changes, so can be used to decide which is sufficient for the required accuracy. Each provided value will add an extra series to the figures above.

An example for La2Zr2O7 showing 1 extra figure and 3 different Brille grid sizes is shown below:

euphonic-brille-convergence La2Zr2O7.castep_bin -n 1 --brille-npts 500 2500 5000

To see all the command line options, run:

euphonic-brille-convergence -h

You can also see the available command line options below. For more information on how Euphonic and Brille work together, see see Brille Interpolator.

Command Line Options

Estimate linear interpolation error by comparing with Fourier interpolation

usage: euphonic-brille-convergence [-h] [--asr [{reciprocal,realspace}]]
                                   [--dipole-parameter DIPOLE_PARAMETER]
                                   [--use-c | --disable-c]
                                   [--n-threads N_THREADS] [--e-min E_MIN]
                                   [--e-max E_MAX] [--energy-unit ENERGY_UNIT]
                                   [--ebins EBINS]
                                   [--energy-broadening ENERGY_BROADENING [ENERGY_BROADENING ...]]
                                   [--shape [{gauss,lorentz}]]
                                   [--brille-grid-type {trellis,mesh,nest}]
                                   [--npts NPTS]
                                   [--brille-npts BRILLE_NPTS [BRILLE_NPTS ...]]
                                   [--brille-npts-density BRILLE_NPTS_DENSITY [BRILLE_NPTS_DENSITY ...]]
                                   [-n N]
                                   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).

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

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.

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

--npts

Number of quasirandom samples used in error estimate.

Default: 1000

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

-n

Number of single q-point intensity slices to plot

Default: 0