(F) Technical notes for dynamical matrix based Debye-Waller factors


DMDW is a set of tools developed to calculate Debye-Waller (DW) factors and other related quantities from a dynamical matrix (matrix of force constants or Hessian matrix) using the Lanczos recursive algorithm.[Refs.] This set includes a module integrated into FEFF, a standalone version that can be used independently of FEFF and a Fortran module that can be integrated into third-party programs. DMDW also includes conversion tools to generate the required input files from different ab initio programs.

F.1 Installing DMDW

F.1.1 Installing as a FEFF module

DMDW is included in the feff distribution and is installed as a feff module with all the other program modules. Please refer to the feff installation instructions. After the feff installation is completed a module called dmdw is located under the feff ‘feff90/bin/Seq’ directory structure.

F.1.2 Creating and installing the standalone version

Within the ‘src/DMDW’ directory in the feff distribution, execute the following command:

make standalone

This will create a directory ‘feff90/src/DMDW/dmdw standalone’. Edit ‘dmdw standalone/src/Makefile’ and change the ”F90” variable to your fortran 90 compiler of choice. Then execute the following commands:

make install
make examples 

If everything worked correctly the reference results located in ‘dmdw standalone/examples/Reference Result should agree with those generated in ‘dmdw standalone/examples’ using the newly compiled executable.

F.2 Using DMDW to calculate Debye-Waller factors F.2.1 Using within a XANES or EXAFS calculation in FEFF

See Chapter 5.

F.2.2 Calculating DW factors using the standalone version

Capabilities of DMDW beyond the feff DEBYE card can be accessed by means of the dmdw module or by compiling the standalone version. All the detailes described below apply to the input used by both the dmdw module and the standalone version. During the execution of a normal FEFF run using ab initio DW factors, an input file ‘dmdw.inp’ for the dmdw module is automatically generated based on the options used in the DEBYE card. This autogener- ated input can be used ”as is” with the standalone version, or further edited to access other capabilities.

‘dmdw.inp’ is composed of at least 5 lines of input. All the parameters must be entered and no default values are available:

nT T_Min T_Max
. . 


• Line 1 - Lanczos Order: Number of Lanczos iterations (integer).

This parameter is equivalent to the DMDW Order parameter described for the DEBYE card. It corresponds to the number of Lanczos iterations to be used in the calculation. Well converged results are usually obtained for DMDW Order = 6 − 10. For small size systems, these values might be too large. As a rule of thumb, this value should be less than 3 ∗ (N umberof atoms) − 6. Some paths in systems with high symmetry might

require a lower recursion order. The user should always check for convergence with this parameter.

• Line 2 - nT: Number of temperature values in grid (integer) T Min, T Max: Minimum and maximum temperature values (real, in K)

Define a grid of temperatures in which to calculate the DW factors. This option is very efficient in the generation of whole temperature curves since it performs the Lanczos procedure only once and then calculates the DW for each temperature.

• Line 3 - DMDW Type: Type of DW calculation (integer).

This parameter is equivalent to the one described for the DEBYE card, but more options are available. The possible values of DMDW Type are: 0 Parallel s2 1 Perpendiculars2 2 Crystallographic u2 3 Vibrational free energy calculation The parallel s2 is the usual mean-square relative displacement (MSRD) along a path. The perpendicular s2 is the MSRD orthogonal to a path. The crystallographic u2 is the mean-square displacement of a given atom with respect to its stationary position. Finally, the vibrational free energy associated with that crystallographic u2 can also be calculated.

[Options 1-3 are not fully activated in this release. Also, the meaning of this parameter might change in a future release]

• Line 4 - Filename: Name of file containing the dynamical matrix (string)

The file must be present in the same directory as the DMDW input and be in ”dym” format (see below).

• Line 5 - nPathDesc: Number of path descriptors (integer)

Define the number of path descriptors to use for the generation of paths.

• Lines 6... - PathDescN: Nth path descriptor used to generate a list of paths (integer and real, see below)

A path descriptor has the following form:

         nAt At(1)...At(nAt) Path\_Length 


nAt: Number of atoms in the path (integer) At(i): Index of atom that must be included in the path (integer)

These indices correspond to the ones used in the ”dym” file. The number 0 is a wildcard representing any atom in the structure. For instance, the atom indices ”1 0 2” represent a double scattering paths starting at atom 1, ending at atom 2 and passing through every other allowed atom in the system. The paths are generated in such a way that no consecutive repeated indices are allowed.

Path Length: Effective path length cutoff (real, in Bohr)

This parameter helps fine-tune the generated path list, removing paths that are longer than necessary.

F.3 The ”dym” dynamical matrix file format

A ”dym” file contains the information required by the Lanczos algorithm. This includes the atomic masses, structure and force constants. Two conversion scripts are included in the ‘feff90/bin/Seq’ directory to convert Gaussian 03 formatted checkpoint (”fchk”) files (fchk2dym) and Quantum Espresso dynamical matrix files (dynG2dym) into our ”dym” dy- namical matrix format. The ”fchk2dym” command has been thoroughly tested, but the ”dynG2dym” has not.

We have also used dynamical matrices calculated by the ABINIT program. However, we don’t currently offer automated tools for this scenario. Users may contact the authors for assistance using ABINIT and dmdw.

The current format of the ”dym” files is as follows:

• Line 1 - dym Type: Dynamical matrix file type (integer) This value is for future use. Set to 1 for now.

• Line 2 - nAt: Number of atoms (integer) Number of atoms in the system.

• Lines 2..2+nAt - Atomic numbers (integer) Atomic numbers of atoms in the system.

• Lines 2+nAt+1..2+2*nAt - Atomic masses (real, in AMU) Atomic masses of the atoms in the system.

• Lines 2+2*nAt+1..2+3*nAt - Atomic coordinates (real, in Bohr) Cartesian coordinates (”x y z”) of the atoms in the system.

• Lines 2+3*nAt+1..End - Dynamical matrix in atom pair block format (integer and real, see below,in atomic units):

The force constants in the system are stored for each pair of atoms in the system using the following block format:

i j d2E/dxidxj d2E/dxidyj d2E/dxidzj d2E/dyidxj d2E/dyidyj d2E/dyidzj d2E/dzidxj d2E/dzidyj d2E/dzidzj


i, j: Indices defining the atomic pair d2E/daidbj: Second derivative of the energy (i.e. force constant) with respect to the a coordinate of atom i and the b coordinate of atom j, where a,b=x,y,z.

Example ”dym” files can be found in the ‘feff90/test/DMDW’ directory.

F.4 Examples

See Chapter 5.

F.5 Troubleshooting dmdw

F.5.1 Lanczos problems

• If the code warns that there are less poles than Lanczos iterations, it usually means that the iteration order is too high. Try with a smaller number.

• When the structure associated with a dynamical matrix is not sufficiently optimized, the program is likely to report that certain paths result in poles associated with imaginary frequencies. The code currently ignores these poles by setting ther weigth to zero. Usually this doesn’t affect the results significantly, but they should be considered very carefully anyway.

• The code checks the symmetry of the dynamical matrix. If it isn’t sufficiently symmetric, the results should be examined carefully.

developer's resources