BNL Home

software: comsuite modules

Cif2MatDeLab.py

Converting Crystallographic Information Files to MatDeLab input files

This manual describes the input generators for the DMFT MatDeLab code base. The assumption is that the material structure is given by a file in a common file format such as CIF [Bernstein 2016]. Given the material structure and a number of options a script can be run that generates the appropriate input files for the relevant code modules.The supported code modules include:

  • The GW code [Kutepov 2017] as included in this collection of codes

This manual describes the relevant aspects of the input generator.

Installation

The input generators are Python scripts and therefore no compilation is needed to install them. These scripts do have dependencies on other Python packages that need to be present in your local Python installation.

The input generators depend on the following Python packages.

  • Pymatgen [Ong 2013]

The scripts are provided in the directory DMFT_MatDeLab/bin which must be added to your PATH environment variable.

Command Line Options

The cif2matdelab.py script is typically run from the command line. It proceeds by reading the file defining the material structure and based on the command line options it generates a suitable input file. The input file generation may involve a number of transformations of various parameters to ensure that a valid calculation is specified. These transformations are specific to the LAPW basis set [Andersen 1975] used in the calculations and more details are provided in the appendices. The most basic invocation of the input generator is:

cif2matdelab.py .cif 

which produces a file ini with a boiler plate input file for the specified material.

Band Structure

The band structure is a common property used to understand materials properties. By default the band structure is always calculated, however to save on computational resources one may want to suppress its evaluation. The flag ‘–band’ may be used for this purpose. For example:

cif2matdelab.py –band N .cif

Cutoff Energy

The LAPW basis set includes plane waves in the interstitial region. As is conventional with plane wave methods the size of the basis set can be determined based on a cutoff energy for the kinetic energy. This cutoff energy may be specified in Rydberg using the flags ‘-k’ or ‘–Kmax’. The value of the flag determines both the plane wave basis as well as the atomic basis inside the muffin tin radius.

cif2matdelab.py –Kmax 2.1 .cif

Density of States

Just like the band structure, the density of states is also a common property used to understand materials properties. The density of states is calculated by default, but to save on computational resources one may want to suppress its evaluation. The “–dos” flag may be used for this purpose. For example:

cif2matdelab.py –dos N .cif

Help

The script has build-in help that can be requested with either the ‘-h’ or ‘–help’ flags. For example:

cif2matdelab.py –help

Method

The script is planned to support multiple code modules. The different code modules will provide different capabilities in particular with respect to the energy expressions used. The flags ‘-m’ or ‘–method’ may be used to select an energy expression from:

“hf” for the Hartree-Fock energy expression “dft” for the DFT energy expression [Kohn 1965] “gw” for the GW energy expression [Hedin 1965] “qp” for the QP energy expression [Kutepov 2017] (this is the default)

Modified number of DFT iterations

Based on the method selected a default number of DFT iterations is requested. However, one may want to run a different number of DFT iterations to deal with particular convergence characteristics. The “–dft-it” flag may be used for this purpose. For example:

cif2matdelab.py –dft-it 50 .cif

Modified number of HF iterations

Based on the method selected a default number of HF iterations is requested. However, one may want to run a different number of HF iterations to deal with particular convergence characteristics. The “–hf-it” flag may be used for this purpose. For example:

cif2matdelab.py –hf-it 50 .cif

Modified number of GW iterations

Based on the method selected a default number of GW iterations is requested. However, one may want to run a different number of GW iterations to deal with particular convergence characteristics. The “–gw-it” flag may be used for this purpose. For example:

cif2matdelab.py –gw-it 50 .cif

Modified number of QP iterations

Based on the method selected a default number of QP iterations is requested. However, one may want to run a different number of QP iterations to deal with particular convergence characteristics. The “–qp-it” flag may be used for this purpose. For example:

cif2matdelab.py –qp-it 50 .cif

Restart

The calculations supported can take considerable computational resources to finish. As a result they may not complete within the maximum computer time allocation for a single job. To complete such calculations it is necessary to restart a calculation, possibly multiple times. This requires setting the calculation up in such a way that prior results will be reused. Running the script with the ‘-r’ or ‘–restart’ flags. For example:

cif2matdelab.py –restart .cif

The restart option may also be used to advance a prior calculation. For example, one may want to add a GW calculation to a prior DFT calculation.

Version

The version information is available upon request with the ‘–version’ flag.

  

Appendix A: Selecting the muffin tin radii

A critical aspect of the LAPW basis is that the model of atomic basis functions within the muffin tin radius joining to plane waves in the interstitial region, does not allow for overlapping muffin tin radii. As a starting point predefined radii are used that are stored within the input generator. In practice these radii might violate the no-overlap requirement as different crystal structures may have very different atom packing. Therefore we consider all different atom pairs and test for each pair whether the sum of initial muffin tin radii exceeds the minimal distance between the atoms. If the sum of the radii is greater than the inter-atom distance then a smaller muffin tin radius is calculated as

muffin radius equation

For a given atom i  the smallest value of RiMT'  is selected as the final muffin tin radius.

Initial muffin tin radii for the elements of the periodic table based on Elk 3.1.12.

Elements Initial Radius
H - He 1.4
Li - O 1.8
F 2.0
Ne 1.6
Na - Cl 2.2
Ar 2.0
K - Br 2.4
Kr 2.2
Rb - I 2.6
Xe 2.4
Cs - At 2.8
Rn 2.6
Fr - Ts 3.0
Og 2.8

The initial values for the radii are given in Initial muffin tin radii for the elements of the periodic table based on Elk 3.1.12.
 

Appendix B: Choosing the basis set

All the codes in the MatDeLab project work in the LAPW basis. This basis consists of two parts:

  1. Atomic wave functions within a muffin tin radius
  2. Plane waves in the interstitial region

The atomic to plane wave matching condition

In order for the orbitals to be defined properly they have to continuous at the muffin tin radius, and for the kinetic energy to be well defined they also have to have a continuous first order derivative at that radius. In practice that means that the atomic and the plane wave basis functions cannot be selected independently. Instead, they have to chosen such that the continuity equations have a solution. In addition the plane wave basis set has to be chosen in accordance to the cutoff energy. In practice the continuity conditions along with the chemical element dependent highest occupied orbital angular momentum determine a lower limit on the plane wave cutoff. As this is a minor issue that aspect will not be discussed here.

In his book Singh [Singh 1994] showed that in order for the plane waves to match the oscillations of the spherical harmonics of the atomic basis functions the condition

RMT K = lmax

must hold. Here RMT  is the muffin tin radius for a particular element, lmax  is the maximum angular momentum basis function on that element, and K  is the plane wave cutoff. Hence once the cutoff energy is specified and the muffin tin radii are established the maximum angular momentum for each element can be calculated. The atomic basis set is then composed from stored data, automatically extended up to the required maximum angular momentum.

The impact of the packing factor

An additional complication stems from different basis set requirements depending on the packing factor of a material. For close packed materials the packing factor is high (around 0.74) and the interstitial region is small. Materials such as, for example diamond, have a small packing factor (around 0.34) and correspondingly the interstitial region is large. For the latter kind of materials the quality of the basis set depends more strongly on the number of plane waves. Hence a linear relation is used to scale the plane wave basis set up by a factor 1 to 2 when the packing factor goes down from 0.5 to 0.3.

The choice of atomic basis functions

The atomic basis functions within the muffin tin radius have to chosen with a few considerations in mind:

  1. Inner core orbitals are compact and not affected by their environment
  2. Core orbitals are relatively compact and therefore local
  3. Valence orbitals are key to the interaction of atoms with their environment
  4. Virtual orbitals do not directly impact the physical properties

These considerations motivate a number of choices. One general choice stems from the fact that the occupied orbitals are clearly defined by the Schrodinger equation. By this we mean that any changes to these orbitals directly impact the physical properties of the system, in particular the total energy. Therefore the linearization energies can be determined safely from solving the atomic Schrodinger equation. The virtual orbitals do not directly affect the physical properties. They only affect these properties in as much as they mix with the occupied states. Hence optimizing their linearization energies based on the Schrodinger equation is risky. Therefore it is preferable to freeze their linearization energies at their initial values. In addition to these general considerations the above conditions lead to the following choices:

The inner core orbitals are solved from the atomic Schrodinger equation. The linearization energies are updated throughout the calculation. Once the DFT phase of the calculation is completed the Hartree-Fock equations are used to solve for the inner core orbitals.

The core orbitals are chosen to be local within the muffin tin radius (i.e., they are guaranteed to go to zero at the muffin tin radius and are therefore marked as “LOC”). This also means that they are not matched to the interstitial wavefunctions that are expressed in plane waves. Their linearization energy is given an initial value that is further optimized throughout the initial DFT calculation.

The valence orbitals will spill out of the muffin tin sphere, and are therefore matched to the interstitial orbitals. In particular the valence s-, and p-orbitals are marked at “APW”. The valence f-orbitals by contrast are so compact that they are local, marked as “LOC”. The valence d-orbitals are somewhere in between. Typically the highest occupied orbital is marked as “APW”. Again their linearization energies are well defined by the Schrodinger equation and hence they can be optimized throughout the DFT calculation.

The virtual orbitals are less well defined the atomic Schrodinger equation. They contribute mainly by mixing with the occupied states. Hence they are considered to be local (marked as “LOC”) and forced to go to zero at the muffin tin radius. Their linearization energies are kept fixed at their initial values.

The orbital linearization energies are initialized according to P = N + ½ - arctanD/π , where N  is the principal quantum number of the orbital, and D  is the logarithmic derivative of the orbital at the muffin tin radius.

The core, valence, and the lowest virtual orbitals are stored in a table in the input generator. Depending on the cutoff energy additional virtual orbitals can be generated and added as needed by a simple algorithm. The valence orbitals are essentially the highest occupied orbitals. Last, core orbitals are the remaining orbitals stored. Because these core orbitals are optimized during the DFT calculation the quality of the results may depend on how deep in energy the transition between core and inner core orbitals is chosen. In particular in the block between Si and Te it was found that extending the core orbitals one s- and p-shell further down was essential to obtain good band structures.
 

References

[Andersen 1975] O.K. Andersen, “Linear methods in band theory.” Physical Review B (1975) 12, 3060-3083. Doi: 10.1103/PhysRevB.12.3060.

[Bernstein 2016] H.J. Bernstein, J.C. Bollinger, I.D. Brown, S. Grazulis, J.R. Hester, B. McMahon, N. Spadaccini, J.D. Westbrook, S.P. Westrip, “Specification of the Crystallographic Information File format, version 2.0.” Journal of Applied Crystallography (2016) 49, 277-284. Doi: 10.1107/S1600576715021871.

[Hedin 1965] L. Hedin, “New Method for Calculating the One-Particle Green’s Function with Application to the Electron-Gas Problem.” Physical Review A (1965) 139, 796-823. Doi: 10.1103/PhysRev.139.A796.

[Kohn:1965] W. Kohn, L.J. Sham, “Self-Consistent Equations Including Exchange and Correlation Effects”, Physical Review 140 (1965) A1133-A1138. Doi: 10.1103/PhysRev.140.A1133.

[Kutepov 2017] A.L. Kutepov, V.S. Oudovenko, G. Kotliar, “Linearized self-consistent quasiparticle GW method: Application to semiconductors and simple metals.” Computer Physics Communications (2017), Doi: 10.1016/j.cpc.2017.06.012.

[Ong 2013] S.P. Ong, W.D. Richards, A. Jain, G. Hautier, M. Kocher, S. Cholia, D.Gunter, V. Chevrier, K.A. Persson, G. Ceder, “Python Materials Genomics (pymatgen): A Robust,Open-Source Python Library for Materials Analysis.” Computational Materials Science (2013) 68, 314-319. Doi: 10.1016/j.commatsci.2012.10.028 (see also: http://pymatgen.org/).

[Singh 1994] D.J. Singh, “Planewaves, pseudo-potentials and the LAPW method”, Springer (1994), ISBN: 978-1-4757-2314-4 (Print), Doi: 10.1007/978-1-4757-2312-0, pp. 62-63.

[Slater 1937] J.C. Slater, “Wave Functions in a Periodic Potential.” Physical Review (1937) 51, 846-851. Doi: 10.1103/PhysRev.51.846.

©2017, Gabi Kotliar, Ran Adler, Sangkook Choi, Andrey Kutepov, Patrick Semon, Hubertus van Dam. | Powered by Sphinx 1.6.3 & Alabaster 0.7.10 | Page source