Questaal Home

Including Augmented Plane Waves in the lmf Basis Set

This tutorial describes the PMT method, which enhances Questaal’s standard basis set of augmented smoothed Hankel functions with Augmented Plane Waves.

Table of Contents

Command Summary

These commands are sufficient to run the tutorial. They may not work in all environments, especially if they make use of tools like awk which can differ between MacOS and Linux. If you want more information or are running in to problems, read the tutorial in full.


This tutorial assumes you have cloned and built the lm repository (located here). For the purpose of demonstration, ~/lmf will refer to the location of the cloned repository (source directory), and ~/lmf/build is the directory where the codes are built.


Adding APWs to lmf is exemplified in these test cases

$ ~/lmf/build/fp/test/test.fp srtio3
$ ~/lmf/build/fp/test/test.fp cu
$ ~/lmf/build/fp/test/test.fp v 1

They are useful as test cases. The latter illustrates a pure APW basis, without atom centered functions at all. Should you want a more in depth look, these are good places to start. We will use Cu as a base and explain how add APWs.

For the PMT method, APW-specific tokens must be added to the HAM. They are :

  • PWMODE tells lmf how to add APWs to the basis. For our example we will use 11 (default=0, meaning no APWs). See the link above for a detailed description of the options.
  • PWEMAX is the upper cutoff energy in Rydbergs, only G-vectors whose energy falls below this value will be included.
  • PWEMIN is the lower cutoff energy. In practice, there seems little advantage to choosing PWEMIN much larger than 0.
  • OVEPS, if its value is positive, tells lmf to diagonalize the overlap matrix and eliminate the subspace which has eigenvalues smaller than #. This is necessary, as the MTO and APW basis span nearly the same Hilbert space. Adding many APWs can cause the overlap matrix to become nearly singular (or even negative)and thus unstable. A good value for OVEPS is 1E-7.

The rest of the tutorial focuses on elemental Cu. Copy and to your working directory.

cp ~/lmf/fp/test/ ~/lmf/fp/test/ .

Tutorials for and documentation on these files can be found here and here respectively.

We begin with the standard atom-centered basis of smooth Hankels. As with all lmf simulations, we must run lmfa to generate the free atom densities

lmfa --no-iactiv cu -vnk=8 -vbigbas=f
lmf  --no-iactiv cu -vnk=8 -vbigbas=f > out.lmto
lmf  --no-iactiv cu -vnk=8 -vbigbas=f --band~fn=syml
cp bnds.lmto

This runs lmfa to make, lmf, to self-consistency. -vbigbas=f is a variable the preprocessor uses to decide on the size of basis. In this case it uses small basis of a single set of spd orbitals with envelope functions, and another set of spd local orbitals (18 orbitals in all). -vnk=8 sets BZ_NKABC telling it to use 8 divisions in each of the three directions of the reciprocal lattice vectors. The energy bands are generated and copied to bnds.lmto. --band and tells lmf to generate energy bands on symmetry lines; the switch is documented here.

We next run lmf adding the PMT basis as follows:

lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=11 -voveps=1d-7 --rs=1,0 -vnit=1 > out.pmt
lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=11 -voveps=1d-7 --rs=1,0 -vnit=1 --band:fn=syml
cp bnds.pmt

-vpwmode=11 sets HAM_PWMODE to 11, tells lmf to add to the atom-centered smoothed Hankel envelope functions a basis of Augmented Plane Waves. HAM_PWMODE=11 makes the APW basis k dependent (basis functions are ), but it is better than HAM_PWMODE=1 (basis functions are ) because the basis is consistent with the crystal symmetry. One complication HAM_PWMODE=11 has is that the hamiltonian rank also becomes k dependent.

--rs=1,0 -vnit=1 is added so that lmf makes a single band pass without disturbing the density stored in In out.pmt you can find the following

 suham:  q-dependent PW basis with  Emin = 1 < E < 3.
         Est. min,max PW dimension = 3,10.  Use npwpad = 3 => ndham = 31

The hamiltonian rank increases by between 3 and 10, depending on the k point.

-voveps=1d-7 causes lmf to discard eigenstates in the hilbert space whose overlap is smaller than the given value, for reasons described above. After the band pass you can see this line in out.pmt:

 BNDFP: max reduction in hilbert space = 3; smallest dimension = 22

There would have been no reduction if OVEPS were 0.

Note that this calculation is not self-consistent. In out.pmt you can find

 mixrho:  sought 3 iter, 2178 elts from file mixm; read 0.  RMS DQ=5.55e-4

The change in density from the addition of plane waves is quite modest. Compare the total energies for the two: use tail -2 You should see:

c nk=8 bigbas=0 ehf=-.3263089 ehk=-.3263086
x nk=8 bigbas=0 pwmode=11 oveps=1e-7 nit=1 ehf=-.3279655 ehk=-.3279538

The PMT basis deepens the total energy by about 1.6 mRy. This small change is not surprising: Cu is a close packed system and the atom-centered basis is well suited to it.

The first lmf instruction make a single band pass. It sets the Fermi level for that basis (stored in so it is known when the energy bands are generated by the next lmf instruction.

We are now ready to compare bnds.lmto and bnds.pmt. Instructions to make a postscript figure using Questaal’s plbnds utility and fplot utility are provided below, though you may want to make this comparison with graphics software you prefer.

plbnds -range=-13,10 -fplot~scl=.7,.8~sh~ts=.5 -ef=0 -scl=13.6 -lbl=L,G,X,W,G,K -dat=pmt bnds.pmt
plbnds -range=-13,10 -fplot~scl=.7,.8~sh~ts=.5 -ef=0 -scl=13.6 -lbl=L,G,X,W,G,K -dat=lmto bnds.lmto
awk 'BEGIN {print "%char0 lta=2,bold=3,col=1,0,0"} {if ($1 == "-colsy") {sub("lmto","green");sub("green","pmt");sub("lta","ltb");print;sub("pmt","lmto");sub("ltb","lta");print} else {print}}' plot.plbnds > plot.plbnds2
fplot -f plot.plbnds2

This makes a figure, which you can view with your favorite postscript viewer, e.g. gs The difference in the two energy band structures is scarcely detectable. If you draw the bands over a wider window (e.g. -range=-13,40) you can see the differences become pronounced starting at EF + 30 eV.

Additional Exercises

  1. The PMT basis also changes the charge density. To see its effect on the band structure, make the density self-consistent in the PMT basis. This is done in the instructions below: the density is written to to avoid overwriting the original file.
    rm -f
    lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=11 -voveps=1d-7 --rs=1,2
    lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=11 -voveps=1d-7 --rs=2,0 --band:fn=syml

Self-consistency makes the Harris Foulkes and Kohn-Sham energies equal, as it should do. (If they are not nearly equal, something has gone wrong.) The Harris Foulkes energy changed slightly from -.3278912 to -.3278508.

Compare the bands:

plbnds -range=-13,10 -fplot~scl=.7,.8~sh~ts=.5 -ef=0 -scl=13.6 -lbl=L,G,X,W,G,K -dat=sc
plbnds -range=-13,10 -fplot~scl=.7,.8~sh~ts=.5 -ef=0 -scl=13.6 -lbl=L,G,X,W,G,K -dat=pmt bnds.pmt
awk 'BEGIN {print "%char0 lta=2,bold=3,col=1,0,0"} {if ($1 == "-colsy") {sub("pmt","green");sub("green","sc");sub("lta","ltb");print;sub("sc","pmt");sub("ltb","lta");print} else {print}}' plot.plbnds > plot.plbnds2
fplot -f plot.plbnds2

The difference is scarcely detectable, even up to EF + 40 eV.

  1. You can also use a pure APW basis, without any atom-centered MTO’s. This switch is activated when HAM_PWMODE=12. For a self-consistent calcualtion in pure APW basis, with associated band structure, do the following
    rm -f
    lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=12 -vpwemin=0 -vpwemax=10 -voveps=1e-7 --rs=1,2 -vnit=20 > out.apw
    lmf  --no-iactiv cu -vnk=8 -vbigbas=f -vpwmode=12 -vpwemin=0 -vpwemax=10 -voveps=1e-7 --rs=2 -vnit=20 --band:fn=syml
    cp bnds.apw

    Draw a figure with pure APW, PMT, and pure LMTO bands superposed, as follows:

    plbnds -range=-10,12 -fplot~scl=.7,.7~sh -ef=0 -scl=13.6 --nocol -dat=green apw
    plbnds -range=-10,12 -fplot~scl=.7,.7~sh -ef=0 -scl=13.6 --nocol -dat=red  pmt
    plbnds -range=-10,12 -fplot~scl=.7,.7~sh -ef=0 -scl=13.6 --nocol -dat=blue lmto
    plbnds -range=-10,12 -fplot~scl=.7,.7~sh -ef=0 -scl=13.6 --nocol -lbl=L,G,X,W,G lmto
    mv plot.plbnds plot.plbnds~
    echo "% char0 colr=1,bold=4,clip=1,col=.3,1,.2" >>plot.plbnds
    echo "% char0 colb=3,bold=4,clip=1,col=1,.2,.3" >>plot.plbnds
    echo "% char0 colg=2,bold=4,clip=1,col=.8,.7,.8" >>plot.plbnds
    awk '{if ($1 == "-colsy") {sub("-qr","-lt {colg} -qr");sub("dat","green");print;sub("green","red");sub("colg","colr");print;sub("red","blue");sub("colr","colb");print} else {print}}' plot.plbnds~ >> plot.plbnds
    fplot -f plot.plbnds

    It should show that within a Ry or so of the Fermi level, the three methods yield nearly identical electronic structure.

Note: APWs have more “wiggles” than LMTOs do and require a higher cutoff KMXA in their expansion in polynomials PkL.
It has been found empirically that larger values of KMXA require somewhat smaller values of the radial parameter RMXA.

Questions or Comments

This thread is intended for questions or comments about the tutorial page 'Including Augmented Plane Waves in the lmf Basis Set' located here.

Feel free to ask questions (or answer!) about the physics found on the page, to get help with the Questaal commands listed or for guidance on how to use Questaal for a similar application that the page did not cover.

For questions about physics or Questaal usage not related to this page, have a look around the site as you may find someone has already asked your question or you can post it yourself in the general questions category.

If you spot a bug, an error or have a suggestion for improvement, please use the GitLab issues page instead.

Anyone is welcome to contribute!