phelel-init and phelel commands#
Command-line tools perform steps 1 and 3 in the el-ph calculation workflow. Their usage parallels that of the phonopy-init
and phonopy commands in phonopy for
phonon calculations.
phelel-initgenerates supercells with displacements (step 1).phelelcalculates the derivatives of local potentials and PAW strengths from the results of the VASP calculations of these supercells (step 3).
The following example demonstrates the two steps:
% phelel-init -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
# After running VASP calculations in directories corresponding to displacements:
% phelel --cd disp-000 disp-001 disp-002 disp-003 disp-004 --fft-mesh 18 18 18
The numbers given to --fft-mesh depend on the crystal and on the VASP
calculation; see --fft-mesh.
Generation of displacements in supercell by phelel-init#
Supercells with displacements can be generated by combining the following command options. For example:
% phelel-init -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
Here, POSCAR-unitcell is the unit cell structure in VASP POSCAR format. After
this operation, a file named phelel_disp.yaml, containing information about
the displacements, is created. Additionally, the supercell structures SPOSCAR,
POSCAR-001, and so on are generated.
-d#
This generates supercells with systematically introduced displacements. The
displacements are determined by crystal symmetry, with exactly one displacement
applied in each supercell. phelel-init needs this option.
--dim#
Three or nine integer values specify the supercell shape with respect to the
unit cell structure indicated by the -c option. If nine values are provided,
they correspond to the supercell matrix as defined in the phonopy
documentation. If
three values are given, they represent the diagonal elements of the supercell
matrix, meaning each axis of the input unit cell is simply extended by the
corresponding integer factor.
% phelel-init --dim 2 2 2 [OPTIONS]
% phelel-init --dim 0 1 1 1 0 1 1 1 0 [OPTIONS]
-c, --cell#
Unit cell structure is specified.
% phelel-init -c POSCAR-unitcell [OPTIONS]
--pa, --primitive-axis#
Transformation matrix from the input unit cell to the primitive cell. It is given
either as nine values forming the 3x3 matrix [[v1, v2, v3], [v4, v5, v6], [v7, v8, v9]], or as auto to search the primitive cell automatically. This works
the same way as the PRIMITIVE_AXES tag in
phonopy.
% phelel-init --pa auto [OPTIONS]
--pm#
Unless specified, only one directional displacement is selected among symmetrically equivalent displacements in the opposite direction. With this option specified, both directions are included in the generated supercells with displacements. Use of this option is recommended.
% phelel-init --pm [OPTIONS]
--magmom#
Magnetic moments of the atoms in the unit cell are specified in the order of
the atoms. One value per atom is given for a collinear calculation
(ISPIN = 2), and three values, the x, y and z components, per atom for a
non-collinear calculation (LNONCOLLINEAR = .TRUE.). As in the MAGMOM tag of
VASP, 4*1 means 1 1 1 1. Such values are enclosed in quotes, because the
shell may expand *.
% phelel-init --magmom 2 -2 [OPTIONS]
% phelel-init --magmom "4*1 4*-1" [OPTIONS]
% phelel-init --magmom 0 0 2 0 0 2 [OPTIONS]
The magnetic moments are stored in phelel_disp.yaml. The MAGMOM line for the
supercell is written in the file MAGMOM, which is used in the INCAR of the
VASP calculations of the supercells.
Without --magmom, the symmetry operations are found from the positions and
the species of the atoms, and they act on the atomic positions. With
--magmom, the magnetic moments are also included in what the symmetry
operations act on. Each operation then maps the atomic positions and the
magnetic moments together, and it may be combined with time reversal, which
reverses the magnetic moments. These operations form the magnetic space group.
The displacements and the symmetrization of the derivatives use the same
operations.
In a spin-polarized or non-collinear VASP calculation, the local potential and the PAW strengths have spin parts, and the symmetry operations are applied also to these spin parts in the symmetrization. When the magnetic moments are not included in the symmetry operations, an operation that maps the atomic positions but not the magnetic moments may be used. An example is an operation that moves an atom with an up spin onto an atom with a down spin. The derivatives obtained with such an operation are wrong.
When the magnetic moments are zero in the VASP calculation, zeros are given by
--magmom. The default value of MAGMOM in VASP is not zero in a
spin-polarized or non-collinear calculation, so the file MAGMOM with zeros
makes the VASP calculation start from zero magnetic moments. With zeros, every
operation found from the atomic positions is used both without and with time
reversal.
The number of values has to fit the VASP calculation, one or three per atom,
also when all the values are zero. Otherwise phelel --cd stops with an
error. When --magmom is not used and the VASP calculation is spin-polarized
or non-collinear, phelel --cd shows a warning.
phelel --cd also applies every symmetry operation to the PAW strengths Dij
of the perfect supercell. Dij should be unchanged by every operation, and a
warning is shown when an operation changes it by more than 0.01 eV. This
happens when the magnetic moments included in the symmetry operations do not
describe the magnetic state of the VASP calculation, for example when the sign
or the direction of a magnetic moment differs from that in the VASP
calculation, or when the VASP calculation converged to another magnetic state.
Calculation of derivatives of potentials by phelel#
After running VASP calculations to calculate local potentials and PAW strengths under the configurations of displacements in supercells, those data are stored in certain files. Those are read and then the derivatives are computed by the following command, e.g.,
% phelel --cd disp-000 disp-001 disp-002 disp-003 disp-004 --fft-mesh 18 18 18
Here disp-000, disp-001, …, indicate the directories in which VASP
calculations were performed for respective supercells with displacements, i.e.,
SPOSCAR, POSCAR-001, …, as generated by phelel-init. The displacements
are read from phelel_disp.yaml in the current directory. Another
phelel_disp.yaml-like file can be given as the argument of phelel:
% phelel phelel_disp.yaml --cd disp-000 disp-001 disp-002 disp-003 disp-004 --fft-mesh 18 18 18
--cd, --create-derivatives#
This triggers two sequential operations. First, VASP calculation results are
collected from the specified directories in the order given by the command
options. Next, using these collected data, the derivatives of local potentials
and PAW strengths with respect to displacement are calculated and stored in
phelel_params.hdf5. --cd needs --fft-mesh.
When every directory has LOCAL-POTENTIAL.bin, which VASP writes with
LWAP = .TRUE., the local potentials and the PAW strengths are read from
LOCAL-POTENTIAL.bin, PAW-STRENGTH.bin and PAW-OVERLAP.bin, with
inwap.yaml. Otherwise they are read from vaspout.h5. VASP 6.6.1 and older
do not write the local potential correctly in vaspout.h5 for ISPIN = 2 or
LNONCOLLINEAR = .TRUE., and phelel --cd stops with an error when it would read
such a local potential. Run VASP with LWAP = .TRUE. for these calculations.
velph init writes lwap = true for the phelel calculations of these kinds.
--fft-mesh#
Three integers give the FFT mesh of the primitive cell on which the derivatives
of the local potentials are written in phelel_params.hdf5. Give the FFT mesh
(NGX, NGY, NGZ) that VASP uses for the primitive cell in the electron-phonon
calculation. velph phelel differentiate computes this mesh from ENCUT and PREC
of the electron-phonon calculation and gives it to phelel.
--dv-evaluation-method#
VASP gives the change of the local potential, \(\Delta V\), on the FFT mesh of the
supercell. phelel needs \(\Delta V\) at the points of the mesh given by
--fft-mesh and at these points moved by the symmetry operations. These points
are in general not on the FFT mesh of the supercell.
At such a point \(\mathbf{r}\), phelel computes \(\Delta V(\mathbf{r})\) from the Fourier coefficients \(c(\mathbf{g})\) of the values on the FFT mesh of the supercell, which are their discrete Fourier transform:
Here \(\mathbf{r} = (r_1, r_2, r_3)\) is the position in the basis vectors of the
supercell, and the integers \(\mathbf{g} = (g_1, g_2, g_3)\) give a reciprocal
lattice vector of the supercell, so that
\(\mathbf{g} \cdot \mathbf{r} = g_1 r_1 + g_2 r_2 + g_3 r_3\). The sum has one
term for each point of the FFT mesh of the supercell. --dv-evaluation-method
chooses where each coefficient is placed in the sum and how the sum is computed.
|
Where each coefficient is placed |
How the sum is computed |
|---|---|---|
|
shortest |
without approximation |
|
box |
without approximation |
|
box |
finufft to the accuracy of |
Let \(N_1\), \(N_2\) and \(N_3\) be the mesh numbers of the FFT mesh of the supercell. For integers \(n_1\), \(n_2\) and \(n_3\), \(\mathbf{g}\) and \(\mathbf{g} + (N_1 n_1, N_2 n_2, N_3 n_3)\) have the same coefficient. Each coefficient is placed at one of these \(\mathbf{g}\) in the sum. At the points of the FFT mesh of the supercell, \(\exp(2\pi i \mathbf{g} \cdot \mathbf{r})\) is the same for all of them, so the choice does not change \(\Delta V(\mathbf{r})\) there. At other points, the choice changes \(\Delta V(\mathbf{r})\).
“Shortest” places each coefficient at the \(\mathbf{g}\) whose reciprocal lattice vector is the shortest. When several of them have the same length, the coefficient is divided equally among them. Then \(\Delta V(\mathbf{r})\) has the symmetry of the crystal and is real (Hermitian with non-collinear spin) at every point.
“Box” places each coefficient at the \(\mathbf{g}\) with \(-N_k/2 < g_k \le N_k/2\). For an even \(N_k\), the coefficient is placed at \(g_k = N_k/2\) and not divided with \(g_k = -N_k/2\). When this coefficient is not zero, \(\Delta V(\mathbf{r})\) between the points of the FFT mesh of the supercell has an imaginary part, and in general does not have the symmetry of the crystal.
shortest and box compute the sum in two steps. Many terms of the sum have
the same \(\exp(2\pi i \mathbf{g} \cdot \mathbf{r})\) at all the points of
--fft-mesh, and phelel first adds up the coefficients of these terms. phelel
then computes the sum of the remaining terms by inverse FFTs. The result is the
sum itself, up to rounding errors. finufft computes the sum with finufft,
which approximates it to the accuracy of --finufft-eps.
When the points given by --fft-mesh are on the FFT mesh of the supercell, the
choice of --dv-evaluation-method does not change the derivatives. Otherwise
the derivatives of shortest differ from those of box and finufft. In the
examples tested, the real parts differed by up to 3e-6 relative to the largest
value. box and finufft gave imaginary parts of up to 4e-4 relative, and
shortest gave none.
box gives the values that finufft computes, without the error of finufft. The
derivatives of box and finufft differ by the error of finufft.
finufft is not a dependency of phelel. To use
--dv-evaluation-method finufft, install the finufft package by
conda install -c conda-forge finufft or pip install finufft.
--finufft-eps can be given only with finufft.
finufft runs on all the CPU cores by default. In shortest and box, the
inverse FFTs and the steps done by phonors also run on all the CPU cores.
In a configuration file, DV_EVALUATION_METHOD = box is the same as
--dv-evaluation-method box.
--no-fc-symmetry#
The force constants computed by finite differences are symmetrized by the symfc
projector by default. With --no-fc-symmetry, they are not symmetrized, as in
version 0.19.0 and earlier. The derivatives of the local potentials and PAW
strengths do not depend on this option.
In a configuration file, FC_SYMMETRY = .false. is the same as
--no-fc-symmetry.
--config#
The settings are read from the configuration file given by --config, e.g.,
% phelel --config phelel.conf --cd disp-000 disp-001 disp-002 disp-003 disp-004
with phelel.conf
FFT_MESH = 18 18 18
The argument of phelel is always read as a phelel_disp.yaml-like file. A
configuration file given as the argument is an error.
The supercell matrices are those in phelel_disp.yaml, to which the
displacements belong. DIM and DIM_PHONON in the configuration file do not
replace them, and phelel reports the ones given if they differ.
Commands of earlier versions#
Earlier versions of phelel used a single phelel command to generate the
supercells with displacements and to calculate the derivatives. The two steps
are now done by two commands:
Earlier command |
Command now |
|---|---|
|
|
|
|
|
|
phelel stops with an error when it is given an option of phelel-init, such
as -d, -c or --dim, and the error tells to use phelel-init. With -c,
the earlier phelel --cd also read a crystal structure in a POSCAR-like file;
phelel reads it only from phelel_disp.yaml. phelel-load still works as
phelel and prints that it is deprecated.