Questaal Home
Navigation

The blm utility and the init file

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.

This document has a companion tutorial.

Table of Contents



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

HAM
        NSPIN=1 SO=0
	XCFUN=3
ITER    MIX=B2,b=.3,k=10  NIT=100  CONVC=1e-5

NSPIN is a token within HAM (we refer the entire tag as HAM_NSPIN), which takes an integer argument. SO and XCFUN are other tokens within HAM. Also shown are three tokens in the ITER category. ITER_MIX accepts a string as an argument (the string ends when a space is encountered); ITER_NIT and ITER_CONVC take integers and real numbers respectively.

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

Using 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.
  • LATTICE_B takes 1 real argument.
  • LATTICE_C takes 1 real argument.

Also depending on the symmetry, as many as three angles must be specified. (Cubic symmetries require no angles at all.) Names follow standard conventions:

  • LATTICE_ALPHA takes 1 real argument.
  • LATTICE_BETA takes 1 real argument.
  • LATTICE_GAMMA takes 1 real argument.
Using 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.

SITE category

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.

blm can be run in a variety of ways; see this tutorial. For example it can read data from site files. See this tutorial for a demonstration.

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.
Edit This Page