Generating Input Files

The purpose of this tutorial is to guide the user in how to use the blm utility to construct an input file for the Questaal suite of codes. There is a companion tutorial specifically written for constructing input files for the main DFT code, lmf.

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

This demonstrates different ways to feed structural information to blm:

by supplying the lattice and basis vectors by hand, demonstrated below for Bi₂Te₃
by importing from a Crystallographic Information File (AKA CIF file) demonstrated below for BaTiO₃
by importing from a VASP POSCAR file, demonstrated below for Zn₃As₂
You can also important structural information from a VASP POSCAR file.
by reading a site file in the Questaal format, as shown below

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

This tutorial uses only a few of blm’s many command line switches. See here for documentation of the full set of switches.

The last section of this tutorial is dedicated to cleaning up imprecise input files, where lattice or site positions are such that space group operations are only approximately satisfied.

1. Create an init file and build a simple ctrl file from it.

cat << END > init.bi2te3
# 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}
END

blm --nk,ins --simple bi2te3

2. ctrl file from init file, complex case

cp ~/lmf/testing/init.sbsei .
blm --brief --gw --addes --tidy~fixpos=1e-3 --scalp=1 --xshftx=0,0,-0.0398106/2 --wsitex init.sbsei

3. ctrl file from init file, magnetic ASA

cp ~/lmf/testing/init.fept .
blm --brief --mag --asa --gf --nk=10 --ctrl=ctrl fept

4. ctrl and/or site files from cif file

cp ~/lmf/testing/cif2cell.batio3 .
cif2init cif2cell.batio3
cp init init.batio3
cp ~/lmf/testing/cif2cell.batio3 .
cif2init cif2cell.batio3
cp init init.batio3

and

cp ~/lmf/testing/cif2cell.batio3 .
cif2site cif2cell.batio3
mv site site.batio3

5. ctrl file from POSCAR file

poscar2init  ~/lmf/testing/POSCAR.cuznsns > init.cuznsns
blm --brief init.cuznsns

6. site file from POSCAR file

poscar2site  ~/lmf/testing/POSCAR.cuznsns

7. ctrl file from a site file

cp ~/lmf/testing/sitein.fe2p .
blm fe2p --brief --rdsite --mag --findes~omaxi=-.1 --omax=.19 --asa --ctrl=ctrl

Preliminaries
Tutorial
Other Resources

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 the repository’s top-level directory is ~/lmf.

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.

Bi₂Te₃ and Bi₂Se₃ 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. Copy the box below into file init.bi2te3

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

Copy the box below into file init.bi2te3

# 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, i.e. as fractional multiples of the primitive lattice vectors (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.

Conventional cell:

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

as fractional multiples of the primitive lattice vectors:

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

in dimensionless Cartesian coordinates (to be scaled by ALAT, which is in atomic Rydberg units, the units Questaal uses (1 a.u. = 0.5291772 Å):

  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

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

blm --nk,ins --simple bi2te3

Note that blm writes the input file to actrl.ext.

Make a self-consistent density with

cp actrl.bi2te3 ctrl.bi2te3
lmfa bi2te3
lmf -vnkabc=3 ctrl.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 Questaal repository. Copy this file to your working directory and run:

cp ~/lmf/testing/init.sbsei .
blm --brief --gw --addes --tidy~fixpos=1e-3 --scalp=1 --xshftx=0,0,-0.0398106/2 --wsitex init.sbsei

This calculation sets up a ctrl file for a GW calculation (--gw) and, as can happen with an open system in the GW context, floating orbitals are sometimes needed to improve the accuracy. Here --addes add tags used for empty spheres later on and the rest to modify values in the input file as needed. Complete the setup with the following steps.

--brief : tells blm to create an input file (making use of symbolic variables) with moderate number of tags. Use --simple for a minimalist input file, and --brief=0 to create a verbose, “expert” version . --brief without modifiers flags blm to autogenerate a basis set (written to basp.sbsei) and to determine an appropriate plane wave cutoff (gmax) for this basis. (You can also specify gmax manually with --gmax=#.) The file is thus complete except no k mesh is specified. For blm to select a k mesh for you, add --nk,ins. This will make a rough estimate, and you should check whether it is sufficient. Using --brief is particularly convenient, but the user should be advised that removing the need for set parameters increases the risk that the setup has some limitations or difficulties.
--gw : tells blm this setup is intended for a GW calculation. Extra tags are added, and the basis is somewhat different.
--addes : tells blm to add extra tags in preparation for adding empty sites with floating orbitals. It is not necessary at the density-functional level, but makes a modest difference at the GW level.
--tidy~fixpos=1e-3 : the as-given init.sbsei was generated from a relaxed structure, assuming no symmetry operations.
The structure is quite close to a system with 8 point group operations instead of 4, and this switch fudges the positions a little so it will incorporate all 8 operations. For more details, see below.
--scalp=1 : shifts the balance between ALAT and PLAT so that the volume of PLAT is unity. This is not essential, but a construction with |PLAT| ~ 1 is better suited for hidden parameters built into Questaal.
--xshftx=0,0,-0.0398106/2 : site positions in the as-given init.sbsei contains an offset in the z coordinate relative to standard conventions. This does not affect the result, but site positions blm generates are cleaner; see site.sbsei.
--wsitex : causes blm to write site positions as fractional multiples of the primitive lattice vectors.

The full panoply of blm’s command line switches is documented here.

You can make a self-consistent density with

cp actrl.sbsei ctrl.sbsei
lmfa sbsei
lmf -vnkabc=3 ctrl.sbsei

Then copy the resulting GMAX (the higher, if there are two) output in to the relevant field in your ctrl.sbsei. Alternatively, run blm again with --gmax=#.

3. Input file for magnetic ASA from init file

As an example, use testing/init.fept in the Questaal repository.

cp ~/lmf/testing/init.fept .
blm --brief --mag --asa --gf --nk=10 --ctrl=ctrl fept

--brief : create an input file (one that has symbolic variables) with moderate number of tags.
--mag : prepare for a spin polarized calculation
--asa : this setup is intended for an ASA calculation.
--gf : this setup is intended for a Green’s function calculation within the ASA.
--nk=10 : use a k mesh of 10×10×10 divisions.
--ctrl=ctrl : name the input file ctrl.fept (instead of the default template actrl.ext).

The full panoply of blm’s command line switches is documented here.

Make a self-consistent density as follows:

lmstr fept
lm fept -vnit=0
lm fept -vnit=30

The magnetic moment should come out to about 3.2 μ_B, which is close to the experimental value.

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 utilities 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 repository.

Generation proceeds in a few easy steps:

cp ~/lmf/testing/cif2cell.batio3 .
cif2init cif2cell.batio3
cp init init.batio3
blm --brief --noshorten --wsitex --ctrl=ctrl batio3

Alternatively make only the site file:

cif2site cif2cell.batio3
mv site site.batio3

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

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

Generation proceeds as in Example 1:

cif2init cif2cell.inas; cp init init.inas
blm --brief --noshorten --wsitex --ctrl=ctrl inas

5. Input file from POSCAR file

For this input file we need a POSCAR file. We will use the example POSCAR file for CuZnSnS found in testing/POSCAR.cuznsns in the Questaal repository. Convert the POSCAR file to an init file with the command:

poscar2init  ~/lmf/testing/POSCAR.cuznsns > init.cuznsns

Proceed in in the usual way to make a ctrl file from an init file

blm --brief init.cuznsns

Note: POSCAR files often pick the lattice constant scaling to be 1 Å, so that the lattice vectors PLAT are in Å. The Questaal codes will work with this choice, but sometimes default parameters related to distances can be thrown off, especially if some of the lattice vectors are large. It is safer to choose lattice vectors with roughly unit volume, and put the length into ALAT. blm has a handy switch --scala to do it effortlessly. See this example.

Warning. POSCAR files are often very imprecise, in the sense that the lattice vectors (or site positions) are close to, but slightly misaligned with ones that have a higher symmetry. This is quite common when VASP is used for structural relaxation. Imprecision can confuse the symmetry finders in the Questaal package. There is a convenient --tidy switch that cleans up init files, which seems to work about 90% of the time, but there can be complications. See below.

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  ~/lmf/testing/POSCAR.cuznsns

This generates file site, without extensions. You can use it directly, or as input to blm to make a ctrl file, as explained in the next section.

7. Input file from site file

blm can build ctrl files from site files. As an example, use /testing/sitein.fe2p in the Questaal repository

cp ~/lmf/testing/sitein.fe2p .
blm fe2p --brief --rdsite --mag --findes~omaxi=-.1 --omax=.19 --asa --ctrl=ctrl

which generates a file ctrl.fe2p file, albeit without the k mesh specified.

This is a particularly challenging material for the ASA. The ASA requires space filling spheres, to get a reasonable charge density; this competes with the requirement that the sphere overlaps not be too large. Site positions in Fe2P are such that these two competing demands are difficult to balance. It has been done, however, with reasonable results. Adding artificial empty spheres is essential here.

Th set of switches, --findes~omaxi=-.1 --omax=.19, tells blm to initially shrink the spheres of Fe and P to an overlap of −10% for the purposes of locating placements for empty spheres, and later enlarge them again, so that the final sphere volumes (approximately) matches the unit cell volume.

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. blm can make a ctrl from either, but init files offer more flexibility.

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

Sometimes input are imprecise in the sense that the lattice vectors or site positions are close to, but slightly misaligned with ones that have a higher symmetry. (This is quite common in VASP POSCAR files, for example).

If you are willing to live without symmetry operations (for large cells this many be the case anyway), it is not a problem. But this imprecision can cause trouble for some of the symmetry finders in the Questaal package. Imprecision can appear in lattice vectors, in the site positions, or both.

The command line switch --tidy is aimed cleaning up input files to resolve these problem. There are in fact a multiplicity of ways the input can be imprecise and --tidy is an umbrella for a series of independent operations that make multiple kinds of adjustments. It is a shorthand for the following:
--fixlat,tol=1e-4 --fixpos,tol=1e-4 --ratx,tol=1e-5 --toleqp,tol=0. (equivalently --fixlat=1e-4 --fixpos=1e-4 --ratx=1e-5 --toleqp=0).

--fixlat adjusts lengths and angles between lattice vectors near 60, 90, or 120 degrees and scales the primitive lattice vectors with nearly equal lengths to render them equal.
--fixpos adjusts site positions close to but deviating from a space group operation, rendering them consistent with the operation
--ratx replaces elements in lattice vectors and site positions that are close to a rational number or the square root of one
--toleqp finds elements in lattice vectors PLAT with nearly equal size, and replaces them with their average value. Note that the default tolerance is 0, which turns off this operation

These can be performed independently, if desired.

Suggestion: Several Questaal codes will clean up the supplied input internally, but it is much better to make a clean ctrl file from the outset. Do this by invoking blm with --tidy[~…] or some set of the switches noted above. If you already have a ctrl file, use lmchk with --tidy and create a new site file with --wsite. For an instance where this two-step process was actually necessary, try (assuming ~/lmf/b/ is your build directory) ~/lmf/b/testing/test.blm 16 .

Warning: --tidy will use the (approximate) symmetry operations it finds to make small adjustments to either lattice vectors or site positions. Take care the the adjustments it makes are consistent with what you want. If you really want the configuration as given, run blm with the --nosym switch.

9.1 blm fails to find lattice vectors or has a strange number of symmetry operations

The Questaal codes can get confused when lattice vectors are supplied that approximately, but imprecisely, satisfy a set of point group operations.

You may be able to resolve the problem proceed without knowing details about what happened, simply by adding --tidy~tol=1e-4 to the command line when running a Questaal executable. Nevertheless --tidy is a bit fragile, and it may not work in all cases, and this section uses a number of examples to illustrate error messages that appear and the remedies blm uses to clean up the given lattice data.

Suggestion: Many Questaal codes, e.g. lmchk, that read the standard ctrl file accept the --tidy switch, making it possible for you to clean up the lattice vectors on the fly. But the inconsistency between the internal and file parameters can cause confusion. It’s better to clean the lattice and position vectors at the outset, as we do here with blm.

Below a number examples are given, and the reason blm fails is diagnosed. Problem-specific remedies are given after the examples; alternatively running the umbrella blm --tidy~tol=1e-4 will resolve all the problems automatically, although this not may be exactly what you want (see Example 7](/tutorial/importing_input/#example7)).

Example 1. This warning message may appear

Warning!  symmetry operations not consistent with Bravais lattice!

An instance of this case can be found in file testing/POSCAR.zn3as2 in the Questaal repository, which contains the the following lattice vectors

  -0.4072477    0.4072443    0.8174970
   0.4072477   -0.4072443    0.8174970
   0.4072477    0.4072443   -0.8174970

Generate file init.1 by invoking poscar2init ~/lmf/testing/POSCAR.zn3as2 > init.1 (assuming your repository is in the lmf directory) and invoke blm 1. You should see this output

 SYMLAT: Bravais system is indefinite with 14 symmetry operations.
         Warning!  symmetry operations not consistent with Bravais lattice!
 SYMCRY: crystal invariant under 7 symmetry operations for tol=1e-5

There is no crystal system with 14 point group operations. blm is getting confused because 0.4072477 and 0.4072443 are too similar, and the default lattice vector adjuster is not clever enough to work this out. If you make 0.4072477 and 0.4072443 the same number, blm will not get confused.

Example 2. This error message may appear

BRAVSY : inconsistent threefold rotations ... try running blm with --pr50 --quit=crysys

Copy the box below into file init.2:

LATTICE
   ALAT=1  UNITS=A
   PLAT= 3.7530946 -2.1668512 0.0000000
         3.7530946  2.1668512 0.0000000
        -2.5020266  0.0000000 27.2735377
SITE
     ATOM=Si   X=  0 0 0

Run blm 2 and the error message will appear. To troubleshoot this problem, run blm with extra command-line switches: blm 2 --quit=crysys --pr55. Now you should see:

 BRAVSY: Determine crystal system from rotations of the lattice
         r3z
         r2(sqrt(3)/2,1/1.999999,0) rejected  [possibly it should be accepted]
         r2y
         r2(sqrt(3)/2,-1/1.999999,0) rejected  [possibly it should be accepted]
 BRAVSY: 8 rotations found ... implies orthorhombic crystal system

If the lattice vectors are scaled by 1/2.1668512/2, PLAT becomes

866025   -0.500000    0.000000
866025    0.500000    0.000000
577342    0.000000    6.293357

which makes the symmetry apparent. To six decimal places, PLAT(1,1) is $\sqrt{3}/2$ . The quantity 0.577342 is $0.999986{\times}\sqrt{3}/3$ . As given, the symmetry finder locates a three-fold rotation about z, but only one two-fold rotation, where there should be three of them.

Example 3. This error message may appear

CVPLAT: could not calculate platcv.  Try running blm with --pr55 --quit=crysys

Copy the box below into file init.3:

LATTICE
   ALAT=1  UNITS=A
   PLAT=   5.356110     0.000000     0.000000
           0.000000     5.356120     0.000000
           0.000000     0.000000     5.356120
SITE
     ATOM=Si   X=  0 0 0

Run blm 3 and the error message will appear. The problem is clear: the three lattice vectors deviate from equal lengths by a factor 0.999998 or so. blm 3 --quit=crysys --pr55 shows that 48 group operations are found but that several of rotations would be missed if the tolerance were tight enough.

Example 4. In the init file given below, blm will generate a valid input file, but a sub-optimal one as it misses a symmetry operation, namely a twofold rotation around z. Copy the box below into file init.4:

LATTICE
   ALAT=1  UNITS=A
   PLAT=    8.3316670    0.0000000   -0.0003880
            0.0000000    4.2120930    0.0000000
            0.0000000    0.0000000    8.4174940
SITE
     ATOM=Si   X=  0 0 0

The problem will appear when you invoke blm 4 --quit=crysys --pr55. You should see

 BRAVSY: Determine crystal system from rotations of the lattice
         r2z rejected  [possibly it should be accepted]
         r2x rejected  [possibly it should be accepted]
         r2y

r2z is missed because of the small element -0.0003880 in the lattice vectors: if it were 0, all the symmetry operations would be found. The --ratx feature built into --tidy is designed to resolve this problem; see Point 4 in Remedies, below.

Example 5. blm will generate an input file without complaint from the init file given below, but the input file it generates causes the following subsequent codes using it (such as lmchk) to abort with the following error message:

 Exit -1 GRPGEN: too many elements

For an instance of this, copy the box below into file init.5:

LATTICE
        ALAT=1  UNITS=A
        PLAT=    3.1830599    0.0000000    0.0000000
                -1.5915300    2.7566108    0.0000000
                 0.0000027    0.0000109   20.2699680
SITE
     ATOM=Mo   X=     0.6666693    0.3333218    0.1678141
     ATOM=S    X=     0.3333189    0.6666461    0.0906781
     ATOM=S    X=     0.3333188    0.6666461    0.2449512

You will encounter this error message by doing the following:

blm 5 --ctrl=ctrl; lmchk 5

It is because of the small, nonzero components 0.0000027 and 0.0000109 in the third lattice vector, P₃, so that the angle between P₁ and P₃, and P₂ and P₃, to deviate slightly from 90°.

A detailed exposition of this example and its resolution is taken up in the next section. It deals with imprecision in both the lattice vectors and site positions.

Example 6. The init file given below deals with imprecision in both lattice vectors and site positions, Both kinds of imprecision can cause Questaal codes such as lmchk to abort with errors, at for different reasons. In this example, two kinds of errors appear

Exit -1 FIXPOS: positions incompatible with symgrp

and

SGROUP: ng greater than ngmx=3072

This example takes some explanation and is taken up in a later section. To follow the tutorial there, copy the box below into file init.6:

LATTICE
        ALAT=1  UNITS=A
        PLAT=    4.3042440    0.0000000    0.0000000
                 0.0000000    4.3042440    0.0000000
                 0.0000000    0.0000000   14.7955340
SITE
     ATOM=Pr   X=     0.0000000    0.0000000    0.9167210
     ATOM=Pr   X=     0.0000000    0.5000000    0.1667210
     ATOM=Pr   X=     0.5000000    0.5000000    0.4167210
     ATOM=Pr   X=     0.5000000    0.0000000    0.6666670

Example 7. In the init file for CeO₂ given below, slight deviations from cubic symmetry occur in both the lattice vectors and the site position. It is similar to Example 5.. Here we show how to set up a ctrl file and limit the symmetry operations to those corresponding to the actual input.

Copy the box below into file init.7:

LATTICE
        ALAT=1.8897259886
        PLAT=   5.356110     0.000000     0.000000
                0.000000     5.356120     0.000000
                0.000000     0.000000     5.356120
SITE
        ATOM=Ce X=      0.000000     0.000000     0.000000
        ATOM=Ce X=      0.000000     0.494930     0.494930
        ATOM=Ce X=      0.494930     0.000000     0.494930
        ATOM=Ce X=      0.494930     0.494930     0.000000
        ATOM=O X=       0.247460     0.247460     0.742390
        ATOM=O X=       0.247460     0.742390     0.742390
        ATOM=O X=       0.247460     0.742390     0.247460
        ATOM=O X=       0.247460     0.247460     0.247460
        ATOM=O X=       0.742390     0.247460     0.247460
        ATOM=O X=       0.742390     0.742390     0.247460
        ATOM=O X=       0.742390     0.742390     0.742390
        ATOM=O X=       0.742390     0.247460     0.742390

Like Example 3, blm 7 --quit=crysys --pr55 generates the message below and it is apparent that lattice vectors are similar enough to “almost” generate symmetry operations for a cubic system

CVPLAT: could not calculate platcv.  Try running blm with --pr55 --quit=crysys

blm 7 --tidy~tol=1e-4 will clean up the lattice vectors and render them consistent with cubic symmetry. With symmetry reductions from crystal system to Bravais lattice you should find

 GROUPG: the following are sufficient to generate the space group:
         r3d m(1,0,-1)
         r3d m(1,0,-1)
 MKSYM:  found 6 space group operations; adding inversion generated 12 ops

However, suppose you really do want the first lattice vector to be a different length than the others, and want to retain whatever symmetry is in the system with the vectors as given. If you do this:

blm init.7 --tidy~tol=1e-6 --ctrl=ctrl

blm will not render the crystal system consistent with cubic symmetry. The crystal system is found to be tetragonal and the space group gets reduced to

 GROUPG: 1 generator(s) were added to complete the group:
         i*i m(0,1,-1)
         i*i m(0,1,-1)

as it should. However, codes like lmchk that read this ctrl file will autogenerate the space group from scratch and run into the same difficulty. lmchk stops with this error message:

 GROUPG: the following are sufficient to generate the space group:
         r3d m(-1,0,1.0000019)
         r3d m(-1,0,1.0000019)
 Exit -1 GRPGEN: too many elements

This occurs because blm does not impose the space group it finds in the ctrl file.

To resolve the issue, you can do any of the following:

Include the same --tidy (or the --nosym) switch when running subsequent programs, e.g. lmchk 7 --tidy~tol=1e-6.
Add --savesym to the command line when running blm. This tells blm to uncomment the SYMOPS category, thus imposing the symmetry it found. Subsequent programs will use the symmetry operations in the file, rather than try to find them automatically. Thus blm init.7 --tidy~tol=1e-6 --ctrl=ctrl --savesym will generate file ctrl.7 that codes like lmchk can read without error.
Use your text editor and uncomment the SYMOPS category

Remedies

General Suggestion: Use the --scala switch when the volume contained in PLAT deviates significantly from unity. Often input files, e.g. data imported from VASP POSCAR files, use a lattice constant of 1 Å or 1 a.u.. Questaal can handle such cases but it is optimally designed so that the (dimensionless) volume of the the primitive lattice as given by PLAT is on the order of 1. (Questaal scales the dimensionless PLAT by ALAT, which is in atomic units.) Typically when has a volume of order 1, the elements of PLAT are between 0 and 1. Judicious use of --scala can shift the weight between ALAT and PLAT, and also make the structure of PLAT more transparent.

Example 2 is a case where the volume of PLAT deviates strongly from unity.
Invoking blm as blm '--scala=2.1668512*2' 2 --tidy both reduces the volume of PLAT and makes its structure more transparent.

Here are some automatic remedies to use with blm

The simplest solution is to invoke blm with --tidy, e.g. blm --tidy~tol=1e-4 ... --tidy invokes a panopoly of different patches and resolves most issues with slightly imprecise lattice vectors. Usually it will successfully patch inconsistencies with the lattice vectors and site positions (e.g. in the five examples above), but sometimes the ctrl and site it generates may be a bit inelegant.
Use --tidy in combination with the --scala switch. This is particularly useful in One function --tidy performs is to identify elements in PLAT close to rational numbers, and replace them with those numbers. The lattice vectors are easily recognizable as body centered tetragonal, but with 0.4072 replacing the usual 0.5. To make this function work, use --scala to shift some of the weight between PLAT and ALAT. When scaled both 0.4072477 and 0.4072443 fall near 1/2 and will be replaced by 1/2.
Invoking blm as blm --scala=0.4072477+0.4072443 --tidy yields PLAT with a transparent structure:
```
SYMLAT: Bravais system is tetragonal with 16 symmetry operations.
...
                Plat                     Conventional unit cell          As multiples of Plat
 -0.5000000  0.5000000  1.0036894   -0.5000000  0.5000000  1.0036894    1.0000  0.0000  0.0000
  0.5000000 -0.5000000  1.0036894    0.5000000 -0.5000000  1.0036894    0.0000  1.0000  0.0000
  0.5000000  0.5000000 -1.0036894    0.5000000  0.5000000 -1.0036894    0.0000  0.0000  1.0000
```

Use --tidy~equp[=#] tag. The equp modifier causes --tidy to look for elements in PLAT that are equal to within some tolerance and replace them with their average value. You don’t need any scaling in this case.
Running blm dat --tidy~equp yields

SYMLAT: Bravais system is tetragonal with 16 symmetry operations.
...
               Plat                     Conventional unit cell          As multiples of Plat
-0.4072460  0.4072460  0.8174970   -0.4072480  0.4072440  0.8174970    1.0000  0.0000  0.0000
 0.4072460 -0.4072460  0.8174970    0.4072480 -0.4072440  0.8174970    0.0000  1.0000  0.0000
 0.4072460  0.4072460 -0.8174970    0.4072480  0.4072440 -0.8174970    0.0000  0.0000  1.0000

Focus on specific elements within --tidy (which is an umbrella for several distinct operations). e.g. –tidy~ratx=# (equivalently, --ratx=#), –tidy~fixlat=# (equivalently, --fixlat=#). When running blm, soften tolerances in lattice adjustments, e.g. blm --tidy~fixlat=1e-3~ratx=1e-3 in Example 4, it will zero out the offending -0.0003880 in PLAT. –tidy~fixpos==# (equivalently, --fixpos=#) cleans up site positions and is discussed in more detail in the next section, by expanding on Example 5. The previous point noted the use of --tidy~equp[=#] (equivalently, --toleqp=#; note that by default this operation is not active.)
Adjust the init file by hand. If, in Example 1. 0.4072477 and 0.4072443 should be the same, simply edit the init file before running blm. In Example 2 you resolve inconsistencies by substituting −2.5020266/0.999986 for the x component of the third vector. In Example 7 make the lattice vectors the same length.
Invoke blm with --nosym, e.g. blm --nosym .... This generates a ctrl file that explicitly excludes symmetry operations.

9.2 lmchk finds too many group operations.

This section picks up on the following error message noted in Example 5 and is also discussed on the troubleshooting page:

 Exit -1 GRPGEN: too many elements

It can happen when the lattice vectors are not specified with enough precision. For an illustration, A common cause is that the lattice vectors are not specified with enough precision; to test it, look at Example 5 and also Example 7.

You will encounter this error message by doing the following:

blm 5 --ctrl=ctrl; lmchk 5

This is simple a case where --tidy will yield an acceptable input file: blm 5 --ctrl=ctrl --tidy; lmchk 5 will work.

To see in more detail, inspect PLAT. It is pretty likely that the x and y components of P3 should be zero, as they would do for a hexagonal lattice. Similarly the first and second components of the site positions should be 1/3 or 2/3. Here are the steps we recommend:

Questaal tends to have fewer difficulties when lattice vectors have a length on the order of unity. Use blm’s --scala switch to shift weight between ALAT and PLAT.
Use blm’s switch --fixlat, that will look for symmetry operations that transform PLAT in an “almost” invariant manner, and attempt to make PLAT consistent with those operations.
Use blm’s switch --fixpos switch, which does the same for the site positions.

Use blm’s switch --ratx switch. It is not essential, but it cleans up small deviations from rational numbers and simplifies the lattice vectors.

blm 5 --scala=3.1830599 --fixlat --fixpos --ratx

This renders the lattice vectors much closer to exact hexagonal symmetry (and also renders P1 and P2 with unit length)

            Plat                     Conventional unit cell          As multiples of Plat
 1.0000000  0.0000000  0.0000000    1.0000000  0.0000000  0.0000000    1.0000  0.0000  0.0000
-0.5000000  0.8660254  0.0000000   -0.5000000  0.8660254  0.0000000    0.0000  1.0000  0.0000
 0.0000000  0.0000000  6.3680762    0.0000000  0.0000021  6.3680762    0.0000  0.0000  1.0000

The site positions will also be internally consistent with hexagonal symmetry, but they will be slightly offset from their canonical ±1/3, 2/3 values, when expressed (as multiples of PLAT).

 site spec            pos (Cartesian coordinates)             pos (multiples of plat)
Mo       -0.49999161   0.28866517   1.06865297   -0.33333070   0.33332180   0.16781410
S         0.00000840   0.57734030   0.57744154    0.33333597   0.66665513   0.09067755
S         0.00000840   0.57734032   1.55986439    0.33333597   0.66665513   0.24495065

This can be fixed by adding a uniform translation. Run blm using -\xshftx= to translate the first and second elements to ±1/3 or to 2/3 (in units of P1 and P2). You can also use --ratx to ‘rationalize’ PLAT and site positions (that is, values close to a simple rational number are adjusted to that number). Write the site file with extra digits (--digits) to confirm their positions are given to machine precision. Confirm that lmchk now runs cleanly:

blm 5 --scala=3.1830599 --fixlat --fixpos --ratx --xshftx=1/3-0.33333597,2/3-0.66665513,0 --digits --wsitex --ctrl=ctrl
lmchk 5

Now the translation part of the group operations no longer have small components in x or y . The output of lmchk should yield

 GROUPG: the following are sufficient to generate the space group:
         i*r6z:(0,0,2.137306) r2y:(0,0,2.137306)

Note: These switches will not always resolve this issue, as the routine that tries to patch up the lattice vectors is not that sophisticated. See more discussion at the end of the next section (9.2).

9.3 Exit -1 SGROUP: ng greater than ngmx … or Exit -1 FIXPOS: positions incompatible with symgrp

This section expands on Example 6. In contrast to Example 5 (which is connected to imprecision in lattice vectors), the errors encountered here are related to imprecision in the position vectors. This one case where the bare --tidy is not enough to resolve the difficulty. To reproduce this tutorial, copy the box shown here into file init.6.

blm 6 --ctrl=ctrl --wsitex (or just blm 6) will proceed without complaint, but finds only four of the sixteen group operations that are likely intended.
On the other hand blm 6 --ctrl=ctrl --wsitex --tidy aborts with this message:

Exit -1 FIXPOS: positions incompatible with symgrp:  dpos=0.000804

It is telling you that the imprecision of the position vectors is 0.000804, which is larger than the default tolerance of --fixpos implicit in --tidy (1d-4). If you relax the tolerance of as a workaround, e.g. blm 6 --ctrl=ctrl --wsitex --fixpos=1e-3 blm aborts in a different place with this error message:

SGROUP: ng greater than ngmx=3072

This is because the fixpos algorithm adjusts one site to be compatible with one symmetry operation, only to mess up compatibility with another operation. You can resolve this by invoking --tidy~fixpos with a negative tolerance. The minus sign acts as a flag telling blm to loop of site adjustments iteratively until adjustments stop changing.
blm --ctrl=ctrl --wsitex --tidy~fixpos=-1e-3 will yield this output

 FIXPOS: shifted site positions by average 2.01e-4
 FIXPOS: shifted site positions by average 5.8e-5
 FIXPOS: shifted site positions by average 2.9e-5
 FIXPOS: shifted site positions by average 1.45e-5
 FIXPOS: shifted site positions by average 7.25e-6
 FIXPOS: shifted site positions by average 3.63e-6
 FIXPOS: shifted site positions by average 1.81e-6
 FIXPOS: shifted site positions by average 9.06e-7
 FIXPOS: shifted site positions by average 4.53e-7
 FIXPOS: shifted site positions by average 2.27e-7
 FIXPOS: shifted site positions by average 1.13e-7
 FIXPOS: shifted site positions by average 5.67e-8
 FIXPOS: shifted site positions by average 2.83e-8
 FIXPOS: shifted site positions by average 1.42e-8
 FIXPOS: shifted site positions by average 7.08e-9

Now lmchk 6 can find all 16 symops:

         r4z::(0,-1/2,1/4) i::(0,-1/2,0.083442)

The symmetry becomes more apparent if you put the first atom at the origin:

blm 6 --ctrl=ctrl  --wsitex --tidy~fixpos=-1e-3 --xshftx=0,0,0.083279-1

Now the site positions have a tidy form, as can be seen by inspecting site.6:

 Pr        0.0000000   0.0000000   0.0000000
 Pr        0.0000000   0.5000000   0.2500000
 Pr       -0.5000000  -0.5000000  -0.5000000
 Pr       -0.5000000   0.0000000  -0.2500000

Note: Occasionally blm is only partially successful at rationalizing the lattice and site positions. Sometimes you can further refine these positions once you have a ctrl file, using lmchk. This test provides an illustration (assuming ~/lmf/b/ is your build directory)

~/lmf/b/testing/test.blm 16

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.

Table of Contents