# Questaal Data files and their Formats

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

You can generate this file 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.

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

##### Symmetry line mode

This is the default mode. 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, or if you use --band~mq, they refer to multiples of the three primitive reciprocal lattice vectors.

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, output from symmetry line mode

Bands are written to file bnds.ext in a format specially tailored to symmetry lines.

The file begins with

 36  -0.02136     2  col= 5:9,14:18  col2= 23:27,32:36
41                                           &larr; number of points on this line
0.50000   0.50000   0.50000                  &larr; first k point&thinsp; &darr; 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 ki (3 numbers).
2. one or more lines with the energy levels for ki
3. If color weights are present, information about color weights, consisting of
• a line containing ki (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. ##### 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. When this switch is set, lm (or similar programs that do numerical integrations over the Brillouin zone) will save information about the k-points it uses for integration to file qpts.ext. List mode can read this format; there is some flexibility in the format also. As a minimum the first line should consist of nkp=#, which specifies the number of k-points in the file. Then follows a list of k-points, e.g.  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, output from 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. ##### 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 one line of the form <i>v<sub>x</sub> range n<sub>x</sub> v<sub>y</sub> range n<sub>y</sub> height band</i>  where: • vx and vy are two reciprocal lattice vectors defining a plane • range is a pair of numbers marking starting and ending points along each vector • nx and ny are the number of divisions along the first and second vectors • height specifies the offset normal to the plane • band specifies which band is to be saved. By default, vx and vy are in Cartesian coordinates, in units 2π/a. The --band~mq~con form declares vx and vy to be fractional multiples of reciprocal lattice vectors. Example:  1 0 0 -1 1 51 0 1 0 -1 1 51 0.00 4,5  ##### bnds file, output from 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 See this example. ##### 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. There are two ways to transform the $\mathbf{k}$ point. The first is to use the ~rot options to the --band switch. The second expressions which you specify in the first line of the k-points input file. This line consists of a sequence of algebraic expressions, which generate one or more of kx, ky, or kz, which modifies one of more of the Cartesian components of $\mathbf{k}$. To modify kx, ky, or kz insert a line at the beginning of the file. The first character must be a ’%’, followed by one or more strings with algebraic expressions defining the x-, y, and z components of the modified q: % [var=expr var=expr ...] kx=expr ky=expr kz=expr  kx, ky, kz are the Cartesian coordinates of the modified k-point. expr are algebraic expressions involving these variables:  qx kx qy ky qz kz q |k|=[kx2+ky2+kz2]1/2  The expression should be integer (returning 0 or nonzero). Example: let qx, qy, qz, q be the Cartesian components and absolute value of the unmodified k-point. Any of the kx=expr ky=expr kz=expr may be present; any missing component will be left unchanged from its original value. This example (in symmetry line mode) modifies kx such that the kinetic energy is increased by 0.12 a.u. % map kx=(q^2+.1^2-qy^2-qz^2)^.5 41 .5 .5 .5 0 0 0 L to Gamma ...  You should verify that code reading the k-points modified the q points by inspecting the output. It should contain the following lines:  suqlst: map qp using the following: kx=(q^2+.1^2-qy^2-qz^2)^.5  The ~rot option may be used in conjuction with the modification through alegbraic expresssions. For example suppose you want to modify $k_\perp$ normal to the (1,-1,0) direction, while preserving $k_\parallel$ in the (1,1,0),(0,0,1) plane. Take Cu as a concrete example. If lm is your top-level directory, set up the calculation for Cu with ~/lm/fp/test/test.fp cu 1  This should set up a self-consistent potential for Cu and save generate energy bands in file bnds.cu-pwmode11. The input file as constructed uses the normal Cartesian coordinates for a cube. But if you invoke lmf with -vrot=t, viz lmf -vrot=t cu --showp  you will see that tag STRUC_ROT=z:pi/4 appears in the preprocessed input file. This tells lmf to rotate the crystal axes, the basis vectors, and the symmetry group operations. This rotates (1/2,1/2,0) to the -z axis. Do the following: $ lmf -vrot=t cu --quit=ham


and you should see:

           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


Run the band calculation exactly as was done in the test case, but modify it as follows. Replace the original

$lmf --no-iactiv cu -vnk=8 -vbigbas=t -vpwmode=11 -voveps=0d-7 --band:fn=syml  with: $  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'

• –rs=101 tells the charge density reader to rotate the local densites (the density was generated in the unrotated coordinate system).
• –band~rot= is necessary because lmf will not automatically rotate the k-points read from the syml.ext.

Run a modifed band pass calculation and compare bnds.cu with bnds.cu-pwmode11. You should see that the k-points are different, but that the bands are essentially identical. (There are slight differences relating to the numerical instabilities in the overlap originating from the addition of APW’s.)

This shows that the bands are replicated in the rotated coordinate system.

Finally, modify syml.cu by uncommenting the first line so it reads:

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


and repeat the lmf band pass. You should see that kx and ky are unchanged, but kz is slightly modified. Similarly the bands are slightly modified.

#### The basp file

File basp.ext contains information about the lmf basis set. In the Bi2Te3 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.

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

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

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

How 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−EF.
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.extmay alternatively be written in standard Questaal format for 2D arrays (if generated using, e.g. --dos@rdm).

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

 ω εx εy εz

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.

 1 Efermi ndham nsp nkp 2 evals(1:ndham,1:nsp,1:nkp)

The remaining records depend on the type of file :

 3. (optdata) nfilm nempm nspx nkp 4. (optdata) optmt(1:3,nfilo:nfiup,nemlo:nemup,nspx,nkp) 3. (optdatac) nfilo nfiup nemlo nemup nspx nkp qp nkp 4. (optdatac) optmt(1:3,nfilo:nfiup,nemlo:nemup,1:nspx,1:nkp) 5. (optdatac) optmc(1:3,nfilo:nfiup,nemlo:nemup,1:nspx,1:nkp)
• 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 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 EF is usually fixed and a potential shift vconst is added to make the system charge neutral for EF.

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

##### Files lbc and rbc

These files 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

##### Files jz, jzk and rzl,rzr

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

#### Selected files generated by the GW codes

The GW codes operate through a shell script. 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.

##### QPU

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

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.

#### 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 lmfgwsspectral writes to file  se; it must be renamed to se.ext for lmfgws to read it.

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. 0  version-number  file-contents  units
The first element (0) is a placeholder for future use.
This documentation is written for version-number=4.
1s digit file-contents governs how Σ(ω) 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 file-contents governs what frequency-independent self-energies are stored
Add 1 :   QSGW Σ0 is stored
Add 2 :   Exchange self-energy is stored
Add 4 :   LDA XC potential is stored.
100s digit file-contents governs what frequency-dependent object is stored
0 :   diagonal parts of self-energy (complex)
1 :   spectral function (real)
2. [for real frequencies]     : nsp  nband  nqp  nw  ommin  ommax  mu  (Real axis flagged by nw>0)
[for Matsubara frequencies] : nsp  nband  nqp  −nw  beta  mu  (Imaginary axis flagged by -nw<0)
Number of spins, bands, k-points and frequencies; first and last frequency; chemical potential  (nw>0)
Number of spins, bands, k-points and (negative of number of) frequencies; inverse temperature; chemical potential  (nw<0)
3. list of bands entering into spectral function, using Questaal standard syntax for integer lists.
If 0, bands comprise 1…nband
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 Σ0 = 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 Vxc = 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.

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

Routine subs/ioseh.f performs the I/O.

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

#### 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:

 1. ndham nomg nkfbz n123 lsigim 2. omega(1:nomg) cycled for each frequency and k point: 1. iomg nlo nhi iqfbz iq iv qpr 2. G(nlo:nhi,nlo:nhi)

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 i1,i2,i3, to microcell in the full Brillouin zone
• qpr = k point in units of 2π/a
2. G in the basis of 1-particle eigenstates