# Generating Input Files

The purpose of this tutorial is to guide the user in constructing 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:

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

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 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 ~/lm.

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.

Bi2Te3 and Bi2Se3 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. Enter this information into file init.ext as follows.

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

# 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 (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:

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

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

  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


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

blm --express bi2te3


Note that blm writes the input file to actrl.ext

#### 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 ~/lm/testing/init.sbsei .
blm --gw --express --addes --fixpos:tol=1e-2 --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.

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. 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 ~/lm/testing/init.fept .
blm --mag --asa --gf --nk=10 --express fept --ctrl=ctrl


The --mag and --asa switches tell blm to prepare for a spin polarized calculation and generate the input file for ASA.

#### 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 CuZnSnS found in testing/POSCAR.cuznsns in the Questaal repository. Convert the POSCAR file to an init file with the command:

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


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

blm 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  ~/lm/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 ~/lm/testing/sitein.fe2p .
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. 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.

#### 9. Cleaning up imprecision in input files

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 troubles for some of the symmetry finders in the Questaal package.

Quite often the command line switch --tidy will resolve the problem. --tidy is actually a shorthand for --fixlat,tol=1e-4 --fixpos,tol=1e-4 --ratx,tol=1e-5. These switches are explained in more detail below.

Warning: --tidy can make small adjustments to lattice vectors, site positions, or space group operations. Take care the the adjustments it makes are consistent with what you want.

##### 9.1 lmchk finds too many group operations.
 Exit -1 GRPGEN: too many elements


This problem is discussed in the troubleshooting page.

A common cause is that the lattice vectors are not specified with enough precision. For an illustration, copy the box below into file init.mos2

LATTICE
#       SPCGRP=
ALAT=1  UNITS=A
PLAT=    3.1830599    0.0000000    0.0000000     &larr; P1
-1.5915300    2.7566108    0.0000000     &larr; P2
0.0000027    0.0000109   20.2699680     &larr; P3
# 3 atoms, 2 species
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 enounter this error message by doing the following:

blm mos2 --ctrl=ctrl
lmchk mos2


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

Nevertheless --tidy is a bit fragile, so we explain in more detail here what the swtich does, and a offer few tips for making a more robust input file.

Inspecting 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:

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

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

3. Use blm’s switch --fixpos switch, which does the same for the site positions.

blm mos2 --scala=3.1830599 --fixlat --fixpos


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.0000001  6.3680762    0.0000008  0.0000034  6.3680762    0.0000  0.0000  1.0000


The position vectors will also be internally consistent with hexagonal symmetry, but they will be translated relative to their canonical ±1/3, 2/3 values (as multiples of PLAT).

 site spec            pos (Cartesian coordinates)             pos (multiples of plat)
1  Mo       -0.49999161   0.28866517   1.06865297   -0.33333070   0.33332180   0.16781410
2  S         0.00000840   0.57734030   0.57744154    0.33333597   0.66665513   0.09067755
3  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 mos2 --scala=3.1830599 --fixlat --fixpos --xshftx=1/3-0.33333597,2/3-0.66665513,0 --ratx=1e-5 --digits --wsitex --ctrl=ctrl
lmchk mos2


Note that the translation part of the group operations no longer have small components in x or y :

 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.2 Exit -1 SGROUP: ng greater than ngmx … or Exit -1 FIXPOS: positions incompatible with symgrp

This problem is similar to the previous one (which is connected to imprecision in lattice vectors), but these messages are related to imprecision in the position vectors. Usually the --tidy switch fixes the problems, but sometimes the bare switch is not enough. To illustrate such a case copy the box below into file init.dat :

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


The command blm (or more informatively, blm --ctrl=ctrl --wsitex) will proceed without complaint, but finds only four of the sixteeen group operations that are likely intended.
On the other hand blm --ctrl=ctrl --wsitex --tidy yields:

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


If you relax the tolerance of --fixpos as a workaround, e.g. blm --ctrl=ctrl --wsitex --tidy~fixpos=1e-3 this error message appears:

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 dat 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 --ctrl=ctrl  --wsitex --tidy~fixpos=-1e-3 --xshftx=0,0,-0.9167210


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

 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 ctrl, using lmchk. This test provides an illustration:

testing/test.blm 16

##### 9.3 Warning! symmetry operations not consistent with Bravais lattice!

This warning message is usually associated with lattice vectors that approximately, but imprecisely, satisfy a set of point group operations. Such an anomalous case is generated from the following lattice vectors

  -0.407248   0.407244   0.817497
0.407248  -0.407244   0.817497
0.407248   0.407244  -0.817497


It yields

 SYMLAT: Bravais system is indefinite with 14 symmetry operations.
Warning!  symmetry operations not consistent with Bravais lattice!


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

blm has the following automatic remedies. Note that other codes (e.g. lmchk), reading the standard ctrl also can use these switches, but it’s better to do it at an early stage, i.e. when blm makes the ctrl and site files, so blm can adjust site positions as well.

1. Use the --tidy switch, which replaces numbers close to rational fractions with those fractions. To make it work, use this switch, you must also scale the shift some of the weight between PLAT and ALAT, so that 0.407248 and 0.407244 are both near 1/2. This combination of switches blm --scala=0.4072477+0.4072443 --tidy yields
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

1. Use --tidy~equp[=#] tag. This causes blm to substitute elements in PLAT (within tolerance #) with their average value. You don’t need any scaling in this case. This option works only in special cases; this is one instance. Doing blm zn3as2 --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

2. In the more likely case 0.407248 and 0.407244 should be the same, simply edit the init file before running blm (alternatively the ctrl file before running other codes). But as noted earlier, it is better to modify the init file, either by hand or let blm do it automatically.

3. If you really require these lattice vectors, you can avoid confusing the codes by invoking --nosym. In particular blm --nosym add a line specifying no symmetry operations in the ctrl file, so you don’t need to use this switch when running codes that read the ctrl file, like lmf.

For an example, look at testing/POSCAR.zn3as2 in the Questaal repository. You can make an init file that exhibits these issues with poscar2site ~/lm/testing/POSCAR.zn3as2.

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

One of the following cryptic error messages may occur:

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


or

 Exit -1  CVPLAT: could not calculate platcv


Here is an example:

    PLAT= 3.7530946 -2.1668512 0.0000000
3.7530946  2.1668512 0.0000000
-2.5020266  0.0000000 27.2735377


Scaling the lattice vectors by 1/2.1668512/2, PLAT becomes

    0.866025   -0.500000    0.000000
0.866025    0.500000    0.000000
0.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.

To troubleshoot this problem, try running blm adding commnd-line switches --quit=crysys --pr55. In this case 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


bravsy.f is naive: it associates 8 symmetry operations with the orthorhombic crystal system, but does not check that the set of operations found is internally consistent.

All three two-fold rotations should be found. To fix this, you have the following choices.

Fix precision of lattice vectors
If you substitute −2.5020266/0.999986 for the x component of the third vector, blm will find all three two-fold rotations, and correctly determine that this is a rhombohedral crystal system.
Use the --ratx switch
When running blm, soften tolerances in lattice adjustments, e.g. blm --tidy~fixlat=1e-3~ratx=1e-3. It will zero out the offending -0.0003880 for the following set of lattice vectors, for example:
      PLAT=    8.3316670    0.0000000   -0.0003880
0.0000000    4.2120930    0.0000000
0.0000000    0.0000000    8.4174940


Confirm this with blm --tidy~fixlat=1e-3~ratx=1e-3 --quit=crysys --pr55` .

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