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 simplest way to construct a ctrl file is to autogenerate it from an init file, init.ext. The latter contains mainly structural information, though some chemical-specific information can be supplied, e.g. a estimate for the magnetic moment of a species, which blm passes to the ctrl file. The init file structure is read by the blm utility; it and the structure of the init file are documented here. You can also import structural data from a Crystallographic Information File (CIF) as described below and in this tutorial. You can also important structural information from a VASP POSCAR file.

Numerous tutorials construct ctrl files from structural data. One example is given below. For other examples, 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.

Further description of the various routes to making input files can be found here.

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 described in this lmf tutorial for Pbte, which you may wish to go through first.

Executables blm, lmchk, lmfa, and lmf are required and are assumed to be in your path.

For conversion of cif or POSCAR files, you must install cif2cell utility (separately from the Questaal suite), and *cif2init, *cif2site, *poscar2init and *poscar2site must be in your path.

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.

Tutorial

1. Basic input file from init file

Cut and past the box below into init.bi2te3, or copy ~/lm/testing/init.bi2te3 into your working directory

# 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}


Create a simple skeleton input file

blm --express bi2te3


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 hyperlinke for usage and command-line arguments. $