The plbnds utility


plbnds is designed to generate data to make figures of energy bands along a specified symmetry lines. Questaal codes generate energy bands when the --band command-line argument is invoked, in the (default) symmetry line mode. Usually Questaal codes write bands to bnds.ext. This page contains files for symmetry lines for any crystal structure here

plbnds can make postscript files directly, but this tool is is mostly used to set up render bnds.ext into files with a simple, easy-to-read format. plbnds also makes a script for the fplot graphics tool that will make the postscript file. You can tailor the figure by editing the script file; alternatively the simple data format is suitable for use by any graphics package.


Executables plbnds and fplot are required and are assumed to be in your path. You will also need a postscript viewer. This document assumes you are using the generic apple-style open command to view postscript files.

Table of Contents

1. Introduction

Energy bands provide a great deal of information, and the Questaal codes provide a fair amount of flexibility in generating them. Drawing bands with color weights is a particularly useful feature, as shown in Section 2.

Questaal lmf, lm, and tbe can generate energy bands along symmetry lines you specify. They share a common input and output format. You must choose the symmetry lines yourself, but prepackaged symmetry line files are available that greatly facilitate the selection and labelling of lines. Bands are written to file bnds.ext, or bbnds.ext if --band~bin is used. This file is not written in a friendly format; but it is often the case that you need only a subset of the bands or to provide extra information such as data for color weights.

plbnds may be used to make postscript files of bands directly, without other software. It is quick and dirty, andthere is no easy way to modify the figure.

Alternatively plbnds can efficiently convert data in bnds.ext to a simpler format. In this mode (plbnds --fplot), data in bnds.ext is converted to a friendly format useful for a variety of circumstances. A separate file bndn.ext is created for each panel, one panel per symmetry line. bndn.ext is tailored to how many bands are in an energy window of interest, whether color weights are present, and so on. Together with the data files, a script plot.plbnds is automatically created designed for fplot. You can use fplot directly to make the figure, or make it with your favorite graphics package.

plbnds will provide a synopsis of its usage by typing

$ plbnds --h

Section 2 gives you an intuitive feel of how plbnds operates by working through an example (the energy bands of Co).

Section 3 is an operations manual.

See Table of Contents

2. Examples

Copy an already prepared bands file for Co, to your working directory. It contains energy bands connecting the symmetry lines M, Γ, A, L, Γ, K (5 panels). Bands were computed in the LDA with spin-orbit coupling; thus both spin-up and spin-down bands are present.

The first line of the file

36  -0.02136     2  col= 5:9,14:18  col2= 23:27,32:36

contains essential information about the contents. It says that:

  • the file contains 36 bands
  • the Fermi level is -0.02136 Ry
  • the file contains two sets of color weights

Strings col= and following are not used; they are there for record-keeping.

The structure of the entire file is documented here.

Example 1

Enter the following to make and view the postscript file:

$ echo -0.8,0.6,10,15 | plbnds -lbl=M,G,A,L,G,K
$ open


  • The energy bands are plotted in an energy window -0.8,0.6 Ry, in 5 panels.
  • Arguments 10,15 specify the width and height of the entire figure (in cm, approximately).
  • The symmetry labels M, Γ, A, L, Γ, K, were extracted from -lbl=M,G,A,L,G,K. (G is turned into Γ.)
  • Energy bands are in Ry.
  • The Fermi level is drawn as a dashed line at -0.02136 Ry.
  • Bands are plotted as fat dots at the points where they are generated.
  • It is easy to distinguish the dense tangle of flat d bands approximately between -0.3 and +0.1 Ry. The sp bands are highly dispersive and approximately quadratic; see Example 3 for more details.
Example 2

For a better and more modifiable figure, run plbnds again with:

$ echo -10,8 / | plbnds -fplot -ef=0 -scl=13.6 -nocol -lbl=M,G,A,L,G,K

 plbnds : bands file contains two sets of color weights
 plbnds: 36 bands  fermi=-0.02136  scaled by 13.6  shifted to 0
 panel 1  nq=25  ebot=-9.232224  etop=33.866176  delta q=0.577353
 panel 2  nq=21  ebot=-9.232224  etop=33.235136  delta q=0.30619
 panel 3  nq=41  ebot=-7.005904  etop=29.214976  delta q=0.57735
 panel 4  nq=45  ebot=-9.232224  etop=33.503056  delta q=0.653518
 panel 5  nq=41  ebot=-9.232224  etop=33.603696  delta q=0.666665
 nq=173  npan=5  emin=-9.232224  ef=0  emax=33.866176  sum dq=2.781075
 emin, emax, width(cm), height(cm) ?
 write file bnd1.dat, bands 1 - 26
 write file bnd2.dat, bands 1 - 26
 write file bnd3.dat, bands 1 - 26
 write file bnd4.dat, bands 1 - 26
 write file bnd5.dat, bands 1 - 26
  ... to plot, invoke:
  fplot -disp -f plot.plbnds

The new switches indicate the following:

  • -fplot tells plbnds to generate data files for each of the five panels, and also a script for the fplot tool.
    The fplot script is written to a file, plot.plbnds.
    The five panels are written to files (bnd[1-5].dat) (see standard output). They take a standard Questaal format, which is easily read by other packages.
    The first column is a fractional distance along the symmetry line (0 for starting point, 1 for ending point).
    The remaining 26 columns comprise energy bands in the window (-10,8) eV.
  • -ef=0 tells plbnds to shift the bands by a constant so the Fermi energy falls at 0.
    Note: in an infinite periodic system the energy zero is ill defined; it can be chosen arbitrarily.
  • -scl=13.6 scales the energy bands by this factor, converting the raw bands (in Ry) to eV.
  • -nocol tells plbnds to ignore information about color weights.

The energy window is now -10,8 eV. The last two arguments from stdin (formerly 10,15) are not used in this mode since plbnds makes no figure.

Make and view a postscript file with

$ fplot -f plot.plbnds
$ open

This figure is much closer to publication quality. You can of course customize the figure by editing plot.plbnds. To interpret and customize the script, see the fplot manual.

Example 3

This example illustrates a very useful feature of the Questaal band plotting capabilities. It uses two color weights to distinguish spin-up and spin-down bands. The first color selects out the majority bands of d character, the second the minority d bands.

Consider orbital component i of band n. Its wave function has eigenvector element zin. The wave function is normalized, and so

izni1zin=1\sum_i z^{-1}_{ni} z_{in} = 1

The sum runs over all of the orbitals in the basis. By “decomposing the norm” of z, that is summing over a subset of orbitals i, the result is less than unity and is a measure of the contribution of that subset to the unit norm. Note: this decomposition is essentially like a Mulliken analysis. was generated with two color weights: all d orbitals in the Co majority spin channel were combined for the first weight, and the corresponding d orbitals in the Co minority channel the second. Thus, the first color weight is zero if there is no projection of the eigenfunction onto majority d channel, and 1 if the entire eigenfunction is of majority d character. The same applies for the second weight, but for the minority d channel.

Note: was generated from one of the validation scripts in the Questaal source directory.

$ ~/lm/fp/test/test.fp co 1

The script runs lmf as:

lmf  co -vmet=4 -vlmf=1 -vnk=8 -vnit=10 --pr31,20 --no-iactiv -vso=t --band~col=5:9,dup=9~col2=18+5:18+9,dup=9~fn=syml

-vmet=4 -vlmf=1 -vnk=8 -vnit=10 assign algebraic variables which will modify when run through the preprocessor. They are of secondary interest here. -vso=t does the same, but is important in this context because the input file contains the following:

HAM   ...  SO={so}

-vso=t sets variable so to true (or 1). The proprocessor transforms SO={so} into SO=1. Token SO controls spin orbit coupling.

--band~col=5:9,dup=9~col2=18+5:18+9,dup=9~fn=syml tells lmf to draw energy bands with two color weights (col=.. and col2=..) Orbitals 5-9 comprise the majority spin d orbitals of the first Hankel energy;, 14-8 those of the second. Note: dup=9 replicates the existing list, adding 9 to each element in the list.)

States 23-27 are the corresponding d orbital in the minority channel. The five d states are expressed conveniently as 18+5:18+9. These are the minority spin counterparts since the entire hamiltonian basis consists of 18 orbitals. When the hamiltonian is treated relativistically, the hamiltonian is doubled into a 2×2 supermatrix; with spin 1 orbitals occuring first.

Run plbnds as before, except eliminating -nocol and adding a line type:

$ echo -10,8 / | plbnds -fplot -ef=0 -scl=13.6 -lt=1,bold=3,col=0,0,0,colw=.7,0,0,colw2=0,.7,0 -lbl=M,G,A,L,G,K
$ fplot -f plot.plbnds
$ open

The line type specifes a solid line (-lt=1), the line thickness (bold=3); the default line color (col=0,0,0) which is the color when the first and second weights vanish; colors of the first weight (colw=.7,0,0) and second weight colw2=0,.7,0), respectively. The three numbers correspond to fractions of (red, green, blue). Thus, if a band has no d character it will be black; it will be red with 100% majority d character and green with 100% minority d character.

Colors provide an extremely helpful guide to interpret the bands. It shows clearly which bands have majority and minority d character.

Your postscript file should look like the figure below.

Energy bands for Co


See Table of Contents

3. plbnds manual

Invoke plbnds in one of the following ways:

plbnds [-switches] filename
echo emin, emax, w, h | plbnds [-switches] filename

filename is the file name ( in this case). You can also use just the extension (co).

plbnds reads four numbers from stdin:   emin, emax, width(cm), height(cm)
emin and emax comprise the lower and upper bounds of figure. Data is written only for bands that fall in this range. The third and fourth arguments determine the size of the figure; they are used only when plbnds makes a postscript file directly (Example 1).

Optional switches perform the following functions. A reference to  expr  indicates a real number or an algebraic expression.

See Table of Contents

4. Additional exercises

This tutorial comparing QSGW to LDA energy bands provides a simple demonstration of how to overlap bands generated from two calculations in one figure.

5. Other resources

See the fplot and pldos manuals.

See Table of Contents

Edit This Page