Self-Consistent ASA calculation for PbTe

Command summary

The tutorial starts under the heading “Tutorial”; you can see a synopsis of the commands by clicking on the box below.

$ blm --express=0 --asa --wsitex --findes init.pbte
$ blm --h
$ cp actrl.pbte ctrl.pbte
$ blm --express=0 --asa --wsitex --addes init.pbte
$ cp actrl.pbte ctrl.pbte

... the following from section 2.2 are optional
$ lmchk ctrl.pbte
$ lmchk --findes --wsitex ctrl.pbte

$ lmstr ctrl.pbte
$ lm -vnit=0 ctrl.pbte
$ lm -vnit=20 ctrl.pbte
$ lmctl ctrl.pbte
$ cat log.pbte >> ctrl.pbte



Executables blm, lmchk, lmstr and lm are required and are assumed to be in your path. The last step (not essential for the tutorial) uses lmctl. The source code for all Questaal executables can be found here.


This tutorial consists of two main sections:

  1. Building a suitable input file for an ASA-LDA calculation
  2. Running a self consistent calculation

A detailed theoretical description of the ASA and its uses can be found here.

1.Building input file

Under normal atmospheric conditions PbTe crystallises in the rocksalt structure with lattice constant a=6.428 Å. To build an input file, the first step is to construct file init.ext (ext is replaced by a name of your choosing, usually related to the material being studied, pbte in this case). init.pbte will contain the structural information needed for the calculations demonstrated here. For PbTe it will look similar to the following. Copy the content of the box below into init.pbte:

    ALAT=6.427916  UNITS=A
        PLAT=    0.0000000    0.5000000    0.5000000
                 0.5000000    0.0000000    0.5000000
                 0.5000000    0.5000000    0.0000000
    ATOM=Pb   X=     0.0000000    0.0000000    0.0000000
    ATOM=Te   X=     0.5000000    0.5000000    0.5000000

File init.pbte shown above has two sections: LATTICE and SITE. The lattice section includes information regarding the lattice structure such as lattice constant (ALAT=) and its units (UNITS=, Å in this case) plus the primitive lattice translation vectors (PLAT=). The site section of the init file includes the basis information. In the case of PbTe there are two atoms, one Pb and one Te at the position indicated by “X=” (X= indicates positions as fractional multiples of the lattice vectors. Alternatively, you can supply the position with POS=, which specifies positions in Cartesian coordinates, in units of the lattice constant).

Now that init.pbte has been created, blm will create the ctrl file, which is the primary input file for the Questaal suite. Invoke it this way:

$ blm --express=0 --asa --wsitex --findes  init.pbte

This command will generate three new files which are site.pbte, actrl.pbte, and log.pbte. (The log file keeps track of key information generated by each program and will not be considered here.) The site file contains structural information in a form the Questaal package can read, and the ctrl file contains all other information needed to carry out a self-consistent calculation (LDA-ASA calculation in this case). The switches blm used have the following meanings:

--express=0  controls the brevity of the input file (smaller numbers make more verbose files with more information.
         It is worth experimenting with this switch to find which style of control file you are most confortable with.
--asa        tells blm that you are preparing to do an ASA calculation
--wsitex     causes blm to write site positions as fractional multiples of the lattice vectors.
--findes     causes blm to find empty spheres to fill the unit cell.

The last switch is necessary when using ASA, because the sum of sphere volumes must equal the cell volume. The ASA only works well when sites are closely packed. Close packing of open systems can be artificially accomplished by adding “empty” sites with Z=0.

blm has a number of other command-line switches; to see what they are, type:

$ blm --h

Now the only thing left to do is to rename actrl.pbte to ctrl.pbte, which is the name of the main input file.

$ cp actrl.pbte ctrl.pbte

blm writes to actrl, rather than ctrl, to avoid overwriting a file you may wish to keep.


  • Lines which begin with #* are comment lines and are ignored. (More generally, text following a **# in any line is ignored).
  • Lines beginning with % 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.
2.Building the input file

If you used blm as above to find the empty spheres (ES) you can skip section 2.1 below. It is included here to explain how to add empty spheres to an already existing ctrl file.

2.1 Empty Spheres

Begin by running blm with a slightly different set of switches:

$ blm --express=0 --asa --wsitex --addes init.pbte
$ cp actrl.pbte ctrl.pbte

--addes differs from --findes in that in the former case, blm prepares the input file for adding empty spheres, without actually adding them, while in the latter case blm addes them automatically.

To check ES and volume packing invoke:

$ lmchk ctrl.pbte

The full output can be viewed by clicking here (waiting for file storing system), however the important informations regarding the volume packing and overlap are towards the end of the standard output (stdout) and in this particular case it can be seen (in the case of no ES) in one line

Cell volume= 448.07190   Sum of sphere volumes= 301.06511 (0.67191)

Here the cell volume, sum of all sphere volumes and their ratio are presented, the latter of which has to be equal to 1 for an ASA calculation. Another important value is the overlap percentage, which in this case is given by

  OVMIN, 38 pairs:  fovl = 4.24366e-7   <ovlp> = 8.7%   max ovlp = 8.7%

This line tells us about the average and maximum sphere overlaps. Generally, for ASA the overlaps should be kept below 16% where possible. For full potential calculations generally 5% and below is safe. For GW calculations it should be below 2%. As the sum of sphere volumes is less than the cell volume, we have to add artificial atoms with Z=0 (“empty spheres”) to meet this requirement.

The appropiate space filling spheres can be found using lmchk by invoking:

$ lmchk --findes --wsitex ctrl.pbte

We have added two command-line switches: the first is to invoke the procedure to find the empty spheres and the second is to write the information into a new site file called essite.pbte. At the end of the stdout generated by lmchk you will see the following snippet:

 ... Final sphere sizes and packing fraction (2 new spheres)

 SCLWSR:  mode = 30  vol = 448.072 a.u.   Initial sphere packing = 81.3%  scaled to 100%
 constr omax1=  16.0  18.0  20.0 %    omax2=  40.0 100.0 100.0 %
 actual omax1=   8.7  12.1   0.0 %    omax2=  16.0  24.6   0.0 %

 spec  name        old rmax    new rmax     ratio
    1   Pb          3.300000    3.300000    1.000000
    2   Te          3.300000    3.300000    1.000000
    3   E           1.959808    2.598601    1.325947

which indicates two new empty spheres have been found, and the new sphere packing is 100%. The control file has to be changed to reflect the new basis. First, change:

  NBAS=2+{les?0:0}  NL=4  NSPEC=2+{les?0:0}


  NBAS=2+{les?2:0}  NL=4  NSPEC=2+{les?1:0}

Quantities in brackets {…} are algebraic expressions. In particular, {les?2:0} uses C-like syntax consisting of three expressions separated by ‘?’ and ‘:’. The first (les in this case) is evaluated. If les is nonzero, the result of the entire bracket is the result of the second expression (2 in this case) and otherwise the result of the third (0). In the line above, the contents of tag NBAS= can be interpreted as “if les>0 then NBAS=4 else NBAS=2”. Similarly the contents of NSPEC can be interpreted as “if les>0 NSPEC=3 else NSPEC=2”. “les” is a variable that is defined in the control file through the following line

  % const nit=10 les=1

Here we have also defined nit with value of 10. Finally, we have to pass the information about the empty sphere sites to the control file. We do this by commenting both instances of the line beginning FILE=site and uncommenting the line FILE=essite, as essite.pbte has the new appropiate information. Note: there are two instances of FILE=site : the first occurs in the STRUC category, where lattice information is read. The second occurs in the SITE category, where basis information is read. Be sure to comment/uncomment both instances.

The last step is to copy the new species information from file poses.pbte file to the SPEC category within the ctrl file, including the new empty spheres.

2.2 Self-consistency

Before a self consistent calculation can be performed the real-space structure constants have to be generated. They are made once, for a given structure, with a separate tool

$ lmstr ctrl.pbte

The penultimate step, is to generate a starting potential. In the ASA, the potential is determined through multipole moments Q0Q_0, Q1Q_1, Q2Q_2. For this we first change the nkabc variable within the control file to (nkabc=4, this variable represents the k-mesh density). Use your text editor to change:

% const nkabc=0


% const nkabc=4

Invoke lm executable with zero number of iterations as:

$ lm -vnit=0 ctrl.pbte

This command takes Q0Q_0, Q1Q_1, Q2Q_2 and makes a trial potential from it. You supply Q0Q_0, Q1Q_1, Q2Q_2; if you do not will take some simple default guesses. blm does not supply these values.

For a self consistent LDA-ASA calculation invoke lm with nit>0, e.g.

$ lm -vnit=20 ctrl.pbte

You should see “Jolly good show” at the end of the standard output will indicate if self-consistency has been achieved, which in this case it has.

Note: -vnit=20 does not directly set the number of iterations. This number is determined by token NIT in this line:

ITER  MIX=B2,b=.3,k=7  NIT={nit}  CONVC=1e-5

The preprocessor sees the the curly brackets ({nit}), treats the contents as an expression (a trivial one in this case) and substitutes the result (20) for {nit}.

As a final step, you can collect the self-consistent moments generated by lm and add them to the ctrl file. Type

$ lmctl ctrl.pbte

lmctl clears the log file, log.pbte, and overwrites it with linearization parameters P and moments Q0Q_0, Q1Q_1, Q2Q_2, in a form suitable for the ctrl file. Append log.pbte with, e.g.

$ cat log.pbte >> ctrl.pbte

In this way the ctrl file retains the essential information for the self-consistent density.

Edit This Page