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

Table of Contents

• 1. Introduction
• 2. Examples
  • Example 1 : Directly generate a postscript file
  • Example 2 : Create data and script for fplot
  • Example 3 : Color weights
  • Example 4 : Spin Texture
    • a) xyz spin texture in Co
    • b) Sign of z component of spin in Co
    • c) xyz projection of spin in MAPI
• 3. plbnds manual
• 4. Additional exercises
• 5. Other resources

Preliminaries

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.

In a few places files in the Questaal repository are referred to. For purposes of this tutorial, it is assumed to reside in ~/lmf.

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, but there 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 these data files, a script plot.plbnds is automatically created designed for fplot. You can use fplot directly to make the figure, or use 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

Example 1 : Directly generate a postscript file

Enter the following to make and view the postscript file from bnds.co:

echo -0.8,0.6,10,15 | plbnds -lbl=M,G,A,L,G,K bnds.co
open fplot.ps

Notes:

• The energy bands are plotted in an energy window -0.8,0.6 Ry, in 5 panels.
  To find how many panels there are and the number of k points in each panel, do:   egrep '^ *[0-9]*$' bnds.ext
• 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.

  egrep ‘^ [0-9]$’ bnds.ext

Example 2 : Create data and script for fplot

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 bnds.co

 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 utility.
  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 fplot.ps

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 : Color weights

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 z_in. The wave function is normalized, and so $$\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 a Mulliken analysis.

We will simply take bnds.co as given (it is generated from one of the validation scripts in the Questaal source directory).

cp ~/lmf/fp/test/bnds.co .

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 structure of the bnds file is documented on this page.

bnds.co was generated with two color weights, as can be seen from the first line of the file

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

This line says that:

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

Note that strings col= are not used; they are there for record-keeping only.

All d orbitals in the Co majority spin channel are 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.

rm -f mixm.co rst.co
cp ~/lmf/b/fp/test/ctrl.co ~/lmf/b/fp/test/syml.co .
lmfa  co -vmet=4 -vlmf=1 
lmf   co -vmet=4 -vlmf=1 -vnk=8 --iactiv=no --pr31,20 -vnit=10 
lmf   co -vmet=5 -vlmf=1 -vnk=8 --iactiv=no --pr31,20 -vnit=1 --rs=1,0 -vso=1
lmf co -vmet=4 -vlmf=1 -vnk=8 -vnit=10 --pr31,20 --no-iactiv -vso=t --band~scol@z=27@l=2@spin1~scol2@z=27@l=2@spin2~fn=syml

HAM   ...  SO={so}

lmf co --pr55 --quit=ham

 Makidx:  hamiltonian dimensions Low, Int, High, Negl: 18 0 0 0
...
 Orbital positions in hamiltonian, resolved by l:
 Site  Spec  Total    By l ...
   1   A    1:9    1:1(s)   2:4(p)   5:9(d)
   2   A   10:18   10:10(s) 11:13(p) 14:18(d)

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

To generate a figure for the energy bands, run plbnds as follows

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 bnds.co

This is similar to Example 2 except -nocol is not used and line types are added. 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.

plbnds will generate a file bnd1.dat for the first panel, bnd2.dat for the second, and so on. Use your favorite graphics package to draw the figure, or use the fplot with the ready-made script plot.plbnds, which plbnds generates for fplot.

fplot -f plot.plbnds
open fplot.ps

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

Note: If you do not supply -lt=... plbnds will still include color weights in bnd1.dat, bnd2.dat, … and the script plot.plbnds, but all the weights default to black so you won’t see any colors.

Example 4 : Spin Texture

In the general noncollinear magnetic system, electron spins can point in arbitrary directions. The Mulliken decomposition described in Example 3 has a special mode for recording these directions (“spin texture”). In this mode four weights are generated: charge, and x-, y-, and z- components of the magnetization. The charge is merely the standard color weight (Example 3), and evaluates to 1 if all the orbitals are included (see Eq.(6) in the DOS tutorial). Designate the weights $w_q$, $w_x$, $w_y$, $w_z$.

This example presents several illustrations explaining how color weights can be used to represent spin texture.

a) xyz spin texture in Co

In this example the xyz spin projections in Co are shown as three colors (black=$w_z$, red=$w_x$, green=$w_y$). The bands file bnds.co-st is generated by the test described at the beginning of the Examples section. Here we just take file generated by the test.

Make a fresh working directory and copy this file to it.

cp ~/lmf/fp/test/bnds.co-st .

and inspect the top of the file to verify it has four color weights.

Note: you can make bnds.co-st by running the test (assuming ~/lmf/b is the build directory where you compiled your Questaal distribution)

~/lmf/b/fp/test/test.fp co

For some interpretation of the instructions this test executes, see the dropbown box above, “Click here to see how to generate file bnds.co”. Note particularly the lines:

lmf co -vmet=4 -vlmf=1 -vnk=8 -vnit=10 --pr31,20 --no-iactiv -vso=t --band@scolst~z=27~l=d@fn=syml
mv bnds.co bnds.co-st

The following generates a bands figure, with the projection of spin onto the xy plane represented by red and green. Black is $w_z$.

echo -10,5,5,10 | plbnds -wscl=.6,.6 -fplot~sh~ext=z~lt=1,col=0,0,0,colw=1,0,0,colw2=0,1,0~spintexture -ef=0 -scl=13.6 -lbl=M,G,A,L,G,K bnds.co-st
open fplot.ps

You should see the same Co bands as in Example 3, but now the bands are all black except for tiny regions of red where two bands of opposite spins coincide. This means that the band structure is nearly collinear.

b) Sign of z component of spin in Co

Since the vector points essentially along a single direction, it is useful to know whether the spin is pointing up or down. The spin texture facility has a special mode that uses two color weights, the first represents positive values of projection onto a particular axis, the second for negative values of projection. In particular if z is the axis of projection, a projection between 0 and +1 on z would result in the band being weighted by the first color; a projection between 0 and −1 the band would be weighted by the second color. In addition, there is a choice of normalization: by default the magnetic moment $(x,y,z)$ is normalized to 1.

Do the following:

echo -10,5,5,10 | plbnds -wshft=-.15 -wscl=.6,.6 -fplot~sh~ext=z~lt=1,col=0,0,0,colw=1,0,0,colw2=0,1,0~spintexture=z -ef=0 -scl=13.6 -lbl=M,G,A,L,G,K bnds.co-st
cp plot.plbnds plot.plbnds1    [This step is not necessary but is added to compact two figures; see below]
open fplot.ps

The figure has colors somewhat similar to Example 2: red and green indicate projections onto +z and −z spin components, respectively. Since almost every state is aligned along z, every band is distinctly green or red, in contrast to Example 2. This is because by default magnetization weights vector $(w_x,w_y,w_z)$ is normalized to unit length, and since the direction points almost entirely along z, bands are either red or green. The only exception is a small region for the lowest band near Γ, where the color becomes gray. At this point s and d character become completely decoupled. The s band has a negligible coupling to the exchange correlation field; it no longer needs to align with z.

If you leave $(w_x,w_y,w_z)$ unnormalized, then the colors will reflect not only the sign but the magnitude of the projection on that axis. Do this by using ~spintexture0 instead of ~spintexture :

echo -10,5,5,10 | plbnds -wshft=.55 -wscl=.6,.6 -fplot~sh~ext=z0~lt=1,col=0,0,0,colw=1,0,0,colw2=0,1,0~spintexture0=z -ef=0 -scl=13.6 -lbl=M,G,A,L,G,K bnds.co-st
cp plot.plbnds plot.plbnds2    [This step is not necessary but is added to compact two figures; see below]
open fplot.ps

Now the figure more closely resembles Example 2. Red and green correspond to large magnetization; black to weak magnetization.

To compare the figures side by side, do the following:

cp plot.plbnds1 plot.plbnds
cat plot.plbnds2 | awk '{if ($1 != "%char0" && $1 != "fplot") {print}}' >> plot.plbnds
fplot -f plot.plbnds

(The second instruction appends plot.bands2 to plot.plbnds, stripping out the header to make one monolithic file).

c) xyz projection of spin in MAPI

NH₃CH₃PbI₃, also called MAPI, is a new solar cell material. It nonmagnetic but has a large spin-orbit coupling and large internal fields, resulting in a large Rasha splitting of the bands.

For a particular choice of pseudocubic cell, the spins point almost uniformly along the y axis. To see this, take a bands file from the standard Questaal distrbution:

cp ~/lmf/plot/examples/bnds.mapi .

This data was generated along a symmetry line that passes through the two local (Rashba-induced) minima.

plbnds -range=-4,4 -wshft=-.15 -wscl=.6,.6 -fplot~sh~ext=1~lt=1,col=0,0,0,colw=1,0,0,colw2=0,1,0~spintexture -ef=0 -scl=13.6 -lbl=k1,k2 bnds.mapi
cp plot.plbnds plot.plbnds1    [This step is not necessary but is added to compact two figures; see below]
open fplot.ps

Ten energy bands should be nearly green, except near the center point where they turn brown, where it becomes noncollinear with a projection along x and z as well as y. Far awan from the center point the lines are green because the spins point along +y for k to the right of the midpoint, and along −y for k to the left.

To see the sign of the spin, do the following

plbnds -range=-4,4 -wshft=.55 -wscl=.6,.6 -fplot~sh~ext=2~lt=1,col=0,0,0,colw=1,0,0,colw2=0,1,0~spintexture=y -ef=0 -scl=13.6 -lbl=k1,k2 bnds.mapi
cp plot.plbnds plot.plbnds2    [This step is not necessary but is added to compact two figures; see below]
open fplot.ps

Now red and green highlight the transition from +y to along −y as k crosses the midpoint between the two minima.

To compare the figures side by side, do the following:

cp plot.plbnds1 plot.plbnds
cat plot.plbnds2 | awk '{if ($1 != "%char0" && $1 != "fplot") {print}}' >> plot.plbnds
fplot -f plot.plbnds

(The second instruction appends plot.bands2 to plot.plbnds, stripping out the header to make one monolithic file).

See Table of Contents

3. plbnds manual

plbnds operates in one of three modes:

1. direct mode which generates a postscript file directly from filename. It is fast but not flexible. See Example 1
2. fplot mode (−fplot), which creates templates for the fplot utility. This is the recommended mode. See Example 2.
3. spectral mode (--sp) — a special purpose mode for band pictures of spectral functions.

Additionally it has edit modes that allow you to modify bnds files in different ways.

Invoke plbnds in one of the following ways:

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

filename is the file name, e.g. bnds.co. 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.
• Optional arguments  w,  h  are used only in direct mode, as in Example 1. They determine the approximate width and height of the figure in cm.
  If you do not use  w,  h, substitute  /.
• To scale the figure in  −fplot  mode, use ~scl=w [,h].

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

• −help  |  --help  |  --h
  prints out a help message and exits.

• −h5  |  --h5  | 
  Input bnds is in hdf5 format.

• −range=#1,#2[,#3,#4]
  Specify ranges. #1 and #2 are the minimum and maximum energies. Optional #3 and #4 are respectively the width and height of the figure, in cm.
  If you omit this switch, plbnds prompts for this information from the standard input.

• −bands=lst
  plot only a subset of the bands. lst takes the form of Questaal’s (extended) syntax for integer lists. (You can use the shriek  (!)  in this context).

• −lbl  |  −lbl=a,b,c,d,…
  Provide labels for endpoints of each symmetry line. Without arguments, plbnds will attempt to read labels from the first line of the bnds.ext file (characters following lbl=), and if not present, plbnds will prompt you for the sequence. In the the second form, a,b,c,d,… are k point (symmetry) labels at the points where panels meet. (See Example 1)
  For now, labels must be one character each. You should supply n+1 labels, where n is the number of panels.
  Note: G is turned into the Greek character Γ.

• −tl  |  −tl=strn
  Adds a title to appear at the top of the figure. (This switch may work but it is no longer maintained). If no argument is supplied plbnds will prompt for a title from stdin.

• −ef=expr
  shifts the energy bands so that the Fermi energy lies at expr. (See Example 2)

• −scl=expr
  scales bands by expr. (See Example 2)

• −wscl=w[,h]   (applicable to fplot mode only)
  scales the default figure size by w. w is a real number or expression.
  If the second argument is present the width is scaled by w, the height by h.
  This switch is used in Example 4 and in this tutorial.

• −wshft=x[,y]   (applicable to fplot mode only)
  shifts the default figure to the right by x. x is a real number or expression.
  If the second argument is present the figure is shifted upwards by y.

• −spin1  |  −spin2
  plots bands of first or second spin (bnds.ext must contain data for two spins).

• −skip=lst
  skip panels in lst, e.g. −skip=1,3. This page documents integer list syntax.

• −dat=nam (same as −fplot~ext=nam)
  Substitute nam for .dat when writing data files.
  This is useful when merging two or more sets of bands into one figure.

• −nocol  |  --nocol (may be used in conjunction with −fplot)
  Ignore information about color weights.

• −col4:bnds2,fnout
  merges the color weights in bnds2 with the current file (last argument on the command line) and writes the merged data to file fnout. fnout and bnds2 refer to the full file name.
  plbnds and fplot are equipped to generate energy bands with up to four color weights; however lmf can only manage up to three.
  −col4 enables you to merge back-to-back band calculations with an additional weight into a single file, suitable for processsing by plbnds and fplot.
  • bnds2 can contain only one color weight.
  • The current bnds file (read by plbnds specified by the last command-line argument) and bnds2 must contain identical bands generated at the same k points.

• −merge=file2[,file3]  |  −mergep=file2[,file3]
  merges two bands file (one for each spin in the spin-pol case).
  Optional file3 causes plbnds to write the merged file to file3.
  -mergep pads a file containing fewer bands so that the number of bands in the merged file is fixed.

• −sipr~scl=#[~neg][~fn=outfile]
  Reads the inverse participation ratio from evec.h5 and appends an additional color weight in the bands file. A new bands file is written.
  ~scl is required: the weight is defined as scl/IPR. If ~neg is also present, the weight is defined as max(1-scl/IPR,0).
  Optional ~fn=outfile specifies the name of the output bands file. If not specified it uses the input file name, with .ipr appended.

fplot mode

• −fplot[~options] causes plbnds to create input for fplot or another graphics package (see Example 2.). It does the followng:
  1. writes energy bands to files bnd1.dat, bnd2.dat, … (one file for every panel).
  2. generates a script plot.plbnds.
  3. Optionally creates a postscript file by invoking fplot in a subshell.
     Options: the first character after −fplot (assumed to be  ’~’  here) delimits the different switches.
     • ~2sp : writes data for two spins
     • ~sh : invoke fplot in a subshell to make fplot.ps.
     • ~lt=string : specify fplot line type
     • ~ext=nam : names the extension for data files (default is .dat)
     • ~ib1=# : specify lowest band to include in plot
     • ~ib2=# : specify highest band to include in plot
     • ~scl=w[,h] : same as --wscl=w[,h]
     • ~shft=x[,y] : same as --wshft=x[,y]
     • ~spintexture : specifies that spin texture is used to define color weights.
       plbnds expects the bnds.ext to have four color weights, $w_q$ corresponding to charge, and $w_x$,$w_y$,$w_z$ corresponding to $(x,y,z)$ components of the magnetization density.
       plbnds will generate three color weights: $(w'_x,w'_y,w'_z)$ The components are normalized such that $\lvert(w'_x,w'_y,w'_z)\rvert{=}1$.
     • ~spintexture0 : same as ~spintexture but $(w'_x,w'_y,w'_z)$ is not normalized.
     • ~spintextureq : same as ~spintexture but $(w'_x,w'_y,w'_z)$ is normalized to $w_q$.

  For each of ~spintexture flags, append  =x | =y | =z  to use a single Cartesian component. Two color weights are assigned: first weight applies to projection >0, second to projection <0.
  Example 2 illustrates the −fplot switch; Example 4 illustrates the spin texture options.

  Note: you can also split off the fplot~lt modifier as a separate switch, e.g. -lt=string.

You can create and view a postscript figure of the bands with

  fplot -f plot.plbnds
  open fplot.ps

Alternatively, make fplot.ps by using the ~sh option to −fplot.

To customize the figure, edit plot.plbnds. Refer to the fplot manual to learn about the capabilities and switches in the fplot tool.
Or, generate energy bands with your favorite graphics tool. bnd1.dat,  bnd2.dat, … are in Questaal’s standard form, an easily readable format.

Spectral function mode

• −sp[~switches]  sets up plots for drawing spectral functions along symmetry lines. It:
  1. reads spectral information from a file spq.ext, normally generated by lmfgws
  2. creates a data file spf.ext that gnuplot reads to generate the figure.
  3. creates a gnuplot script gnu.plt. Alternatively it writes spf.ext in a form that SpectralFunction.sh can read.

  On exit, plbnds will print out a brief message giving you the instruction to make a postscript (or other) file.
  It draws the bands in the window given by the input spq.ext; however, you can edit the gnu.plt to adjust it. This tutorial illustrates an interacting band plot.

  Switches: the first character after −sp (assumed to be  ’~’  here) delimits the different switches.
   ~lst=list  specifies which bands to include in the spectral function.  See this page for the syntax of integer lists.
   ~out=eps  |  out=svg  |  out=png  |  out=i
    Specify whether gnuplot is to generate a postscript file (.eps), a Portable Networks Graphics file (.png),
    or a Scalable Vector Graphics (.svg).  i = 1, 2, or 3, corresponds to these three formats.
   ~fs[@options]  is a “Fermi Surface” mode which expects spq.ext to contain spectral functions at a single frequency on a uniform grid.
    It writes the sum of spectral functions to a file spf.ext in Standard Questaal format, for subsequent processing.
    Options to ~fs:
       @fn=filename    reads range parameters and number of divisions from fnam
       @shft=#1[#2]    shifts x range by #1 and yrange by #2
       @scl=#1[#2]    scale x range by #1 and yrange by #2
       @swap    swaps ordinate and abscissa
   ~escl=val  scales the frequency mesh by val.
   ~window=#,#  sets the energy window for the band plot. It defaults to energy window in spf.ext.
   ~out=lmgf  tells plbnds to format spf.ext for the SpectralFunction.sh script.
   Note: If you make spectral functions with lmfgws and the output is in eV, use escl=1/13.6. SpectralFunction.sh assumes the file is in Ry units.
   ~ascl=val  scales the spectral function by val. Only affects the scale in the colorbar.
   ~atop=val  sets the top of the colorbar scale to val.
   ~abot=val  zeros out any point less than val
   ~writeqp  causes plbnds to extract the QP part of the spectral function, and write a bnds file.
   ~drawqp[:options]  tells plbnds to superimpose QP bands on top of the spectral function in the gnuplot script. Options:
     :ef=#     Fermi level shift when interaction is turned on (difference between chemical potential and noninterating fermi level)
     :bold=#    Pen thickness for noninteracting bands
     :col=#,#,#   Pen color for noninteracting bands
   Example: Draw spectral function + bands, where the noninteracting Fermi level is 0.038197 Ry higher than interacting one:
  plbnds '-sp~drawqp:ef=-0.038197*13.6~atop=10~window=-0.5,0.4' spq2.sr2ruo4

edit modes

plbnds has a limited, special purpose editing mode that is designed to extract and modify the bnds files it read. In this mode edits are made, creating a staging area with a new set of panels. After staging is complete you can write out the file to bnds.dat.

plbnds has another editor specifically for bnds files in hdf5 format.

Invoke the editor with --edit. If an ASCII file is supplied as input, the first editor is invoked. If an h5 file is supplied the hdf5 etiro is invoked. plbnds’ edit mode follows the same conventions as other Questaal editors: you can run it in batch mode or interactively.

The ASCII editor: options are limited at present to extracting one or set of panels from a bnds file, and writing the extracted ones to a new file. The options are:

• ~panels=lst  causes the editor to copy a set of panels to the staging area. lst is a list of panels that plbnds read from disk at start of execution. lst follows Questaal’s standard syntax for integer lists. Each element in lst must be an integer between 1 and the maximum number of panels read from the disk. You can copy the same panel into the staging area more than once, as shown in the example below.
• ~mirror=#  Operates on the #^th panel in the staging area. It reverses the order of q points in that panel.
• ~save  writes the panels in the staging area to file bnds.dat.
• ~q  causes plbnds to exit the editor and stop.

Example: plbnds --edit~panels=4,3~mirror=2~q bnds.yfege copies panels 4 and 3 read from file bnds.yfege into the staging area. The original panel 4 becomes the first panel; the original panel 3 becomes the second panel. Then the k-points in the second panel (original panel 3) are reversed, the file bnds.dat created, and plbnds exits.

The HDF5 editor: operates by reading the h5 input file when an instruction needs the data, performs the operation and possibly writes an output file, discards the data, and and either writes the updated bnds file to disk and exits, or returns to the interactive prompt.

• ef=#  changes the Fermi level in the existing h5 file
• fn=nam  changes the default input file hdf5 file name to nam. nam should be full name”//
• mergef@file@outfile   merges multiple bnds files (in h5 format) into one file
  file is a file name containing a list of h5 files to merge
  outfile is the name of the output h5 file
• panels@lst=list@file=outfile  Reorder panels in bnds file
  lst=list specifies a list of new panel order, following Questaal’s standard syntax for integer lists. outfile is the name of the output h5 file
• midp@n=#@file=outfile  Interpolate bands to midpoints and interleave with original bands
  n=# specifies the order of polynomial interpolation outfile is the name of the output h5 file
• ipr[@neg]@scl=#  merge weights for inverse participation ratio ipr from evec.h5 and add scl/ipar as new color weight
  Optional @neg causes the editor to use 1-scl/ipr as weight.
  This operation requires that eigenvalues in evec.h5 and bnds.h5 align.
• wadd@src=#[@dst=#[]@fs=#][@fd=#] | wadd@src=#[@dst=#][@fs=#]  multiply or add one color weight into another.
  src, dst are indices to source, destination color weight (dst set to 1 if user does not supply it)
  wfac : dest = fs × src × dst
  wadd : dest = fs × src + fd × dst
• q  quit the editor

Example: plbnds --h5 --edit~ef=0.096370/2+0.114572/2~q bnds.h5

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