# Generating Input Files

The purpose of this tutorial is to guide the user in constructing an input file for the Questaal suite of codes.

The primary input file is the ctrl file, named ctrl.ext.   ext is a string you specify; it can consist of letters and numbers, and the underscore character. The structure of ctrl.ext is documented in the input file guide; a careful description of its syntax can be found in this manual.

The easiest way is to use the input file maker blm. Its primary input is the crystal structure (lattice and basis vectors), and it builds a (nearly) complete template ctrl file from it. As input, blm reads from a file init.ext which contains mostly structural information, though the init file can contain a limited amount to augments the template ctrl file, e.g. an estimate for the magnetic moment of a species.

This demonstrates different ways to feed structural information to blm:

The structure of the init file is documented here, and explained in this tutorial through practical examples.

Build a simple input file from an init file

cp ~/lm/testing/init.bi2te3
blm --express bi2te3


Input file from init file, complex case

cp ~/lm/testing/init.sbsei .
blm --gw --addes --fixpos:tol=1e-2 --scalp=1 --xshftx=0,0,-0.0398106/2 --wsitex init.sbsei


Input file from init file, magnetic ASA

cp ~/lm/testing/init.fept .
blm --mag --asa --gf --nk=10 fept


Input and/or site files from cif file

cp ~/lm/testing/cif2cell.batio3 .
cif2init cif2cell.batio3
mv init init.batio3
blm --noshorten --wsitex batio3
cp ~/lm/testing/cif2cell.batio3 .
cif2site cif2cell.batio3


Input and/or site files from POSCAR file

cp ~/lm/testing/POSCAR.zn3as2 POSCAR
poscar2init > init.zn3as2
blm --express=0 zn3as2 --fixpos:tol=1e-6 > out.zn3as2
cp actrl.zn3as2 ctrl.zn3as2
lmchk ctrl.zn3as2 --fixpos:tol=1e-6 --shell:r=.2 >> out.zn3as2

cp ~/lm/testing/sitein.fe2p .
blm fe2p --rdsite --express=1 --mag --findes --asa --omax=.00


### Preliminaries

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

This tutorial assumes you have blm in your path. Additionally, poscar2init, poscar2site, cif2init, cif2site, lmchk, lmscell, lmfa, and lmf may be required for some sections.

For conversion of cif files, you must install cif2cell utility (separately from the Questaal suite),

This tutorial makes use of a few files in the Questaal repository where the executables are built. For purposes of this tutorial we assume it is in directory ~/lm.

blm writes the input file to actrl.ext to avoid overwriting ctrl.ext you might already have. (You can specify otherwise: blm has many command line switches; --ctrl lets you name the file).

### Tutorial

#### 1. Manually entering Crystal Data

Structural data by specifying the space group

Classic books like Wyckoff’s Structure of Crystals provide information about crystal structure in a compact form.

Bi2Te3 and Bi2Se3 have the space group R3M. R3M is a rhombohedral lattice with hexagonal axes, which has two independent dimensions: the length a=4.3835Å of the basal plane and c=30.487Å of the third (c) axis normal to the basal plane.

The primitive unit cell contains 3 Te and 2 Bi atoms; the two Bi and two of the Te and are equivalent by symmetry. Thus coordinates need be specified for only three atoms. Wykcoff writes them as (0,0,0) and (0,0,0.788) for two inequivalent Te, and (0,0,0.4) for one of the Bi. These coordinates are expressed in terms fractional multiples of the lattice vectors in the conventional cell.

This data completely specifies the crystal lattice. Enter this information into file init.ext as follows.

# 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 C=0     0    0
ATOM=Te C=0     0   {uTe}
ATOM=Bi C=0     0   {uBi}


SITE_C denotes site positions expressed as fractional multiples of the conventional cell.

Structural data by specifying the lattice vectors and point group operations

We can supply equivalent information through the lattice vectors. This substitutes for the specification of the Bravais lattice R3M. Equivalent information is given by the lattice vectors and the point group operations. R3M has 12 rotations in all, which can be generated from the three generators   I R3Z MY. You don’t need to specify the generators, but since these operations tell blm the positions of symmetry-equivalent Te and Bi atoms, you must either give blm the generators of the group, or specify the positions of all five atoms in the unit cell. The init file below supplies the generators.

# Bi2Te3 from Wyckoff
% const a=4.3835 c=30.487 uTe=0.788 uBi=0.40
LATTICE
GENS='I R3Z MY'
UNITS=A
ALAT={a/sqrt(3)}
PLAT= 1.0 0.0 {c/a/sqrt(3)} -0.5 sqrt(3/4) {c/a/sqrt(3)} -0.5 -sqrt(3/4) {c/a/sqrt(3)}
SITE
ATOM=Te X=0     0     0
ATOM=Te X={uTe-1} {uTe-1} {uTe}
ATOM=Bi X={uBi-1} {uBi-1} {uBi}


The two init files look somewhat different but they generate the same input file.

Typically when the lattice is designated by a space group as Wyckoff does, the accompanying positions are expressed in terms of the conventional cell (C=). When specifying the lattice by the space group you must supply the lengths (e.g. A, or A and C) and angles (e.g. ALPHA) of the lattice vectors that are dictated by symmetry.

When instead the lattice is specified directly through lattice vectors PLAT, site positions are usually expressed in as multiples of the primitive cell (X=), as was done in the second init file, or in Cartesian coordinates (POS=). In this mode you must also supply the lattice constant ALAT (not the same as A, as you can see by comparing the two init files), and possibly the generators of the point group, as discussed above.

• 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.

This line:

% const a=4.3835 c=30.487 uTe=0.788 uBi=0.40


defines preprocessor variables which later appear in curly brackets as expressions.

• SPCGRP=R-3M tells blm that you are specifying the lattice by its space group.  R3M is entered as R-3M. You can also refer to this group by its number: SPCGRP=166.

• A={a} C={c}  are the two lengths of this hexagonal lattice. After parsing by the preprocessor, this line gets transformed into A=4.3835 C=30.487.

• UNITS=A  tells blm that lengths A and C are in Å units. By default blm uses atomic units.

• The SITE category operates in a tree structured syntax in much the same form as the ctrl file.

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.

As noted above, the basis vectors can be expressed in three forms:

  ATOM=Te C=0     0    0
ATOM=Te C=0     0    0.788
ATOM=Bi C=0     0    0.4

  ATOM=Te X= 0      0         0
ATOM=Te X=-0.212 -0.2120000 0.788
ATOM=Bi X= 0.400  0.400    -0.600

  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


Copy either of the init files above and create a simple skeleton input file

blm --express bi2te3


Note that blm writes the input file to actrl.ext

#### 2. Input file from init file, complex case

First obtain your input file, which for this example will be init.sbsei, which can be found in the /testing/ directory within your lm repository. Copy this file in to your working directory and run:

blm --gw --express --addes --fixpos:tol=1e-2 --scalp=1 --xshftx=0,0,-0.0398106/2 --wsitex init.sbsei


Where, for sbsei in particular, we use –gw to add GW related tags, –addes to add tags used for empty spheres later on and the rest to modify values in the input file as needed. We then do the general steps to complete our ctrl file:

cp actrl.sbsei ctrl.sbsei
lmfa sbsei
cp basp0.sbsei basp.sbsei
lmfa sbsei


Then copy the resulting GMAX (the higher, if there are two) output in to the relevant field in your ctrl.sbsei.

#### 3. Input file for magnetic ASA from init file

First obtain your input file, which for this example will be init.fept, which can be found in the /testing/ directory within your lm repository. Copy this file in to your working directory and run:

blm --mag --asa --gf --nk=10 --express fept


Specifically, the –mag and –asa switches to blm tell it to prepare for a spin polarized calculation and generate the input file for ASA. We then run the commands needed to finalize the ctrl file:

cp actrl.fept ctrl.fept
lmfa fept
cp basp0.fept basp.fept
lmfa fept


Then copy the resulting GMAX (the higher, if there are two) output in to the relevant field in your ctrl.fept.

#### 4. Input and/or site file from a CIF file

Crystallographic Information Files (CIF for short) is a standard text file format for representing crystallographic information, whose standards are set by the International Union of Crystallography. Questaal does not read CIF files directly, but makes use of the cif2cell utility. It is a very versatile tool, freely available on the web. cif2cell reads a CIF file and generates a file in a format the Questaal utilities can read. Questaal utilties can make either init file, or a site file as described here.

Example 1: Make ctrl.batio2 from cif2cell.batio3.

This example transforms a cif2cell file to a ctrl file. To make cif2cell.batio3 in the first place you would run cif2cell on an existing CIF file. Here we just copy the file from the Questaal respository.

Generation proceeds in a few easy steps:

 cp ~/lm/testing/cif2cell.batio3 .           ←  from the Questaal respository
cif2init cif2cell.batio3                    ←  makes file init
cp init init.batio3
blm --noshorten --wsitex batio3             ←  makes files actrl.batio3 and site.batio3
mv actrl.batio3 ctrl.batio3                 ←  Questaal input file name


Alternatively make only the site file:

 cif2site cif2cell.batio3                    ←  makes file site
mv site site.batio3			       ←  Questaal site file name


Example 2: Make ctrl.inas from a CIF file. You must install cif2cell before doing the first step.

1. Create cif2cell.inas from a CIF file for InAs. Note that the [111] axis points along z in this section.
Copy the contents of the box below (a cif file) into file InAs.cif.

# generated using pymatgen
data_InAs
_symmetry_space_group_name_H-M   'P 1'
_cell_length_a   4.28365288
_cell_length_b   4.28365288
_cell_length_c   4.28365288
_cell_angle_alpha   60.00000000
_cell_angle_beta   60.00000000
_cell_angle_gamma   60.00000000
_symmetry_Int_Tables_number   1
_chemical_formula_structural   InAs
_chemical_formula_sum   'In1 As1'
_cell_volume   55.581186778
_cell_formula_units_Z   1
loop_
_symmetry_equiv_pos_site_id
_symmetry_equiv_pos_as_xyz
1  'x, y, z'
loop_
_atom_site_type_symbol
_atom_site_label
_atom_site_symmetry_multiplicity
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
_atom_site_occupancy
In  In1  1  0.000000  0.000000  0.000000  1
As  As2  1  0.250000  0.250000  0.250000  1


Make cif2cell.inas

cif2cell InAs.cif > cif2cell.inas

2. Generation proceeds as in Example 1:

cif2init cif2cell.inas                      ←  makes file init
cp init init.inas
blm --noshorten --wsitex --ctrl=ctrl inas   ←  makes files ctrl.inas and site.inas


#### 5. Input file from POSCAR file

For this input file we need a POSCAR file. We will use the example POSCAR file for Zn3As2 found in /testing/POSCAR.zn3as2 in the lm repository. We copy this to our working directory and name it POSCAR.

We then convert the POSCAR file to an init file with the command:

poscar2init


Notice the lack of command line switches - this tool only takes files named POSCAR and does not differentiate whether they are POSCAR.[material]. We can then use the blm tool to translate this init.zn3as2 file to an actrl.zn3as2 file:

blm --express=0 zn3as2 --fixpos:tol=1e-6


And then follow steps shown in (1) or (2).

#### 6. Site file from POSCAR file

For this input file we need a POSCAR file. We will use the example POSCAR file for Zn3As2 found in /testing/POSCAR.zn3as2 in the lm repository. We copy this to our working directory and name it POSCAR.

We then convert the POSCAR file to a site file with the command:

poscar2site


Notice the lack of command line switches - this tool only takes files named POSCAR and does not differentiate whether they are POSCAR.[material]. This generates our site.zn3as2 file. From this you may have a use for the site file directly, or you can use a site file to generate a ctrl.zn3as2 file, (7) explains this.

#### 7. Input file from site file

This tutorial will look at the material fe2p. We will need a site file, which we shall find in /testing/sitein.fe2p in the lm repository. We copy this to our working directory and run:

blm fe2p --rdsite --express=1 --mag --findes --asa --omax=.00
`

Which generates an actrl.fe2p file, follow the steps in (2) to fully complete the ctrl.fe2p file.

#### 8. init file from site file

It may be more convenient to make an init file from a site file instead of making the ctrl file directly.

One additional step is needed to make the ctrl file (blm generates ctrl files from init files), but if the site file isn’t suitably structured (e.g. atom names do not correspond to standard species symbols), some intervention is necessary. In any case you may wish to add some flexibility to the init file.

The site2init utility makes this conversion; see the hyperlink for usage and command-line arguments.

### Other Resources

Numerous other tutorials construct ctrl files from structural data. See the introductory tutorials that carry out density-functional and Quasiparticle Self-consistent GW calculations of Si, or a more detailed LDA tutorial that uses PbTe as the material, and a LDA+QSGW tutorial for a magnetic metal, Fe. For PbTe there is a corresponding tutorial for the lm code which makes the Atomic Spheres Approximation, and for QSGW with additions of ladder diagrams for the response function, see this tutorial for LiF.

This tutorial uses blm to construct a ctrl file for the ASA Green’s function program lmgf, while this one autogenerates an input file for lattice relaxations in Se. For the most part, generation of the basis set and parameters controlling convergence are use default settings. A detailed exposition of the basis set and convergence parameters can be found in this tutorial.

A useful application of blm reading structural data from a site file is demonstrated in the superlattices tutorial.