# Building Input Files

### Command summary

The tutorial starts under the heading “Tutorial”; you can see a synopsis of the commands by clicking on the box below.

$blm init.pbte$ cp actrl.pbte ctrl.pbte
$cp testing/cif2cell.batio3 .$ cif2init cif2cell.batio3        # creates an init file from
$poscar2init # creates an init file from a VASP POSCAR file$ poscar2site                     # creates a  site file from a VASP POSCAR file
$testing/test.blm 2$ poscar2init > init.zn3as2
$blm zn3as2 --fixpos:tol=1e-6 > out.zn3as2$ testing/test.blm 3
$blm bi2te3$ cp actrl.bi2te3 ctrl.bi2te3
$lmchk bi2te3$ cp actrl.bi2te3 ctrl.bi2te3
$lmfa bi2te3$ cp basp0.bi2te3 basp.bi2te3
$lmfa bi2te3$ blm --gw bi2te3


### Preliminaries

The materials system in this tutorial is Bi2Te3; you will build an input file ctrl.bi2te3 by one of several possible paths.

The input file structure is briefly described in this lmf tutorial for Pbte, which you may wish to go through first.

This tutorial assumes you have blm installed. Additionally, poscar2init, lmchk, lmscell, poscar2site and cif2site may be required for some sections.

### Tutorial

blm is an input file generator. You can use it autogenerate an input file (ctrl.ext); or you can build it yourself. blm usually writes the structural data to a site file (site.bi2te3). Site files are a primary way structural data is kept in a form the Questaal programs can read.

In either case, you need structural information to get started. In default mode blm reads structural data from a file init.ext, and writes a ctrl file and a site file. It can read structural data from a site file.

#### 1. Importing Crystal Structure

##### 1.1 Supplying Crystal Structure by hand

Typically you have structural information about your material, e.g. space group number (e.g. number 99 or name P4mm) and lattice parameters related to the space group (a and b in the P4mm case). This page will use Bi2Te3 as an example, which belongs to space group R3m with lattice constants a and c. (See Wykoff, Structure of Crystals, to obtain this information.) You also need information about the chemical species and positions of the atoms in the basis. The minimum information for Bi2Te3 is:

ATOM=Te X=0     0    0
ATOM=Te X=0     0   .788
ATOM=Bi X=0     0   .4


There are five atoms in the basis; the positions of the remaining two follow from the symmetry of the space group (R3m).

Symbols Te and Bi tell blm that the atoms are Tellurium and Bismuth, with atomic numbers 52 and 83. You can use any symbol for the species name, but if you don’t use a standard one you must specify the atomic number, e.g. write ATOM=A Z=52.

The three coordinates e.g. (0 0 0.788) correspond to fractions of the first, second, and third lattice vectors. This is a standard way of representing site coordinates. Alternatively, you can specify Cartesian coordinates; use POS= in place of X=. In the Bi2Te3 case, substituting the above 3 lines with

ATOM=Te POS= 0.0000000   0.0000000   0.0000000
ATOM=Te POS=-0.5000000  -0.8660254   1.4616199
ATOM=Bi POS= 0.5000000   0.8660254   0.8030878


creates the same input template.

##### 1.2 Importing a CIF file

Crystallographic Information Files (CIF files for short) is a standard text file format for representing crystallographic information, whose standards are set by the International Union of Crystallography. If you have a CIF file, you can automatically make either an init.ext file, or a site.ext file. The tools in this package do not read CIF files directly, but parse the output of the cif2cell program (version 1.1.0). cif2cell is a very versatile tool, freely available on the web.

To import data from a CIF file you need cif2cell installed and cif2init in your path (cif2init should be automatically compiled with this package). The steps are:

1. Run cif2cell (without any special switches) and capture the output in a file, e.g. cif2cell.out . 2. Run cif2init to generate an init file (called simply  init ‘). 3. Rename init to init.ext and use the blm tool.

Example : create an init file for the orthorhombic form of BaTiO3:

$cp testing/cif2cell.batio3 .$ cif2init cif2cell.batio3


Note: cif2cell.batio3 was obtained by running cif2cell on the CIF file supplied with the cif2cell-1.1.0 distribution: cif2cell-1.1.0/cifs/BaTiO3_orthorhombic.cif.

The following init file should be generated:

HEADER Ba (Ti O3) (Barium titanate - nanocrystalline)
LATTICE
#       SPCGRP=38
#       A=4.0094  B=5.6214  C=5.6386   ALPHA=90  BETA=90  GAMMA=90
% const a=4.0094
ALAT={a}  UNITS=A
PLAT=    1.0000000    0.0000000    0.0000000
0.0000000    0.7010276   -0.7031725
0.0000000    0.7010276    0.7031725
SITE
ATOM=Ba       X=     0.0000000    0.0000000    0.0000000
ATOM=Ti       X=     0.5000000    0.4900000    0.5100000
ATOM=O        X=     0.5000000    0.0100000    0.9900000
ATOM=O        X=     0.5000000    0.0129000    0.4921000
ATOM=O        X=     0.5000000    0.5079000    0.9871000


If you prefer to make your own input file but import structure information via a site file, use cif2site in place of cif2init. To summarize:

cif2init creates an init file from the output of cif2cell cif2site creates a site file from the output of cif2cell

##### 1.3 Importing a POSCAR file

VASP is a very popular electronic structure program which can store structural information in the POSCAR files. If you want to import data from such a file in a form suitable for this program suite, use one of the following commands:

$poscar2init creates an init file from a VASP POSCAR file$ poscar2site     creates a  site file from a VASP POSCAR file


If you already have an input file, use poscar2site to translate structural data from a POSCAR file into site.ext. If you want an input file instead, use poscar2init; then run blm.

Example: create an input file for Zn3As2 from a POSCAR file:

$testing/test.blm 2  The script has the following steps $ poscar2init > init.zn3as2
$blm zn3as2 --fixpos:tol=1e-6 > out.zn3as2  which creates an input file template (actrl.zn3as2) from a POSCAR file in two steps. Example: create a site file for the Kesterite Cu2ZnSnS4: $ testing/test.blm 3


It creates file site from file POSCAR.

#### 2. Running blm

blm will create a template file for the main input file of the Questaal package, ctrl.ext. ext_{: style=”color: green”} is a name you select; we will use bi2te3 corresponding to the material. blm actually generates actrl.ext, prepending the a so as not to overwrite any file named ctrl.ext.

Almost all programs in this package require the input file ctrl.ext. You can do an entire calculation starting only with this file; but often you supply other files. For example, symmetry line points for plotting energy bands are read from a separate file (e.g. syml.bi2te3). Structural data is typically split off into a separate file (site.bi2te3 in this tutorial); blm will create a site file by default.

##### 2.1 init{: style=”color: green”} file

Create a file named init.bi2te3 containing the following lines:

    # from http://cst-www.nrl.navy.mil/lattice/struk/c33.html
# Bi2Te3 from Wyckoff
% const a=4.3835 c=30.487 uTe=0.788 uBi=0.40
LATTICE
SPCGRP=R-3M
UNITS=A
A={a} C={c}
SITE
ATOM=Te X=0     0    0
ATOM=Te X=0     0   {uTe}
ATOM=Bi X=0     0   {uBi}


Note

• Lines which begin with ‘#’ are comment lines and are ignored. (More generally, text following a #’ in any line is ignored).
• Lines beginning with ‘%’ are directives to the preprocessor. Directives can perform various functions similar to a normal programming language, such as assigning variables, evaluating expressions, conditionally readings some lines, and repeated loops over sections of input.
• Quantities in brackets {…} are algebraic expressions parsed by the preprocessor, evaluated and the result the contents of brackets replaced by the result.

init files and ctrl files are styled the same way: data is divided into categories (LATTICE and SITE) — tags which begin in the first column, and tokens (e.g. SPCGRP=, A=, X=) — tags belonging to a particular category.

This tutorial explains how the input files init.ext and ctrl.ext are structured, and the tags the various programs can read.

##### 2.2 ctrl{: style=”color: green”} file

To create a template input file invoke blm:

$lmfa bi2te3  With the latter choice lmfa operates a little differently from before as can be seen by comparing new output with the old. Initially the Bi 5d was part of the core; now is included as part of the valence. 2. blm does not by default assign any value to the plane wave cutoff for the interstitial density. lmf reads this information through HAM_GMAX. It is a required input; but blm does not pick a value because its proper choice depends on the smoothness of the basis. lmfa will determine a suggested value for HAM_GMAX for you. In the present instance, when the usual 6s, 6p, 6d, 5f states are included lmfa recommends GMAX=4.4 as can be seen by inspecting the first lmfa run. In the second run it recommends GMAX=4.1 from the valence states alone (as before), but because of the 5d state lmfa recommends that GMAX=8.1. The 5d state is strongly peaked at around the atom, and requires more plane waves to represent reasonably, even a smoothed version of it, than the other states. The difference between 8.1 and 4.4 is substantial, and it reflects the additional computational cost of including deep core-like states in the valence. This is the all-electron analog of the “hardness” of the pseudopotential in pseudopotential schemes. If you want high-accuracy calculations (especially in the GW context), you will need to include these states as valence. This particular choice of local orbital is rather overkill for LDA calculations however. If you eliminate the Bi 5d local orbital you can set GMAX=4.4 and significantly speed up the execution time. 3. blm assigns the initial k-point mesh to zero. Note the following lines in actrl.bi2te3: % const met=5 nk=0 BZ NKABC={nk} METAL={met} # NKABC requires 1 to 3 positive numbers  BZ_NKABC governs the mesh of k-points. An appropriate choice will depend strongly on the context of the calculation and the sytem of interest; the density-of-states at the Fermi level; whether Fermi surface properties are important; whether you want optical properties as well as total energies well described; the precision you need; the integration method, and so on. Any automatic formula can be dangerous, so blm will not choose a default for you. In this case, a 4×4×4 mesh works well. Use your text editor to change nk=0 to nk=4. Alternatively, supply –nk=.. to blm on the command line, as was done in this tutorial. Note that as generated, ctrl.bi2te3 will reflect METAL=5. Using METAL=5 with the tetrahedron integration is the recommended way to handle Fermi surface integration in metals. See this tutorial for some discussion. #### Input files for GW GW calculations demand more of the basis set because unuoccupied states are important. To set up a job in preparation for a GW calculation, invoke blm as : $ blm --gw bi2te3


Compare actrl.bi2te3 generated with the –gw switch to one without. One important difference will be that the default basis parameters are modified because AUTOBAS becomes:

AUTOBAS[PNU=1 LOC=1 LMTO=5 MTO=4 GW=1]


The basis is similar to LMTO=4 but EH has been set a little deeper. This helps the QS_GW_ implementation interpolate between k-points. The larger basis makes a minor difference to the valence bands; but the conduction bands change, especially the higher in energy you go.

Look also at this QS_GW_ demo for Silicon.

*Note The GW implementation allows you to use plane waves, but the QS_GW_ part of it does not, as yet.