Questaal Data files and their Formats

Questaal will generate many different kinds of files, depending on the context. In most cases files have an extension appended to identify a particular system. For example the main input file, the ctrl file, might be called ctrl.si. Files such as the rst file described below, have the same extension, e.g. rst.si.

Table of Contents

• Table of Contents
• Introduction
• Standard data formats for 2D arrays
  • Complex arrays
• Site files
• The restart file
• Positions file
• The qpts file
• File formats for k-point lists
• bnds file
  • bnds file, hdf5 format
  • Symmetry line mode
  • bnds file, ASCII format for symmetry line mode
  • List mode
  • bnds file, ASCII format for list mode
  • Mesh mode
  • bnds file, ASCII format for mesh mode
  • Transformation of the supplied k-points
• The atm file
• The basp file
• The wkp file
• The save file
• The spf file
• The dos file
• The smpot0 file
• The dosq file
• The bfield file
• The socscl file
• Selected files generated by lmf or lm for optics
  • File jdos
  • The opt file
  • Files optdata and optdatac
• Selected files generated by lm
  • The vext file
• Selected files generated by lmgf or lmpg
  • The vshft file
  • The moms file
  • Files lbc and rbc
  • Files jz, rzl, rzr, and jzk and rzk
• Selected files used or generated by the GW codes
  • eigen.h5
  • evec.h5
  • bz.h5
  • atom.h5
  • pb.h5, pbc.h5, pbb.h5
  • vc.h5, vcc.h5
  • pqmap
  • QPU
  • TOTE.UP and TOTE2.UP
• Selected files read or generated by lmfgws
  • The se file
    • se file, ASCII format
    • se file, hdf5 format
  • Files sdos, seia, pes, pesqp, spq, seq
• Selected files read or generated by lmfdmft
  • Files sig.inp, gloc, and gkloc
  • File gk

Introduction

Questaal codes require a wide variety of data formats to meet the diverse range of purposes they serve. When files are not too large they are usually written in ASCII format. In many cases, such files are passed through the file preprocessor before being scanned for data. The preprocessor’s facilities (e.g. to evaluate expressions and to make looping constructs) can be useful in many contexts.

The preprocessor can modify the input before it is parsed for data. Note also:

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

Standard data formats for 2D arrays

Many Questaal programs, for example the fplot utility and electronic structure programs such as lm, read files containing 2D arrays. Most of the time they follow a standard format described in this section.

Where possible, the 2D array reader uses rdm.f, so that the files are read in a uniform style. Unless told otherwise, the reader treats data as algebraic expressions. Thus you can use expressions in these files, in addition to expressions in curly brackets {…} managed by the preprocessor.

The array reader must be given information about the number of rows and columns in the file. (They are called nr and nc here.)

The safest way to specify nr and nc is to indicate the number of rows and columns in the first line of the file, as illustrated in the code snippet below (this is the beginning of chgd.cr used in an fplot exercise). nr and/or nc (the number of rows and columns) can be stipulated in the file as shown in the first line of chgd.cr:

% rows 101 cols 101
      0.0570627197      0.0576345670      0.0595726102      0.0628546738
...

Note: % rows... is not a preprocessor directive because  rows  is not a keyword the preprocessor recognizes.

The reader attempts to work out nr and nc in the following sequence:

• The reader checks to see whether the first nonblank, non-preprocessor directive, begins with % ... rows nr or % ... cols nc.
  If either or both are supplied to set nr and/or columns to nc are set accordingly.
  • In some cases nr or nc is known in advance, for example a file containing site positions has nc=3. In such case the reader is told of the dimension in advance; if redundant information is given the reader checks that the two are consistent.
    If they are not, usually the program aborts with an error message.
• If nc has not been stipulated, the parser will count the number of elements in the first line containing data elements, and assign nc to it.
  For the particular file chgd.cr, the reader would incorrectly infer nc=4: so nc must be stipulated in this case.
• If nr has not been stipulated in some manner, the reader works out a sensible guess from the file contents.
  If it knows nc, the reader can count the total number of values (or expressions more generally) in the file and deduce nr from it.
  If the number of rows it deduces is not an integer, a warning is given.

Complex arrays

If the array is complex, the first line should contain complex, e.g.

% ... complex

The entire real part of the array must occur first, followed by the imginary part.

Site files

Site files can assume a variety of formats. Their structure is documented here.

The supercell maker writes site files when constructing supercells. You can also use lmchk to write a site file See command line arguments to lmchk.

See Table of Contents

The restart file

The full-potential codes, e.g. lmf, store complete information to restart a calculation where you left off. This is normally kept in a binary file, named rst.ext; though it can be read from, or written to an ascii file rsta.ext. It is a convenient way to retain all the input conditions of a self-consistent calculation. It contains information about the charge density and related parameters, such as the sphere logarithmic derivative parameters P. It also contains the site positions, and by default lmf will overwrite existing site positions when reading from this file. The internal structure of rst.ext is rather involved, as it contains many parts. A description can be found in the comments of the source code, Questaal-top-level-directory/fp/iors.f.

The ASA codes, e.g. lm, lmgf, and lmpg can also read input from the restart file. In this case the file is always ASCII and the format is different. The full density is not kept, but only the logarithmic derivative parameters P, and the energy moments of the density Q₀, Q₁, Q₂.

Positions file

You can read site positions from a positions file. Site positions p are overwritten with the contents of filnam.ext, if command-line switch --rpos=filnam is present.

filnam.ext should take one of two forms:

• (mode=0, default) the standard Questaal format for two-dimensional arrays.

• (mode=1) The first row should begin with % and contain mode=1.
  Each subsequent line should consistent of an integer (site index i) followed by a vector of three numbers (p). Only sites where index i is read are affected.
  Example: assign position of atom 3 to (0.1,0.2,0.3) in Cartesian coordinates, units of 2π/a.

  % mode=1
  3     .1 .2 .3

You can also read from a file a change in position Δp, to be added to p, with command-line argument --rdpos.

You can also write current positions to this file, with lmchk ... --wpos=filnam, with lmscell ... --wpos=filnam, or with lmf ... --wpos=filnam. The latter is useful if you find the the current positions in the restart file.

The qpts file

This file may be used to read a list of k points for Brillouin zone integration, in lieu of generating them via specifications in the  BZ  category.

Note: k points are internally stored, and typically read, in Cartesian coordinates, in units 2π/a where a is the lattice constant, input as ALAT in the input file

You can generate file qpts.ext using  --putqp; you can cause programs like lmf to read them using  --getqp.

The standard format for this file is

  nkp=nqp; nkabc=n1,n2,n3; lshft=sh1,sh2,sh3; ntet=ntet
  #
  1     q_x(1)     q_y(1)     q_z(1)     w(q_1)
  ...    ...        ...        ...        ...
  nqp  q_x(nqp)   q_y(nqp)   q_z(nqp)   w(q_nqp)
  #
  1     idtet(1,1)     idtet(2,1)     idtet(3,1)     idtet(4,1)     idtet(5,1)
  ...      ...            ...             ...           ...            ...
  ntet idtet(1,ntet)  idtet(2,ntet)  idtet(3,ntet)  idtet(4,ntet)  idtet(5,ntet)

Lines beginning with  #  are ignored.

The first line declares dimensions used to generate the file:  nkp  is the number of q-points in the file,  nkabc  corresponds to the tag  BZ_NKABC ;  lshft  has the same meaning as  BZ_BZJOB . Finally  ntet  is the number of tetrahedra for each microcell in irreducible Brillouin zone. It is not necessary that tetrahedra be present; but you cannot perform BZ integrations using the tetrahedron method without them.

Next come the list of k points, together with the k point weights. Note the first column (the k point index) isn’t used by the code, but all five columns must be present

Next come information about tetrahedra: the second column is the number of occurences of this tetrahedron in the full BZ; the final four columns point to the corners of the tetrahedra. This latter is not required, but if it is not present, you cannot perform integrations using the tetrahedron method.

File formats for k-point lists

k-points and which energy bands or quasiparticles are to be generated are specified in one of three types, or modes.

k points are read by default in Cartesian coordinates, in units 2π/a where a is the lattice constant (called ALAT in the input file). When read via the

• (default) symmetry line mode is designed for plotting energy bands along symmetry lines. In this case k-points are specifed by a sequences of lines with start and end points. The output is a bands file in a specially adapted format.

• List mode is a general purpose mode to be used when energy levels are sought at some arbitrary set of k-points, specified by the user. Data is written in a standard format with k-points followed by eigenvalues.

• Mesh mode is a mode that generates states on a uniform mesh of k-points in a plane. Its purpose is to generate contour plots of constant energy surfaces, e.g. the Fermi surface. Data file output is written in a special mode, with levels for a particular band at all k written as a group.

• Box mode is a special-purpose mode that generates k-points in a cluster around a central point. It is used as an engine for the band-edge utility.

bnds file

Energy bands and optional color weights are written to a bnds. file. The format can be ASCII (usually written to bnds.ext), binary (usually written to bbnds.ext) or in hdf5 format (bnds.h5). The hdf5 format is essentially the same for all modes, while the ASCII and binary formats are tailored to the mode in which they are generated (symmetry line mode, qpts-list mode, or 2D-mesh). The ASCII formats are documented separtely after description of the hdf5 format.

bnds file, hdf5 format

dataset       dimensions                       description
bnds          {nband, nsps, nqtot}             (symmetry line and qpts list modes) Energy bands (independent particle hamiltonian, as in DFT)
              {nqx, nqy, nband, nspx}          (mesh mode) Energy bands on a regular mesh of (nqx, nqy) divisions
colwt         {nband, nsp, ncol, nqtot}        Optional color weights (symmetry line and qpts list modes)
              {nqx, nqy, nband, ncol, nspx}    Optional color weights (mesh mode)
dlabel        {*}                              (Symmetry line mode only) floating point representation of symmetry line labels
ef            {1}                              Fermi energy
iblst         {nblst}                          If present, list of bands included in the bnds and colwt datasets
mode          {1}                              1,2,3 for symmetry line, qpts, and 2D mesh modes.
nband         {1}                              Dimensions bnds and colwts
nblst         {1}                              size of iblst (used if a subset of all bands is written)
ncol          {1}                              Number lf color weights, if colwt exists
nqpan         {0:*}                            context-dependent information about how q points are organized
                                               (Symmetry line mode) information about how the nqtot q-points are grouped by panels.
                                               nqlst(0) is the number of panels; nqlst(i) is index to the last qp in panel i
                                               (2D mesh mode) information about how the nqtot q-points are grouped by panels.
                                               nqlst(0) = -3  ⇒ qp list corresponds to a mesh of qp on a regular 2D mesh
                                                                nqlst(1:2) specify the number of rows and columns on the mesh
nqtot         {1}                              total number of qp; dimensions bnds and colwt
nspx          {1}                              total number of independent spins; dimensions bnds and colwt
qp            {3, nqtot}                       List of qp
swqlst        {3}                              swqlst(1): If 1 or 2, one spin is written, even for spin polarized calculations
                                               swqlst(2): 1 ⇒ color weights made by spin texture
                                                          2 ⇒ band color weights made from DOS
                                               swqlst(3): 0 ⇒ eigenfunctions generating color weights are represented in real harmonics
                                                          1 ⇒ weights correspond to spherical harmonics
                                                          2 ⇒ weights correspond to relativistic kappa-mu representation
nqxy          {nqx,nqy}                        (mesh mode) number of <i>k</i> divisions along abscissa and ordinate

Symmetry line mode

This is the default mode. Symmetry lines for all crystal systems are described here.

Note: lmchk will automatically generate a template file with --syml switch switch.
(For this switch to work fully automatically you must have the spglib library installed and include the link to the library in flags.mk.)

The k-points file consists of a list of symmetry lines and the number of k-points in each line. Each line of text in the file specifies one symmetry line with the syntax

Number-of-pts  start-k   end-k

start-k and end-k each consist of three numbers specifying a k-point. You can terminate the list with a line beginning with 0. For example:

51   0  0  0    0  0  1
51   0  0  1    0 .5 .5
0    0  0  0    0  0  0

The start and end k-point refer to Cartesian coordinates (units 2π/a), or if you use --band~mq, they refer to crystal coordinates.

See this tutorial for a demonstration using the full-potential code lmf in this mode, and this tutorial using the ASA code lm.

bnds file, ASCII format for symmetry line mode

The file begins with

 36  -0.02136     2  LBL=xxxx   col= 5:9,14:18  col2= 23:27,32:36
   41                                           ← number of points on this line
   0.50000   0.50000   0.50000                  ← first k point  ↓ energy levels
 -4.3011 -4.2872 -4.2872 -0.6225 -0.4363 -0.4363 -0.2342 -0.2342 -0.1355  0.1484
  0.9784  1.2027  1.2027  1.7702  1.7702  1.8940  2.3390  2.3390  2.4298  2.9775
  2.9775  3.0605  3.1020  3.1020  3.6589  3.7134  4.1113  4.1494  4.1494  4.6987
  5.3267  5.3267  5.6162  5.6162  5.9457  6.4435  6.4435  8.6484  8.6484 10.1458

The header line consists of the (maximum) number of bands (36); the Fermi level (-0.02136); and the number of color weights (2). The remainder of the line is for informational purposes only and is not needed.

Next follow data for each symmetry line, one line after the other. The data structure for a single symmetry line has this form:

• A line with specifying the number of points for the current symmetry line.
  Next follow for each point i:
  1. a line containing k_i (3 numbers).
  2. one or more lines with the energy levels for k_i
  3. If color weights are present, information about color weights, consisting of
     • a line containing k_i (3 numbers) (should be the same as (1))
     • one or more lines with the color weights (should have the same format as (2)
  4. If a second set of color weights is present, there are lines similar to (3).
  5. If in a spin-polarized calculation with both spins present, the same information (1-4) is written for the second spin.

To find how many panels there are and the number of k points in each panel, do

egrep '^ *[0-9]*$' bnds.ext

Making figures, symmetry-line mode

Use plbnds to read this file format. It can generate directly a (not very pretty) picture rendered in postscript. Better, plbnds can generate data files and a script for the Questaal graphics tool fplot. plbnds generates energy bands in a simple to read, standard Questaal format. You can use fplot or your favorite graphics package.

See Table of Contents

List mode

This mode is specifed by, e.g. command line argument --band~qp. Use this mode to generate energy levels for a discrete list of k-points. The k-points file consists of a list of points in standard Questaal format, e.g.

-.01  0  0
  0   0  0
 .01  0  0

This file must have 3 columns, corresponding to the x,y,z, components of k. Unless you specify otherwise the number of rows in the array are the number of k points.

Alternative file format for k-points specification

There is an alternative format available for this mode: it is the format automatically generated if  BZ_PUTQP  is set or if the command-line switch  –putqp  is present.

 nkp=2
  1  0.100000000000D+00  0.000000000000D+00  0.000000000000D+00
  2 -2.600000000000D-01  2.500000000000D-01  2.500000000000D-01

The k-points file reader will automatically distinguish between these formats.

bnds file, ASCII format for list mode

Bands are written in standard Questaal format, used, e.g. by the matrix calculator mcx. The first three columns are the k point; the remaining columns are the bands. If color weights are specified, an additional group of columns are appended.

Plotting, list mode

Because the k-points need not follow any particular pattern, there is no generic plotting scheme. As noted, the file is in standard Questaal format which can be easily read by programs such as MATLAB.

Additional options, list mode

The list mode has additional sub-options, that make it convenient to collate distinct groups of k-points into a single list. Switch
--band~qp~...
may be extended with any of these switches:
--band~qp[,inc=<i>expr</i>][,merge=fnam][,save=fnam]~...

• [,inc=expr] causes the list reader to parse each k-point, and exclude those for which expr is zero. expr is an ASCII string containing an algebraic expression. expr can (and is expected to) contain k-point specific variables, which include:

  iq   k-point index
  qx   kx
  qy   ky
  qz   kz
  q    |k|=[kx2+ky2+kz2]1/2
  

  The expression should be integer (returning 0 or nonzero). Example: –band~qp,inc=q<1/2
  In this case only k-points read from the file whose magnitude is less than 0.5 will be retained.

• [,merge=fnam] causes the list reader to read a second file fnam.ext (in standard Questaal format and append the list read from it to the original list.

• [,save=fnam] causes the list reader to write the final k-points list to fnam.ext. After writing this file the program automatically stops.

See Table of Contents

Mesh mode

In this mode k-points are generated on a uniform 2D mesh, useful for contour plots. Invoke with

  --band~con~... | --band~mq~con~...

The mesh is specified by a file containg one line with of the form

<i>v<sub>x</sub></i>     range  <i>n<sub>x</sub></i>     <i>v<sub>y</sub></i>     range  <i>n<sub>y</sub></i>   height|origin  band</i>

where:

• v_x and v_y are two vectors on the reciprocal lattice that define a parallelepiped, as well as the orientation of the parallelepiped’s plane.
• range is a pair of numbers marking starting and ending points along each vector
• n_x and n_y are the number of divisions along the first and second vectors
• height | origin specifies the k point in the center of the parallelepiped. Select one of the two options:
  • origin is a sequence of three real numbers, specifying a vector in reciprocal lattice, either in cartesian coorindates or, if mq is supplied, as multiples of the reciprocal lattices.
  • height specifies the origin (a vector) as height · (v_x × v_y) / | v_x × v_y | .
• band is an integer list specifying which band(s) are to be written to the output.

By default, v_x, v_y, and origin are in Cartesian coordinates, in units 2π/a. The --band~mq~con form declares all of them to be given in fractional multiples of reciprocal lattice vectors. Note that this does not apply to height: mq plays no role in specifying the origin in this case.

Example: file fs.ext contains

.5 0 0   -1.5 1.5       51   0 .5 0     -1.5 1.5   51 1/2  12:16      #  comment here

If you run lmf or another band program with --band~con~fn=fs, output file bnds.ext will contain energy bands in mesh mode, bands 12…16. Bands at the five sets of 51×51 mesh points are stacked one after the other. The first k point (lower left corner will be (−3/4,−3/4,1/2) and the last (upper right corner) will be (3/4,3/4,1/2).

bnds file, ASCII format for mesh mode

Bands are written in standard Questaal format used by matrix calculator mcx and the graphics package fplot. The number of rows is the number of divisions in the first vector; the number of columns is the number of divisions in the second vector. No k point information is written (it is implicit in the uniform mesh).

Plotting, mesh mode

Several applications of making Fermi surface contours are shown on this page.

Transformation of the supplied k-points

The k-points as supplied from the input file can be transformed.

This is useful in several contexts. If spin-orbit coupling is present on the bands depend on the relative orientation of the coordinate system and spin quantization axis (the z axis by default).

In an angle-resolved photoemission experiment, $\mathbf{k}$ normal to the surface $\mathbf{k_\perp}$ is modified on exiting the surface, whereas $\mathbf{k_\parallel}$ is conserved. This means that $\mathbf{k}$ measured by ARPES slightly different from $\mathbf{k}$ calculated from the band structure. The larger the kinetic energy the smaller the effect, but in typical photoemission experiments it is not negligible.

% [var=expr var=expr ...]   kx=expr  ky=expr  kz=expr

  qx   kx
  qy   ky
  qz   kz
  q    |k|=[kx2+ky2+kz2]1/2

% map kx=(q^2+.1^2-qy^2-qz^2)^.5
41  .5 .5 .5     0  0 0                L to Gamma
...

 suqlst: map qp using the following:
 kx=(q^2+.1^2-qy^2-qz^2)^.5

~/lm/fp/test/test.fp cu 1

lmf -vrot=t cu --showp

$ lmf -vrot=t cu --quit=ham

           Lattice vectors:                         Transformed to:
   0.0000000   0.5000000   0.5000000     0.1035534   0.6035534  -0.3535534
   0.5000000   0.0000000   0.5000000     0.6035534   0.1035534  -0.3535534
   0.5000000   0.5000000   0.0000000     0.0000000   0.0000000  -0.7071068

$ lmf  --no-iactiv cu -vnk=8 -vbigbas=t -vpwmode=11 -voveps=0d-7 --band:fn=syml

$  lmf  --no-iactiv cu -vnk=8 -vbigbas=t -vpwmode=11 -voveps=0d-7 -vrot=t --rs=101 '--band~rot=(1,-1,0)pi/2~fn=syml'

% map kz=(q^2+.01^2-qx^2-qy^2)^.5*(qz>0?1:-1)

See Table of Contents

The atm file

File atm.ext is generated by lmfa and contains information about free-atomic densities. The potential is taken to be spherical, so a wave function has $\ell$ as a good quantum number and there is one radial function for each $\ell$. Atomic wave functions are computed numerically on a shifted logarithmic mesh and the density obtained by summed the wave functions according to the occupations of each $\ell$. There is one density for every atom.

Each free-atomic density is divided into an augmentation part, tabulated on the shifted logarithmic mesh. and the density in the interstitial. The numerical density is fit to a linear combination of Hankel functions, so that densities at different sites can be overalapped (called a Mattheis construction). This serves as an initial trial density for the the lmf code.

The atm file is written in ASCII with a simple structure. First come header information, e.g.

     z          a      nsp lrel  nr       rmt          rsm
  14.000   0.0250000    1    1   335    2.2213550    1.1106775

nr and rmt are the number of radial mesh points and the muffin-tin radius, respectively. These numbers, and the “spacing” parameter a, fix the radial mesh.

Next follows a tabulation of the smooth Hankel energies and coefficients that fit the numerically determined density, e.g.

nxi   6
 -1.00000000D+00 -2.00000000D+00 -4.00000000D+00 -6.00000000D+00 -9.00000000D+00 -1.50000000D+01
  3.27859984D-01  7.27618807D+00 -5.53897094D+00 -7.22461640D+01  4.40875210D+02 -2.57698030D+03
  0.00000000D+00  0.00000000D+00  0.00000000D+00  0.00000000D+00  0.00000000D+00  0.00000000D+00

Then there is a line containing information about the core charge and some potential and kinetic energy parameters needed to calvulate the total energy, e.g.

core      10.0000000     653.3489657     -31.1177328     568.0074390

Then follows the valence density

rho
... nr points

and the core density

rhoc
... nr points

and the potential that generates this density

v0
... nr points

This structure is repeated for every atom.

For further discussion about The atm file and how it is used, see this tutorial.

See Table of Contents

The basp file

File basp.ext contains information about the lmf basis set. In the Bi₂Te₃ tutorial it reads:

BASIS:
Te RSMH= 1.615 1.681 1.914 1.914 EH= -0.888 -0.288 -0.1 -0.1 P= 5.901 5.853 5.419 4.187
Bi RSMH= 1.674 1.867 1.904 1.904 EH= -0.842 -0.21 -0.1 -0.1 P= 6.896 6.817 6.267 5.199 5.089 PZ= 0 0 15.936

The file consists of one line for each species (it is not an error if a species is missing). The line begins with the species name, optionally followed by

• envelope shape parameters RSMH=… and EH=… and possibly RSMH2=… and EH2=…
• augmentation sphere boundary conditions P=…
• Local orbital information PZ=….

I/O is performed by routine iobzwt in subs/ioorbp.f.

See Table of Contents

The wkp file

wkp.ext keeps Fermi level efermi and band weights wtkb(nevx,nsp,nq) for Brillouin zone integration.

This binary file consists of a header in a single record, followed by second record containing wtkb(nevx,nsp,nq).
The header contains a dimensioning parameter, number of spins and irreducible k points in the Brillouin zone:
  nevx  nq  nsp  efermi

I/O is performed by routine iobzwt in subs/suzbi.f.

See Table of Contents

The save file

save.ext keeps a log of summary information for each iteration in iterations to self-consistency.

Each line records data for one iteration, including algebraic variables declared on the command line, followed by variables kept in the ctrl file by the % save directive, system magnetic moment (in magnetic systems) and total energy.

The box below shows an example from the basis set tutorial:

h gmax=4.4 nkabc=3 ehf=-126808.3137885 ehk=-126808.2492178
i gmax=4.4 nkabc=3 ehf=-126808.3039837 ehk=-126808.2781451
i gmax=4.4 nkabc=3 ehf=-126808.2952016 ehk=-126808.2925665
...
c gmax=4.4 nkabc=3 ehf=-126808.2950696 ehk=-126808.2950608
i gmax=4.4 nkabc=3 ehf=-126808.2950731 ehk=-126808.2950686
i gmax=6 nkabc=3 ehf=-126808.294891 ehk=-126808.294886

The character at the beginning of the line has the following significance:

• c  self-consistency achieved within the specified tolerances
• i  intermediate iteration, not self-consistent
• h  the first iteration
• x  the maximum number of iterations was reached without achieving convergence
• C  (molecular statics) when both charge density is converged and forces fall below specified tolerance

File I/O is performed by subs/iosave.f.

See Table of Contents

The spf file

File spf.ext, and site-specific files spfn.ext contain spectral functions along symmetry lines generated by lmgf, with the --band switch. The spf file can also be generated by plbnds, reading spq files generated by the dynamical self-energy processor lmfgws.

How to use lmgf to make spf.ext is explained in this document. It contains a 1-line header consisting of values for qcut to be explained below, e.g.

#  1.19592  1.19592  2.19592  2.90302  3.61013

The header is followed by a sequence of lines:

[    w         q-q0        A(up)          A(dn)    ( this line is not present in the file)]
  -1.00000   0.00000      0.004900      0.004423
  -1.00000   0.01040      0.004896      0.004420
  -1.00000   0.02080      0.004886      0.004411
  ...
  -1.00000   3.61013      0.001589      0.001327
  -0.99800   0.00000      0.005079      0.004586
  -0.99800   0.01040      0.005075      0.004583
  ...

Notes:

1. A is the spectral function.
2. The frequency is ω = E−E_F.
3. The second column is the distance from the first q-point of the first symmetry line i.e. the position in a band figure relative to the left edge. A panel begins/ends where points coincide with qcut.
4. Bash script SpectralFunction.sh will generate figures directly from spf.ext.

Routine iospf in gf/specfun.f reads and writes spf.ext.

Example: qcut shown above was generated from the following symmetry lines file:

116  0  0  0    0  0  1.195917          Gamma to H
97   1  0  0    0  0  0                 M to Gamma
68   0  0  0    .5 .5 0                 Gamma to X
68   .5 .5 0    1  0  0                 X to M

The dos file

This file contains one or more densities-of-states on a uniform mesh of energy points. The traditional (standard) format for dos.ext is described here.
Note: dos.ext  may alternatively be written in standard Questaal format for 2D arrays (if generated using, e.g. --dos@rdm).

The traditional format begins with a header line

  -1.00000   0.00000  501   16    1  -0.01843   0.00000    1
    ↑          ↑       ↑    ↑     ↑      ↑        ↑       ↑
   emin       emax    ne   nchan  nsp    ef      delta    fmt

• emin   First energy point on mesh
• emax  Last energy point on mesh
• ne    Number of points
• nchan   Number of DOS per spin
• nsp    Number of spins
• ef     Fermi level
• delta    Sampling broadening
• fmt   Formatting style; should be 1.

Next follow the DOS (ne points per channel) written as nsp×nchan separate records.

The smpot0 file

File smpot0.ext contains a reference potential and density for certain Fourier components of the mesh potential (density) in reciprocal space. This file is used by lmf in conjunction with the application of an external potential, invoked with the --vext switch.

The Fourier components retained correspond to the nonzero Fourier components in the external potential. The file has a simple structure, with the standard Questaal format.

% rows    [number of -rows]
     1      v_k       rho_k
     2      v_k       rho_k
     ...

v_k and rho_k are the (complex) Fourier coefficients to the reference potential.

The dosq file

This file is created by lmdos when the --kres switch is set, which writes DOS or some related quantity (e.g. band velocity) using the tetrahedron method.

It has a structure

# q+band -resolved   3 bands  373248 qp  ef=-0.736500  microcell vol 8.93061e-7
#            -----  q  -----              tet  ib     DOS
   -0.194444    0.201389    0.208333      259   1    0.457552
   ...

The ‘microcell vol’ named in the header is the volume of one tetrahedron; also shown are the number of bands for which crossings were sought and the number of tetrahedra where crossings were found.

For each tetradron that ecompasses energy ef (or whatever energy is specified), a line is written to dosq.ext containing the q corresponding to the midpoint of tetrahedron (approximately the q where the band reaches ef), the tetrahedron index (not generally very useful), the band index, and in the DOS column, the DOS or related quantity.

The bfield file

File bfield.ext enables you to add a site-dependent external magnetic field. spin-orbit coupling matrix element by site. It is used by lmf, lm, lmgf and lmpg. For the ASA codes the field can be a proper vector, pointing in any direction. For lmf, as of this writing it must point along z. See this page for a tutorial.

This file should be in the standard Questaal format. It should contain as many lines as there are sites.

Example: Supposing there are two sites and you want to apply a magnetic field of 1 mRy to the first site and −1 mRy to the second, both along the z axis ( (remember this is the only option for lmf). Create bfield.ext as follows:

0 0 0.001
0 0 -.001

The socscl file

File socscl.ext enables you to scale the spin-orbit coupling matrix element by site. It is used by lmgf and lmpg. You must create this file, in the standard Questaal format It should contain as many lines as there are sites.

Example Supposing there are 4 sites and you want to scale L·S in the last two sites only, by a parameter soscl which you control from the command line. Create socscl.ext as follows:

% const soscl=1
1
1
{soscl}
{soscl}

and run lmgf or lmpg as, e.g.

lmgf -vsoscl=.5 ...

Selected files generated by lmf or lm for optics

File jdos

jdos.ext is generated by lmf or lm when making single or joint DOS when using the optics package (OPTICS_MODE<0)

File is written in standard Questaal format. Data is written in two, three, or four columns (depending on switch --jdosw) as:

Energy  total-DOS [Mull1] [Mull2]

See this tutorial for an example.

The opt file

When lm or lmf is run in optics mode (OPTICS_MODE>0) it generates the imaginary part of the dielectric function.

File opt.ext is written in standard Questaal format for the longitudinal components of ε as a function of frequency, as shown in the box below.

If the calculation is spin polarized, ε is resolved by spin and three additional columns are written. The resolution by spin is not physically observable, but the code resolves it anyway to enable you to distinguish the up- and down- contributions to ε. For the physically observable ε, combine spin-up and spin-down columns.

Files optdata and optdatac

These files contain matrix elements of the velocity operator. optdata.ext is written when –opt:write appears on the command-line; optdatac.ext is written when –opt:woptmc appears.

optdata.ext contains matrix elements of the square of the velocity operator (called optmt below), symmetrized over k-points, while optdatac.ext contains matrix elements of the (complex) velocity operator itself (called optmc below). It is not symmetrized.

Both files are written in binary format.

Note: optdata.ext is also used to hold joint density-of-states, made by the optics code in special modes of the OPTICS category. In that case an array jdosw is written instead of optmt.

The first two records are common to both files.

The remaining records depend on the type of file :

• nfilo, nfiup = indices to first and last bands in the “occupied channel” for which matrix elements are stored
• nfilm = nfiup−nfilo
• nemlo, nemup = indices to first and last bands in the “unoccupied channel” for which matrix elements are stored
• nempm = nemup−nemlo
• nspx = number of independent spins (1 in nonmagnetic or noncollinear cases, two otherwise)
• nkp = number of k-points
• qp(3,nkp) = vector of nkp k-points

Selected files generated by lm

The vext file

Selected files generated by lmgf or lmpg

The vshft file

File vshft.ext holds information about potential shifts used by lmgf and lmpg.

In these codes the Fermi level E_F is usually fixed and a potential shift vconst is added to make the system charge neutral for E_F.

The first line contains information about these parameters. In lmgf has a single value for vconst, e.g.

ef=-0.0850000  vconst=0.0518662

while lmpg has three, e.g.

ef=0.0000000  vconst=0.1035472 vconst(L)=0.0867085 vconst(R)=0.2418164

You can optionally add site-dependent potential shifts. After the first line, add a line site shifts followed by as many lines as desired, one line per site shift, e.g.:

ef=.03 vconst=-.01 vconst(L)=.02 vconst(R)=.03
site shifts
 3    .1
 4    .2

The moms file

File moms.h5 is generated by lmf, (there is a corresponding moms.ext generated by the ASA codes). This file contains information for DOS weights, which lmdos reads to make various kinds of DOS.

dosw        {nchan, ndhamx, nspr, nkp}       DOS weights (dcomposition of eigenvector) resolved channels for each k
ef          {1}                              Fermi energy
eval        {ndhamx,nspx,nkp}                Eigenvalues
nchan       {1}                              Number of DOS channels.  If 0, dosw need not be present
ndham       {1}                              Maximum dimension of hamiltonian, without spin
nev         {282}                            Number of eigenvalues, for each k point
nfstg       {1}                              Compound of digits indicating what this file should contain
                                             1s digit   eval
                                             10s digit  number of (moments + spin channels) : 1 moment for FP, 3 for ASA
                                             100s digit (ASA) noncollinear DOS weights
nkp         {1}                              Number of k-points
nl          {1}                              Maximum l + 1 in the system (not used)
nsp         {1}                              2 if spin polarized, otherwise 1
nspc        {1}                              2 for noncollinear case, or when spins are coupled
nspr        {1}                              nspr = nsp, unless fully relativistic (J,m_J) basis where spin and orbit are interleaved,
                                             in which case nspr=1

Files lbc and rbc

Files lbc.ext and rbc.ext are generated by lmpg. They are binary files containing information about the left- and right- surface Green’s function used to embed the active region.

As of this writing, they are written in standard binary format, but there are plans to switch to hdf5, to simplify parallel execution of lmpg.

Files jz, rzl, rzr, and jzk and rzk

These files are generated by lmpg. Files jz (rzl, rzr) are written in the standard Questaal format and contain information about the k-integrated transmission probability (jz.ext), and left- and right- reflection probablities (rzl.ext and rzr.ext).

Files jzk.h5 and rzk.h5 contain k-resolved information. They are written in hdf5 format.

dataset       dimensions                  description
 ... in file <i>jzk.h5</i>
jzk           {1, nz, nkp, nsp}           transmission (collinear case), resolved by energy, <i>k</i>, and spin.
jzk           {4, nz, nkp, nsp}           transmission (noncollinear case) also resolved into up-up, up-down, down-up, and down-down parts
jzk           {16, nz, nkp, nsp}           transmission (noncollinear case) further resolved into  up-up, up-down, down-up, and down-down parts of the lead
 ... in file <i>rzk.h5</i>
rzkl          {1, nz, nkp, nsp}           reflection at the left lead (collinear case), resolved by energy, <i>k</i>, and spin.
rzkr          {1, nz, nkp, nsp}           corresponding reflection at the right lead (collinear case)
rzkl          {4, nz, nkp, nsp}           reflection at the left lead (noncollinear case) also resolved into up-up, up-down, down-up, and down-down parts
rzkr          {4, nz, nkp, nsp}           corresponding reflection at the right lead (noncollinear case)

Selected files used or generated by the GW codes

The GW codes operate through a shell script. For the classic implementation, the main input file (analog of the ctrl file) the GWinput file, documented here.

The final step is carried out by hqpe, which assembles output generated by other executables in the GW code to assemble files suitable for reading.

In the one-shot case, the most useful file is the QPU file. In the QSGW case, it is sigm.ext which contains the quasiparticlized self-energy in a form lmf can read and add to the LDA potential.

eigen.h5

eigen.h5 contains information about eigenfunctions the GW package requires. It is generated by lmfgwd. Below is a listing of a data elements with a brief description.

dataset       dimensions                       description
alat          {1}                              length scale of lattice and basis vectors, a.u.
cphi          {ndima, ndhamx, nsp, nqirre}     coefficients to partial waves inside augmentation sphere
eigenstat     {1}                              attributes of eigenfunction and augmentation coefficients
                                               1s digit  0 cphi as generated from partial waves in sugw.f
                                                           (channel offsets are ordered (m,l,n,iat), n = radial index
                                                         1 orthogonalized
                                                         2 channels ordered (m,n,l,iat)
                                                         4 cphi scaled by factor 1/sqrt(1+0.1*n) for stability
                                               10s digit 0 for unscreened basis
                                                         1 for screened basis
eval          {ndham, nsp, nqirre}             LDA or QSGW eigenvalues
evec          {ndham, ndham, nsp, nqirr}       LDA or QSGW eigenfunctions
hmvxc         {ndham, nsp, nqirre}             diagonal matrix element for double counting, GW-LDA
lkoau         {nat, ndlko, 2}                  table of attributes of partial waves inside augmentation sphere
lmxa          {nat}                            augmentation l-cutoff
lshft         {3}                              Switches to offset regular <i>k</i> mesh along each of three axes.  Not used now.
nat           {1}                              number of atoms with an augmentation radius
nbas          {1}                              number of atoms in the basis (including sites w/out augmentation spheres)
ndham         {1}                              dimensioning parameter, largest hamiltonian dimension
ndima         {1}                              total number of augmentation channels
ndimh         {nqirre}                         rank of hamiltonian at current q (possibly q dependent).
                                               Note: ndimh is scaled by 2 when spins are coupled
nev           {nqirr}                          Number of eigenvalues calculated for a particular k
ngwf          {nqirre}                         number of G vectors in the IPW repsn of eigenfunctions
ngwfex        {1}                              dimensioning parameter: maximum value of ngwf
nkabc         {3}                              Number of divisions for regular mesh where eigenvalues, evecs are made
nlmto         {1}                              rank of LMTO part of hamiltonian, q-independent
nqbz          {1}                              number of qp in the full BZ; duplicates bz.h5
nqbze         {1}                              number of qp in the full BZ, including offset points and points on offset meshes
nqirr         {1}                              number of qp in the irreducible part of the BZ; duplicated in bz.h5
nqirre        {1}                              number of qp in the irreducible part of the BZ, including mesh for each offset Gamma, duplicated in bz.h5
nsp           {1}                              2 for spin-polarized case, otherwise 1
nspc          {1}                              Number of coupled spins (for relativistic or noncollinear magnetism)
nwr           {1}                              Number of mesh points for an evenly spaced mesh encompassing largest eval.  Spacing = delre(1).
                                               Spacing between points in actual real mesh increase linearly, specified delre(2), reducing size of mesh
ovl           {ndham, ndham, nsp, nqirr}       Overlap matrix
plat          {9}                              primitive lattice vectors, in units of alat
pos           {3, nat}                         basis vectors
pwz           {ngwfex, ndham, nsp, nqirre}     coefficients to IPW repsn of eigenfunctions
qirre         {3, nqirre}                      vector of nqirre q points, kotani ordering
version       {1}                              (historical, when file contains evecs or self-energy; no longer used)
vxc           {ndham, ndham, nsp, nqirr}       LDA contribution to exchange-correlation potential

evec.h5

evec.h5 contains information about eigenfunctions, similarly to eigen.h5, but it is used in different contexts. (At some point evec.h5 and eigen.h5 may be merged into a unified format).

Below is a listing of a data elements with a brief description.

colwt         {ndhamx, nspx, ncol, nq}         Color weights
eval          {ndhamx, nspx, nq}               LDA or QSGW eigenvalues.  ndhamx is hamiltonian rank, doubled in noncollinear case
evec          {ndhamx, ndhamx, nspx, nq}       LDA or QSGW eigenfunctions
gv            {ngmx, 3, nq}                    G vectors
lkolm         {3, ndlko, ncell, nbas}          indices <i>l</i>, radial index, offset for hamiltonian.  nscell differs from 1 only in supercell mode
ndham         {1}                              maximum hamiltonian rank
ndimh         {nq}                             rank of hamiltonian at current q (possibly q dependent).
nev           {nq}                             Number of eigenvalues calculated for a particular k
ngq           {nq}                             Number of g vectors at each q, must be less than ngmx
nq            {1}                              Number of qp
nsp           {1}                              2 if magnetic case, 1 otherwise
nspc          {1}                              2 if noncollinear case, 1 otherwise
nspx          {1}                              2 if magnetic, collinear case, 1 otherwise
plat          {3, 3}                           primitive lattice vectors, in units of alat
pwz           {ngmx, ndham, nsp, nq}           coefficients to plane wave representation of eigenfunctions, possibly envelope part only
qp            {3, nq}                          list of q points

bz.h5

bz.h5 contains information the Brillouin zone: k-points, and information about symmetry operations needed to perform rotations of objects such as eigenvectors to another k-point of equivalent symmetry It is generated by a combination of lmfgwd and qg4gw.

bz.h5 contains various forms of the following basic objects:

• A list of q points, which consist of regular mesh points and offset points
  • regular mesh points distributed on a uniformly distributed grid with nabc divisions along the parallepiped made of the reciprocal lattice vectors
  • In the context of computing the self-energy: additional points where the self-energy is to be calculated
    1. The offset-gamma method is used to handle the q→0 limit of the polarizability. They are stored in data element q0i.
       Note: this list is doubled when time-reversal symmetry is turned off; the doubled list is not included in the file data element.
    2. Optional extra points where the self-energy is to be calculated off the regular mesh.
  • In the context of computing a response function: additional points where the reponse function is to be calculated (stored in q0i).
  • data elements are q-point lists (qfbze, qfbzk, qibz, shftq, wibz) and integers keeping track of their number
    (nqbz, nqbzw, nqc, nqfbze, nqirr, nqirre, nsgrp, nstar, iqattre, nabc, nq0ix, nqfbze, nqirr, nqirre, nqbzw)
• Information about space group symmetry (ag, shftv, symgr, nsgrp, nstar, irrgk)
• Information needed for BZ integration (idtetf, idtetx, ntetf, ntetix)
• Information about lists of G vectors used to represent 1-particle and two-particle quantities
  • data elements are cutoffs (gmaxpsi, gmaxcou), G-vector lists (igve, igvce) and integers keeping track of their number
    (ngmbe, ngmbex, ngmbr, ngmbrx, ngmbx, ngwf2x, ngwfe, ngwfex, nqc)

Below is a listing of a data elements a brief description.

ag            {3, nsgrp}                       translation part of space group (see symgr)
gmaxcou       {1}                              sphere of q+G, delimiting PW cutoff for mixed basis
gmaxpsi       {1}                              sphere of q+G, delimiting PW cutoff for one-particle basis
idigv         {1}                              dimensions igvrev
idigvc        {1}                              dimensions igvcrev
idtetf        {4, ntetf}                       tetrahedron indices for tetrahedra in full Brillouin zone
idtetx        {5, ntetix}                      Modified idtet for extended irreducible k-points
igvc          {3,ngwf2x,nqc}                   G vectors for raw wave function products at the irreducible q points where coulomb interaction is calculated
igvce         {3,ngmbex,nqfbze}                G vectors for the mixed basis, for all points including offset points
igve          {3,ngwfex,nqfbze}                G vectors for the 1-particle basis, as integral multiples of reciprocal lattice vectors
iigvce        {-idigvc:idigvc,:,:,nqfbze}      inverse mapping of igvce
iigve         {-idigv:idigv,:,:,nqfbze}        inverse mapping of igve
irrmape       {nqfbze}                         index to irreducible qp among nqfbze total points this q gets rotated to
irrgk         {nqirr, nsgrp}                   irr k-point rotates to irk(iq,ig) under symop ig in qfbz
nabc          {3}                              k-point mesh spacing (number of divisions of qlat along the three directions)
ngmben        {nqfbze}                         number of mixed-basis G vectors, analog of ngmbn but for each point in full BZ
ngmbex        {1}                              (dimensioning) maxval(ngmbex)
ngmbrn        {nqc}                            like ngmbn, but number include G vectors in the star of k
ngmbrx        {1}                              (dimensioning) maxval(ngmbrn), ngmbrn(iq) = number of G vectors at iq, including G vectors in the star of iq
ngmbn         {nqc}                            number of mixed-basis G vectors, one for each each of nqc points
ngmbx         {1}                              (dimensioning) maxval(ngmbn), ngmbn(iq) = number of G vectors at iq
ngwf2n        {nqc}                            number of G vectors for raw wave function products for one k point
ngwf2x        {1}                              (dimensioning) maxval(ngwf2n), ngwf2n(iq) = number of G vectors in raw wave function products at iq
ngwfen        {nqfbze}                         number of G vectors representing wave function at each q, full bz + offset points
ngwfex        {1}                              (dimensioning) maxval(ngwfen)
nq0i          {1}                              number of offset gamma points (self-energy context) or where the response function is calculated (polarizability context)
nq0ix         {1}                              total number of offset points needed in various contexts
nqbz          {1}                              nabc(1)*nabc(2)*nabc(3)
nqc           {1}                              number of k points where coulomb interaction is calculated:  all irr points + offset Gamma
nqfbze        {1}                              number of qp in the full BZ, including mesh for each offset Gamma, duplicated in eigen.h5
nqirr         {1}                              number of qp in the irreducible part of the BZ; duplicated in eigen.h5
nqirrc        {1}                              number of qp in the irreducible part of the BZ in calculating susceptibility.  Set to 0 if not different from nqirre
nqirre        {1}                              number of qp in the irreducible part of the BZ, including mesh for each offset Gamma, duplicated in eigen.h5
nsgrp         {1}                              Number of space group operations {g,ag}
nqbzw         {1}                              not documented now
nstar         {nqirr}                          number of k-points in star of k
ntetf         {1}                              number of tetrahedra in full Brillouin zone; dimensions idtetf
ntetix        {1}                              number of tetrahedra in extended irreducible Brillouin zone; dimensions idtetx
q0i           {3,nq0i}                         offset points
wq0i          {nq0i}                           weights for q0i
qfbze         {3,nqfbze}                       list of qp in full Brillouin zone, possibly including offset points, and including offset gamma points
qfbzk         {3,nqbz}                         k-points in full BZ (possibly offset) mesh for which susceptibility is calculated, Kotani ordering
qibz          {3,nqirr}                        irreducible k-points where self-energy is calculated, lmf ordering
qibzc         {3,nqirrc}                       irreducible k-points where susceptibility is calculated
qlat          {3,3}                            reciprocal lattice vectors
shftq         {3}                              Translates the regular mesh by 1/2 division so mesh straddles Gamma point, and does not include it
shftv         {3,nsgrp}                        Similar to ag, using Kotani conventions which may cause the two to differ by a lattice vector
symgr         {3,3,nsgrp}                      rotation part of space group (see ag)
wibz          {nqirr}                          weights corresponding to qibz

Notes on compatibility with legacy code, when information was stored in files QGpsi, QGcou, QGcou2\

Headers:

1. nqfbze is also written to QGpsi and QGcou headers as ngc

2. ngwfex is also written to QGpsi header as ngmbx,ngmbrx,ngwf2x

3. nqbz is also written to QGpsi, QGcou, QGcou2 headers as nqbz

4. nqirre is also written to QGpsi and QGcou headers as nqirre

5. idigv is also written to QGpsi header as imx

6. idigvc is also written to QGcou header as imx

7. nqibz is also written to QGpsi and QGcou headers as nqibz

8. nqibzc0 is also written to QGcou2 header as nqibz

9. nqc is also written to QGcou2 header as nqc

10. ngmbx is also written to QGcou2 header as ngmbx

11. ngmbrx is also written to QGcou2 header as ngmbrx

12. ngwf2x is also written to QGcou2 header as ngwf2x

Body:

1. ngwfen is also written to QGpsi as ngmbn,ngmbrn,ngp2n

2. ngmben is also written to QGcou as ngmbn,ngmbrn,ngp2n

3. ngmbn is also written to QGcou2 as ngmbn

4. ngmbrn is also written to QGcou2 as ngmbrn

5. ngwf2n is also written to QGcou2 as ngp2n

atom.h5

atom.h5 contains information about partial waves inside augmentation spheres. It is generated by lmfgwd. Below is a listing of a data elements with a brief description.

dataset       dimensions                       description
a             {nclass}                         radial mesh parameter (rmeshprm.f)
class         {nat}                            index to class for each site
ecore         {ncorex, nsp, nat}               core levels
gcore         {nr, ncorex, nsp, nat}           core partial waves
gval          {nr,lmxax+1,nphimx,nsp,nclass}   valence partial waves
konf          {lmxax+1, nclass}                valence P.Q.N. for each partial wave
lmxa          {nclass}                         augmentation <i>l</i> cutoff
lmxax         {1}                              dimensioning parameter, maxval(lmxa)
lmxlx         {1}
nat           {1}                              number of atoms with an augmentation radius
nclass        {1}                              number of classes
ncore         {nclass}                         number of core levels/spin
ncorex        {1}                              dimensioning parameter, maxiumum number of core levels on an atom = maxval(ncore)
ncorexl       {1}                              maxiumum number of core functions for one <i>l</i>
nphimx        {1}                              dimensioning, Max no. partial waves for a given <i>l</i>
nr            {nclass}                         number of radial mesh points (partial waves)
nrmx          {1}                              dimensioning, maxval(nr)
nsp           {1}                              number of spins
quadtyp       {1}                              radial quadrature type (rmeshprm.f)
rho1          {nrmx, nlmlx, nsp, nat}          True valence density
rhoc          {nrmx, nsp, nat}                 True core density
rmt           {nclass}                         augmentation sphere radius
z             {nclass}                         nuclear charge

pb.h5, pbc.h5, pbb.h5

pb.h5 contains information about the product basis B for each site, for valence partial waves; pbc.h5 contains the same information but for core states.

pbb.h5 contains related information but for a double product basis ᗷ, which is constructed from products B × B.

All of these files are generated by lmfgw. Below is a listing of elements in pb.h5 and pbc.h5, with a brief description of each.

Note: pb.h5 may also be written in “extended” format. This is the format the 2022 version of the GW code uses. (Its elements are similar the contents of the binary files the legacy GW code used.)
Element  format  distinguishes whether the extended or compact format is used. The elements and description below can may aply to both formats, or to one only.

dataset       dimensions                       description
a             {nbas}                           radial mesh parameter for augmentation spheres (rmeshprm.f)
b             {nbas}                           radial mesh parameter for augmentation spheres (rmeshprm.f).
                                               For the radial mesh, point <i>i</i> corresponds to radius <i>b</i>&thinsp;[exp[<i>a</i>&thinsp;(<i>i</i>&minus;1)&minus;1]
aa                                             Symbol used for a in format style 1
bb                                             Symbol used for b in format style 1
format        {1}                              Format in which product basis is stored.  1 for compact, 2 for mixed (expanded) used by 2022 version
lmxb          {1}                              <i>l</i>-cutoff for product basis (format style 2)
nl                                             1+<i>l</i>-cutoff for product basis (format style 1)
lpbmx         {1}
nat           {1}                              Number of sites with augmentation spheres
nclass        {1}                              Symbol used for nat when writing in format style 1
nblr          {0:2&times;lmxb, nat}                  Number of radial functions for each <i>l</i>.  Formerly named nxx in legacy GW code
nxx                                            Symbol used for nblr when writing in format style 1
nxxcmx        {1}                              (?) format style 1 only
nxxmx         {1}                              dimensions ppbrd and rprod (format style 1)
ncoremx       {1}                              Dimensioning parameter : maximum number of core levels at one site
ndrpb         {1}                              Maximum number of radial functions for a given <i>l</i> at any site = maxval(nblr)
                                               ndrpb(1) for regular product basis functions; ndrpb(2) for grad+ functions; ndrpb(3) for grad- functions
ndrphi        {1}                              Dimensioning parameter : max number of core + valence radial functions for any </i>l<i>
nn                                             Symbol used for ndrphi when writing in format style 1
nphimx        {1}                              Dimensioning parameter : max number of valence partial waves for any <i>l</i>
nr            {nat}                            Number of radial mesh points
nrofi         {nat}                            Symbol used for nr when writing in format style 1
nradpb        {3}                              Total number of radial product basis functions, all <i>l</i> and sites = sum_sites(nblr(:))
                                               nradpb(1) for regular product basis functions; nradpb(2) for grad+ functions; nradpb(3) for grad- functions
nrmx          {1}                              Dimensioning parameter:  global maximum number of radial mesh points
nrpb          {0:2&times;lmxb, nat}                  Cumulative number of radial product basis functions for a particular <i>l</i> and site.
                                               Functions nrpb(l,iat):nrpb(l+1,iat) are the family of radial B functions
                                               stored in rprodb for quantum number <i>l</i> and site iat.
nrphiv:       {0:lmxb, nat}                    number of valence partial waves for this l and site
nrphic:       {0:lmxb, nat}                    number of core partial waves for this l and site
nsp           {1}                              1 for nonmagnetic case, 2 for spin polarized case
ntpba         {nat}                            ntpba(iat) = number of full product basis functions at site iat (format style 2)
                                               formerly named nblocha or mdim in legacy GW code
nblocha       {nat}                            Symbol for ntpba when written in format style 1
rmt           {nat}                            Augmentation sphere radius.  Note that a,b,rmt are not all independent
rprbme        {0:lmx,ndrphi,0:lmx,ndrphi,nsp,nradpb}  Matrix elements of the product basis (format style 2)
ppbrd         {nl,ndrphi,nl,ndrphi,2&times;nl-1,nxxmx,nsp,nat}  Same info as rprbme, written in expanded format 1
rprodb        {nrmx,nradpb}                    Radial part of product basis functions B (format style 2)
rprod         {nrmx,nxxmx,2&times;nl-1,nat}          Same info as rprodb, written in expanded format 1

pbb.h5 has a two other elements

dataset       dimensions                       description
rprbme        {0:lmx,ndrphi,0:lmx,ndrphi,nsp,nradpb}  Analog of rprbme, but for double product basis
rprdbb        {nrmx,nrdpbb}                    Radial part of double product basis functions

vc.h5, vcc.h5

File vc.h5 contains matrix elements of the coulomb integral : the bare coulomb interaction sandwiched between product basis functions. These coulomb integrals are how Questaal constructs the Fock matrix. One coulomb matrix is generated for every irreducible k-point and offset-Γ point. The sum of these is the total number of k-points, nqibze.

vcc.h5 contains the same matrix elements but for core product basis functions.

Let ngmbx be the maximum number of plane waves at any k-point and ntpb be the total number of product basis functions B inside augmentation spheres. Then the maximum dimension of the mixed basis is ntmb=ngmbx+ntpb.

Below is a listing of elements in vc.h5 with a brief description of each.

dataset       dimensions                       description
ngb           {nqibze}                         Dimension of the mixed product basis, one number for each of the nqibze points
qirre         { 3, nqibze}                     <i>k</i> points where the matrix elements are stored
ve            { ntmb, nqibze}                  Eigenvalues of the coulomb matrix
vv            { ntmb, ntmb, nqibze}            Eigenvectors of the coulomb matrix

pqmap

The pqmap file is “helper” file used by the new GW implementation, which can help this code accelerate performance on HPC architectures.

pqmap files are in ASCII format and you can generate it by hand, but it can be troublesome to do so. The easiest way is to have lmfgwd do it for you. A greater description of this file is given here, and this tutorial provides an example of how to autogenerate one with lmfgwd.

There can be several kinds of pqmap files, all with the same structure. The file’s actual name is pqmap-#, where # is the number of cores. Thus you can have several pqmap files in one directory, each for a different set of cores. You can also have a file pq0map-#, which is a pqmap for the offset-Γ points.

They begin with a header consisting of three integers in two lines:

max-steps  nproc
nq

• max-steps is the maximum number of loops over qk combinations any one process must make (see below).
• nproc is number of MPI processes the job has
• nq is number of q points for which the self-energy is made

Then follow nq lines, one line for each q. Each line has the structure

first-step first-proc  nsteps   nproc    iq

Think of the work mapped out on a canvas of contiguous squares like a chessboard (the color doesn’t matter); each qk combination takes one square on the canvas. The rows of the canvas correspond to a cycle or step number, and the columns to a particular MPI process. All the k that belong to one q are combined and treated together. Pictorially this combination of k can be viewed as a rectangle on the pqmap canvas. The entire canvas then is filled up with rectangles; each qk belongs in the rectangle associated with that q.

For each q, pqmap specifies the row and column offset (when to start the cycle, and the first MPI process associated with the cycle) and a row and column dimension (number of steps and number of MPI processes). The meaning of the five numbers on a row of pqmap is then:

• first-step : offset to starting cycle for this block
• first-proc : First MPI process to assign to this block
• nsteps : number of cycles this block of k will require
• nproc : number of processes this block of k will require
• iq : the q index associated with this block

QPU

Note: QPU is a legacy file from the old GW code. It is no longer generated. QPU (and in the spin polarized case QPD) contain the main results of a GW calculation in an easy-to-read format. An example of this file for a one-shot calculation is shown below. In the QSGW case, the file is slightly different; for example there is no Z factor.

E_shift= -0.1135090155598752D+01 -0.1902823497322418D+01 -0.2111434832164544D+01 eV
           q               state  SEx   SExcore SEc    vxc    dSE  dSEnoZ  eLDA    eQP  eQPnoZ   eHF  Z    FWHM=2Z*Simg  ReS(elda)
  0.00000  0.00000  0.00000  4  -14.80  -1.95   3.07 -13.59  -0.07  -0.09  -1.45  -2.28  -2.51  -3.47 0.79   0.00000    -13.68005
  0.00000  0.00000  0.00000  5   -4.82  -1.40  -4.58 -11.77   0.75   0.97   1.10   1.09   1.09   7.78 0.78  -0.02563    -10.80323

 -0.50000  0.50000  0.50000  4  -14.63  -1.91   3.15 -13.28  -0.09  -0.12  -2.64  -3.50  -3.73  -4.77 0.77   0.00000    -13.39330
 -0.50000  0.50000  0.50000  5   -4.99  -2.15  -4.54 -12.66   0.77   0.98   0.00   0.00   0.00   6.65 0.79   0.00000    -11.68493

  0.00000  0.00000  1.00000  4  -14.39  -1.69   3.41 -12.58  -0.07  -0.09  -4.30  -5.14  -5.37  -6.67 0.77   0.09531    -12.66525
  0.00000  0.00000  1.00000  5   -4.20  -0.92  -4.24 -10.31   0.77   0.96  -0.82  -0.82  -0.84   5.51 0.81  -0.00000     -9.35651

The first line contains three energy shifts eLDA, eQP and eQPnoZ that are needed to set a particular state n (e.g. a valence band maximum) to zero. In the Table above, this was state 5 at the second k-point. These shifts are determined by hqpe. You can control how they are set by running lmgw with --insul=n.

The columns have the following meaning, and define eLDA, eQP, and eQPnoZ:

1. q :   k point.
2. state :   Band index n, with n=1 corresponding to lowest eigenvalue.
3. SEx :   $\langle \Psi_{\mathbf{q}n} | \Sigma_\mathrm{x} | \Psi_{\mathbf{q}n}\rangle$ where ${\Sigma_\mathrm{x}}$ is the exchange potential computed from valence + core2 levels.
   The division of core levels into core1 and core2 is desribed in Section IIB of Phys. Rev. B76, 165106 (2007).
4. SExcore :   $\langle \Psi_{\mathbf{q}n} | \Sigma_\mathrm{x} | \Psi_{\mathbf{q}n}\rangle$ where ${\Sigma_\mathrm{x}}$ is computed from core1 levels.
5. SEc :   $\langle \Psi_{\mathbf{q}n} | \Sigma_{c}(\epsilon_{\mathbf{q}n}) | \Psi_{\mathbf{q}n}\rangle$ where ${\Sigma_{c}}$ is the correlation self-energy computed from valence + core2 levels.
6. vxc :   LDA exchange correlation energy $\langle \Psi_{\mathbf{q}n} \mid V_\mathrm{xc}^\mathrm{LDA}[n^\mathrm{tot}] \mid \Psi_{\mathbf{q}n}\rangle$ generated by lmf, used to subtract from the GW self-energy to get QP shifts.
   Note: If you carry out a 1-shot calculation with the QSGW as a starting point (lmgw --vxcsig), vxc is the QSGW self energy.
7. dSE :   QP shift relative to LDA including a Z factor, $Z_{\mathbf{q}n} \times \mathrm{dSEnoZ}$.
8. dSEnoZ :   QP shift relative to LDA without a Z factor : $\langle \Psi_{\mathbf{q}n} \mid \Sigma_\mathrm{x}^\mathrm{core1} + \Sigma^\mathrm{val+core2}_{xc}(\epsilon_{\mathbf{q}n}) - V_\mathrm{xc}^\mathrm{LDA}[n^\mathrm{tot}] \mid \Psi_{\mathbf{q}n}\rangle$ .
9. eLDA :   LDA eigenvalues $\epsilon^\mathrm{LDA}_{\mathbf{q}n}$, generated by lmf.
   Note: If you carry out a 1-shot calculation with the QSGW as a starting point, eLDA is the the QSGW level generated by lmf.
10. eQP :   QP level with shift computed including the Z factor, $\epsilon^\mathrm{LDA}_{\mathbf{q}n} + \mathrm{dSE}$.
11. eQPnoZ :   QP level with shift computed omitting the Z factor, $\epsilon^\mathrm{LDA}_{\mathbf{q}n} + \mathrm{dSEnoZ}$.
12. eHF :   Hartree Fock energy $\epsilon^\mathrm{LDA}_{\mathbf{q}n} + \mathrm{SEx} + \mathrm{SExcore} - \mathrm{vxc}$.
13. Z :   Z factor, $Z_{\mathbf{q}n}=(1-\partial \Sigma_\mathrm{c}^\mathrm{core2+valence}(\epsilon)/\partial\epsilon)^{-1}$ evaluated at $\epsilon_{\mathbf{q}n}$.
14. FWHM :   $2 Z_{\mathbf{q}n} \times \mathrm{Im} \langle\Psi_{\mathbf{q}n}\mid \Sigma_\mathrm{c}^\mathrm{core2+valence}(\epsilon_{\mathbf{q}n})\mid\Psi_{\mathbf{q}n}\rangle$. This quantity is related to the quasiparticle lifetime.
15. ReS(elda) :   $\mathrm{Re}\, \langle\Psi_{\mathbf{q}n}\mid \Sigma_\mathrm{x}^\mathrm{core1} + \Sigma_\mathrm{xc}^\mathrm{core2+valence}(\epsilon_{\mathbf{q}n}) \mid \Psi_{\mathbf{q}n}\rangle$

TOTE.UP and TOTE2.UP

Note: TOTE_UP is a legacy file from the old GW code. It is no longer generated.

These files (and TOTE.DN, TOTE2.DN in the spin polarized case) contain a portion of the information in QPU file, but with more decimal places of precision.

TOTE.UP contains LDA and quasiparticle energies. These values are relative to a Fermi energy determined by the a Gaussian sampling integration. It begins with a header line

        3        2  0.2830887881465354D+01 -0.1135090155598752D+01 -0.1902823497322418D+01 -0.2111434832164544D+01

which indicates how many k-points and states at each point are in the file, the Fermi energy, as determined by Gaussian sampling, followed by the same energy shifts for eLDA, eQP, eQPnoZ found in the QPU header. The remaining lines contain same information denoted by columns eLDA, eQP, eQPnoZ, Z in the QPU file.

TOTE.UP is similar, but the header contains no shifts; the band levels are the same as in TOTE2.UP but without the addiitional shifts. Thus these energies are relative the Fermi level printed in the header. Note: TOTE.UP contains the Fermi level in Ry, not eV, even though the energies in the body of the file are in eV.

See Table of Contents

Selected files read or generated by lmfgws

The se file

The  se  file contains the frequency-dependent self-energy generated by the GW code. It is generated by spectral from raw GW output files SEComg.UP (and SEComg.DN in the magnetic case), for use by lmfgws. Depending on how it is invoked, spectral writes to an ASCII file file  se (which must be renamed to se.ext before invoking lmfgws to read it) or to an hdf5 file se.h5.

Routine subs/ioseh.f performs the I/O for ASCII, binary, or hdf5 format.

See this tutorial for an instance where the se file is written and read.

ASCII and hd5f formats contain essentially the same information. The hdf5 format is documented after documentation for the ASCII format.

se file, ASCII format

The file contains a header and a body; what is inthe latter is specified by file-contents given in the header. The file can be in either ASCII for binary format.
Records are as follows:

1. Header, three records
   1. has four elements: 0  version-number  file-contents  units
      (0) is a placeholder for future use.
      version-number indicates which version this file was written in. This documentation is writen for version number 4.
      file-contents indicates what the file contains.
      1s digit governs the form in which Σ(ω) is written in Step 7
      0 :   sigm(1:nw,1:nband,1:nq,1:nsp), single record
      1 :   sigm(1:nw,1:nband,iq,isp), sequence of nkp*nsp records
      2 :   sigm is written in a user-specified format – usually sigm(1:nw,1:nband)
      10s digit governs what frequency-independent self-energies are stored
      Add 1 :   QSGW Σ⁰ is stored
      Add 2 :   Exchange self-energy is stored
      Add 4 :   LDA XC potential is stored.
      100s digit governs what frequency-dependent object is stored
      0 :   diagonal parts of self-energy (complex)
      1 :   spectral function (real)
   2. has the following elements:
      [for real frequencies]     : nsp  nband  nqp  nw  ommin  ommax  mu  (Real axis flagged by nw>0)
      Elements signify : Number of spins, bands, k-points and frequencies; first and last frequency; chemical potential
      [for Matsubara frequencies] : nsp  nband  nqp  −nw  beta  mu  (Imaginary axis flagged by nw<0)
      Elements signify : Number of spins, bands, k-points and (negative of number of) frequencies; inverse temperature; chemical potential
      Note: If the chemical potential is entered by you, it should correspond to the chemical potential used by the generator of se.
      For the GW drive lmsig, you can find it with, e.g. :   grep ef lsg | tail -1| awk '{print $14}'
   3. (iqlst) list of integers indicating which bands are supplied in the file. List uses Questaal standard syntax for integer lists.
      iblst=0 flags that all 1…nband bands are given.
2. k-points qp(3,nqp), written as a single record.
3. Quasiparticle levels eig(nband,nqp,nsp), written as a single record.
   Note: these levels are saved relative to the chemical potential.
4. QP Σ⁰ = sigm(nband,nqp,nsp), in one record (written if 10s digit file-contents contains 1)
5. Fock exchange Σ_x = sex(nband,nqp,nsp), in one record (written if 10s digit file-contents contains 2)
6. LDA exchange-correlation V_xc = vxc(nband,nqp,nsp), in one record (written if 10s digit file-contents contains 4)
7. If 100s digit file-contents = 0 : $\omega$-dependent self-energy $\Sigma(\mathbf{k},\omega)$ = sigm(1:nw,1:nband,1:nq)
   If 100s digit file-contents = 1 : $\omega$-dependent spectral function $A(\mathbf{k},\omega)$
   $\Sigma$ or $A$ is written in one or multiple records, depend on 1s digit file-contents.

se file, hdf5 format

dataset dimensions description alat {1} length scale of lattice and basis vectors, a.u. cphi {ndima, ndhamx, nsp, nqirre} coefficients to partial waves inside augmentation sphere eigenstat {1} attributes of eigenfunction and augmentation coefficients

Below is a listing of a data elements with a brief description of each

dataset       dimensions                       description
ef             {1}                             Fermi energy
eval           {nband,nqp,nsp}                 One-particle energy bands
mode           {1}                             switches with information about the contents of sigma
nband          {1}                             number of bands
nblst          {1}                             Number of elements in iblst.  If missing, iblst is not present
iblst          {nblst}                         list of bands included in the self-energy
nqlst          {0:*}                           context-dependent information about q points for which bands are made
                                               nqlst(0) characterizes meaning of nqlst.
                                               nqlst(0) = 0   → no special qp list
                                               nqlst(0) = -3  → qp list corresponds to a mesh of qp on a regular 2D mesh
                                                                nqlst(1:2) specify the number of rows and columns
nqp            {1}                             number of k points in eval, sigq, sigwq
nsp            {1}                             number of spins
nspse          {1}                             number of spins in the self-energy
nw             {1}                             Number of frequency pointsn
ommax          {1}                             minimum frequency
ommin          {1}                             maximum frequency
qp             {nqp, 3}                        List of qp
sigq           {2, 29, 11}                     Static self-energy
sigwq          {2, 29, 11, 401}                Dynamical self-energy
units          {1}                             units in which data is stored (0 for Ry, 1 for eV)
version        {1}                             which version this file was written for

Files sdos, seia, pes, pesqp, spq, seq

These files are generated by lmfgws. All files are written in standard Questaal format. There are also files sdos2.ext etc corresponding to the second spin.

For a test that makes and checks many of these files, do

$ gwd/test/test.gwd fe 4 5

File sdos.ext (sdos2.ext)

Density-of-states, i.e. k integrated spectral functions. Columns are: $\omega ~ A(\omega) ~ A_0(\omega)$.

File seia.ext (seia2.ext)

Spectral function at a specific q-point. The header describes each column. Note that $\Sigma(\mathbf{k},\omega)$ is not the true self-energy. It is $\overline{\Sigma(\mathbf{k},\omega)} = \Sigma(\mathbf{k},\omega) - \Sigma^0(\mathbf{k},\omega)$ the last is subtracted so that $\overline{\Sigma(\mathbf{k},\omega)} = 0$ at the QP level.

File pes.ext (pes2.ext)

Simulation of photoemission spectra.

File pesqp.ext (pesqp2.ext)

Simulation of photoemission spectra from noninteracting $A^0(\omega)$. Works with SO coupling.

File spq.ext

Contains the Spectral function in the form of an se file. lmdmft will generates this file on a mesh, to enable further processing e.g. plbnds can make an “interacting band” plot of the spectral function. For an example, see this tutorial.

File seq.ext

Contains the self-energy in the form of an se file. lmdmft will generates this file on a mesh, to enable further processing.

See Table of Contents

Selected files read or generated by lmfdmft

lmfdmft requires an independent input file to make an interface to a CTQMC solver. For the Haule solver, this is indmfl.ext. A file sig.inp containing the DMFT self-energy in the correlated subspace. This is generated by the CTQMC solver, but a template must be created. lmfdmft will do this automatically. Other files lmfdmft generates as a regular part of the DMFT cycle are the hybridization function delta.ext, and for the Haule code eimp1.ext All of these files are described here.

Additionally lmfdmft can create for different purposes a projection of the Green’s function $G_{\mathrm{loc}}$ into the correlated subspace, either k integrated (gloc.ext) or k resolved (gkloc.ext) or the interacting, k resolved G, not projected onto a subspace.

Files sig.inp, gloc, and gkloc

sig.inp, gloc.ext, and gkloc.ext all have similar formats. There may be a header line supplying additional information. Next follow one line for each frequency, which contains (e.g. for sig.inp)

freq   Re Sig1     Im Sig1   Re Sig2     Im Sig2

for as many channels as exist in the subspace. For the CTQMC solver freq is understood to be an imaginary number.

gloc.ext, and gkloc.ext are created with the switch –gprt.

File gk

When G is written in the basis of eigenfunctions (–gprt~mode=8), it is written as a binary file into gk.ext, owing to its large size.

The records are written as follows:

The first pair records are written only once:

1. Dimensioning parameters
   • ndham   rank of 1-body hamiltonian
   • nomg   number of frequencies written
   • nkfbz   Total number of k points
   • n123   No. divisions for the 3 reciprocal lattice vectors into microcells
   • lsigim   0 or 1 depending on whether frequencies are real or imaginary
2. omega contains the vector of nomg frequencies.

The next pair of records are written for each frequency (1:nomg) and k point (1:nkfbz).

1. Indexing and k point information:
   • iomg = frequency index
   • nlo,nhi = first and last eigenstate written for this G
   • iqfbz = k point index
   • iq = irreducible k point indexfrom which this point was generated
   • iv = triplet of indices i₁,i₂,i₃, to microcell in the full Brillouin zone
   • qpr = k point in units of 2π/a
2. G in the basis of 1-particle eigenstates

See Table of Contents