Density functional theory (DFT) is a computational technique in quantum chemistry/physics that makes it possible to obtain the electronic properties of atomic systems (crystals, molecules, etc.) entirely from first-princples. This makes DFT a powerful tool in materials science, as it allows researchers to accurately calculate the electronic structure of any system via a (relatively) inexpensive computer calculation, which is almost always faster, easier and cheaper than having to prepare physical samples and perform laboratory experiments. The results of DFT calculations can be used to accurately obtain dozens, if not hundreds of distinct material properties, and as such it has found use across a wide range of scientific disciplines. The image below shows the electronic bandstructure of a single quintuple-layer of Bi2Te3, a topological 2D material whose atypical 'ring-shaped' valence band makes it an excellent thermoelectric material.

Most DFT calculations are performed in one of four main software packages: ABINIT, VASP, Gaussian and Quantum Espresso. Whichever is chosen, one performs calculations by creating formatted input files which define a large number of parameters, including the type of calculation to be performed, the system to be simulated (atomic positions, lattice vectors, atomic species, etc.), calculational parameters like the cutoff energies, the k-point mesh, convergence tolerances, etc. These input files are then fed to whichever DFT software package, which crunches a lot of numbers, then writes an output file containing the requested information about the electronic structure of the system. These output files need to be parsed to put the desired data into a useful format for analysis. Futhermore, ensuring that the various values obtained are sufficiently converged often requires performing a large number of calculations for a range of input parameter values, which requires the creation of a large number of input files with only small differences between them.

This repository consists of a variety of types of Python scripts designed to facilitate DFT calculations in Quantum Espresso (QE). Somewhat arbitrarily, we choose to think of a standard DFT calculation as consisting of three distinct classes of information, contained in three different types of file, namely STRUCT, KPTS and PARAMS.

The STRUCT file defines the system being simulated, providing the atomic locations, atomic types, psuedopotential file locations and lattice vectors. We have provided a number of structure generator functions that each output STRUCT files for a particular class of structure as a function of input arguments such as vacuum layer, atomic position, lattice vector length, etc. This allows one to easily perform a large number of calculations systematically varying one or more structural parameters, which is often of use when setting vacuum layers or performing structural relaxations.

The KPTS file defines the k-points on which the calculation is going to be performed. A couple of file generators are provided, one for automatically generated grids (good for nkpt convergence tests, SCF and full-BZ NSCF calculations), and one for an input list of k-points (good for bandstructure calculations).

The PARAMS file contains the rest of the information about the calculation, including the type of calculation to be performed (SCF, NSCF, relaxation...), the cutoff energies, the convergence tolerances, filenames, etc.

For the three main classes of calculation performed in QE (SCF, NSCF, structural relaxation), we provide 'maker' functions that take a STRUCT file, a KPTS file and a stencil file as input, and output an input file ready for a QE calculation. The stencil file is first converted into a valid PARAMS file. Default values are assigned to each PARAMS variable unless the variable in question was assigned a value when the function maker was called, i.e make_scf(STRUCT, KPTS, stencil, ecutwfc=100)

We also provide parser functions for these three classes of calculation, which scrape all quantities of interest from the QE output files and write them to Python dictionaries, ready for plotting or further analysis. Summary functions are also provided, which allow one to quickly check the calculational parameters of a given output file from the command line.