The blm utility and the init file

This page documents the blm utility, the main utility for automatically generating Questaal’s main input file (the ctrl file), from structural information. Most files (including the init and ctrl files) have an extension appended which identifies a particular system. e.g. ctrl.si. Questaal appends the extension to most other files read or generated by the codes, for example the site file. File names can consist of letters and numbers, and the underscore character.

For example applications see the tutorials, a general purpose one and another tutorial written for the band code lmf.

In its default mode blm reads from an init file structural information (e.g. lattice constant and lattice vectors) and chemical information (atomic number, site position and possibly other information such as an estimate for the magnetic moment) and generates a ctrl file from it. By default blm splits off structural information into a site file, so that the starting input is given by two files, ctrl.ext and site.ext. (Some people prefer to put everything into the ctrl file, which you can do with the --express switch).

There are several ways to import structural information and automatically generate an init or site file readable by blm; see this tutorial, and also this tutorial written for the full-potential package.

How input is organized
Categories and tokens in the init file
How to use blm
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 ctrl 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 Bi₂Te₃ 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&‌deg;, e.g. trigonal systems
LATTICE_BETA takes 1 real argument. Required when angle between second and third axis is not 90&‌deg;, 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.

LATTICE_ORIGIN is optional. Many space groups, e.g. space group Pn-3 (No. 201), have two conventions for the choice of origin. blm assumes the first choice, but often data in the literature assumes the second. If it is the second choice include ORIGIN=2 in the LATTICE category. For an example, look at file init.lifeas in top-level-directory/testing/init.lifeas.

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

Warning: 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.
LMX takes 1 integer argument. Specifies the $\ell$ -cutoff for the basis.
MMOM takes up to 4 real arguments, one for each orbital quantum number $\ell$ corresponding to s, p, d, f partial waves. Trial magnetic moments for each $\ell$ .
P takes up to 4 real arguments, one for each orbital quantum number $\ell$ . 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 $\ell$ . 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 $\ell$ . Token and contents are transferred to the ctrl file and freeze log derivative parameters.
UH takes up to 4 arguments, one for each orbital quantum number $\ell$ . Hubbard parameters for LDA+U. Note: it may be more convenient to use the INCLUDE directive (see below)
JH takes up to 4 arguments, one for each orbital quantum number $\ell$ . Exchange parameters for LDA+U. Note: it may be more convenient to use the INCLUDE directive (see below)
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.
INCLUDE takes 1 string argument specifying a file name. Add contents of file to this species. It can include directives, but be sure to preserve indentation.
Example:
SPEC …
INCLUDE ldauparms
The contents of file ldauparms, e.g.
```
% ifdef ldau
             IDU= 0 0 0 112 UH= 0 0 0 0.66 JH= 0 0 0 0.099
% endif
```
will be read and appended to this SPEC_ATOM tag.

BZ category (optional)

FSMOM takes 1 real argument. Add tags for the fixed spin-moment method.

HAM category (optional)

REL takes 1 real argument. Specifies relativistic treatment.

How to use blm

The blm uility 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.

Table of Contents