This guide documents the structure of the init file used to automatically build input files (ctrl files), and the blm utility, which reads the init file to create a ctrl file.
See also the companion tutorial to this document.
Table of Contents
- How input is organized
- Categories and tokens in the init file
- The blm utility
- Generating init file from a POSCAR file or a CIF file
How input is organized
File init.ext supplies structural data in order to auto-generate Questaal’s main input file, ctrl.ext. ext is a label you select such as batio3, typically indicating the contents of the file.
The init file syntax is essentially similar to that of the ctrl file: it is composed of categories and tokens which together make tags identifying the a particular element of data for input. Categories group tags together in themes; within a theme the token identifies a particular element of input.
Any text that begins in the first column starts a new category; the string (up to the space) names the category. Apart from that the input system is mostly free format. Arguments to tokens can be integers or real numbers, or strings. Thus in the following
LATTICE SPCGRP=R-3M A=4.3835 C=30.487 SITE ATOM=Te C=0 0 0
SPCGRP is a token within LATTICE (we refer the entire tag as LATTICE_SPCGRP), and it takes a string argument. A and C are other tokens within LATTICE, which accept real arguments. SITE marks the start of new category; shown here are tokens ATOM and C. Note that tokens C in the SITE and the LATTICE categories are distinct, because they belong to different categories.
The structure of categories and tokens is explained in more detail in the ctrl file documentation, and a precise (but less transparent) description of the init and ctrl file syntax can be found in this manual.
Input lines are passed through a preprocessor in the same way the ctrl is parsed.
Categories and tokens in the init file
LATTICE category (required)
This is the analog of the STRUC category in the input file. You specify lattice vectors in one of two ways, either by naming a space group, (LATTICE_SPCGRP) or explicitly through tag LATTICE_PLAT.
In either case atomic Rydberg units are assumed. You can tell blm to use Angstrom units by adding the tag LATTICE_UNITS=A (no arguments).
This tutorial shows how to use blm to build a ctrl file for Bi2Te3 both ways, specifying either the symmetry group or the lattice vectors.
Specifying the space group
LATTICE_SPCGRP takes 1 string argument. It should be either the space group symbol or space group number (1..230).
Note:: when you specify the basis (see below) blm will add any necessary sites to the basis vectors to make it compatible with the space group.
The lattice symmetry does not specify the size of the vectors. Depending on the symmetry there can be one, two, or three lattice parameters or length scales (cubic symmetry has one, monoclinic symmetry has three). You must supply one two three numbers for these lengths, depending on the lattice symmetry. Following standard conventions these numbers are called A, B and C. blm uses atomic Rydberg units, (or Angstrom if UNITS=A is present).
- LATTICE_A takes 1 real argument. Required for all lattices
- LATTICE_B takes 1 real argument. Required where b≠a, as in orthorhombic systems
- LATTICE_C takes 1 real argument. Required, when c≠a, as in tetragonal or hexagaonal systems
Also depending on the symmetry, as many as three angles must be specified. (Cubic, tetragaonal, and orthorhombic symmetries require no angles at all.) Names follow standard conventions:
- LATTICE_ALPHA takes 1 real argument. Required when angle between first and second axis is not 90°, e.g. trigonal systems
- LATTICE_BETA takes 1 real argument. Required when angle between second and third axis is not 90°, e.g. monoclinic systems
- LATTICE_GAMMA takes 1 real argument. Required in triclinic systems
Specifying the lattice vectors
LATTICE_PLAT specify the primitive lattice vectors. This tag takes 9 real elements, the first three specify the first lattice vector, the next three the second, and the last three the third. These vectors are dimensionless
LATTICE_ALAT scales the lattice vectors PLAT, in a.u. (or Angstrom if UNITS=A is present). It takes 1 real number.
LATTICE_GENS is optional. It supplies generators of the space group. It takes 1 string (if there is more than one generator, separate them by spaces and enclose the entire string in quotes). If you supply the generators, blm will add any necessary sites to the basis vectors to make it compatible with the space group.
This is the analog of the SITE category in the input file. It specifies the basis. Within the category information must be supplied for each site, e.g.
SITE ATOM=Mg POS= 0.0 0.0 0.0 ATOM=Li POS= 0.5 0.5 0.5
At least one site must be specified, with a species name (ATOM) followed by a position. The position can be specified in (dimensionless) Cartesian coordinates (POS), or as multiples of the lattice vectors, using X= instead of POS=. If the coordinates are specified in terms of multiples of the lattice vectors of the conventional unit cell, use C= instead of POS=.
Note:: blm versions ref 3a78597 and earlier used X= to represent positions in terms of the conventional unit cell, i.e. what is now C=. Thus older versions of blm may act differently, depending on the init file.
It is recommended, but not required, that you use standard symbols (Mg, Li) for the species labels. If you do not, you must include a SPEC category and specify the atomic number.
SPEC category (optional)
This category specifies additional species information, overriding default values or possible input from SITE category.
Within the category information must be supplied for each species, e.g.
SPEC ATOM=Cr MMOM=0,0,1 ATOM=Cr2 MMOM=0,0,-1
The ATOM token identifies the species: labels should coincide with labels in SITE category. Extra information for that particular species follow the ATOM token before another ATOM token.
In this instance (antiferromagnetic Cr) two kinds of Cr must be specified. Thus two distinct labels are needed. Extra information can be supplied (in this instance an estimate for the magnetic moment).
- Z takes 1 real argument. This is the atomic number. If it not supplied, Z is inferred from the label.
- R takes 1 real argument. This is the augmentation sphere radius.
- MMOM takes up to 4 real arguments, one for each orbital quantum number l. Magnetic moments by l
- P takes up to 4 real arguments, one for each orbital quantum number l. Token and contents are transferred to the ctrl file and specify the “continuously varying principal quantum number”.
- PZ takes up to 4 real arguments, one for each orbital quantum number l. Token and contents are transferred to the ctrl file and specify local orbitals.
- IDMOD takes up to 4 integer arguments, one for each orbital quantum number l. Token and contents are transferred to the ctrl file and freeze log derivative parameters.
- TOKEN takes 1 string argument Token and contents are transferred to the ctrl file and can be any additional tokens for this species you like.
The blm utility
The blm utility reads file init.ext and generates file actrl.ext. This file is a template ctrl file; often it is very close to a complete input file. Edit actrl.ext and copy it to ctrl.ext, as explained in many tutorials, such as the basic Si tutorial. It can accept many command line arguments that modify its generation of the ctrl file.
Generating init file from a POSCAR file or a CIF file
The VASP POSCAR file contains structural data, and there is a utility, poscar2init that will translate structural information in a POSCAR file to an init file. See this tutorial and also Additional exercises in this tutorial.
You can also import Crystallographic Information Files (CIF files) as explained in this tutorial.