# 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
- Site files
- The restart file
- Positions file
- The
*qpts*file - File formats for k-point lists
- 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 - Selected files generated by
**lm** - Selected files generated by
**lmgf**or**lmpg** - Selected files used or generated by the GW codes
- Selected files read or generated by lmfgws
- Selected files read or generated by lmfdmft

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

- In some cases
- 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*.

#### 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*_{0}, *Q*_{1}, *Q*_{2}.

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

##### Symmetry line mode

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

*Note:* *lmchk* will automatically generate this file for you with the `--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, 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 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*:- a line containing
*k*(3 numbers)._{i} - one or more lines with the energy levels for
*k*_{i} - If color weights are present, information about color weights, consisting of
- a line containing
*k*(3 numbers) (should be the same as (1))_{i} - one or more lines with the color weights (should have the same format as (2)

- a line containing
- If a second set of color weights is present, there are lines similar to (3).
- If in a spin-polarized calculation with both spins present, the same information (1-4) is written for the second spin.

- a line containing

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*k*qy_{x}*k*qz_{y}*k*q |_{z}**k**|=[*k*_{x}^{2}+*k*_{y}^{2}+*k*_{z}^{2}]^{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 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:

and*v*_{x}are two vectors on the reciprocal lattice that define a parallelepiped, as well as the orientation of the parallelepiped’s plane.*v*_{y}is a pair of numbers marking starting and ending points along each vector*range*and*n*_{x}are the number of divisions along the first and second vectors*n*_{y}specifies the*height*| origin*k*point in the center of the parallelepiped. Select one of the two options:is a sequence of three real numbers, specifying a vector in reciprocal lattice, either in cartesian coorindates or, if*origin*`mq`

is supplied, as multiples of the reciprocal lattices.specifies the origin (a vector) as*height*.*height*· (*v*×_{x}*v*) / |_{y}*v*×_{x}*v*|_{y}

is an integer list specifying which band(s) are to be written to the output.*band*

By default, ** v_{x}**,

**, and**

*v*_{y}**are in Cartesian coordinates, in units 2**

*origin**π*/

*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, 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*

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, normal to the surface is modified on exiting the surface, whereas is conserved. This means that measured by ARPES slightly different from 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 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 *k*_{x}, *k*_{y}, or *k*_{z}, which modifies one of more of the Cartesian components of .

To modify *k*_{x}, *k*_{y}, or *k*_{z} 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=exprvar=expr...] kx=exprky=exprkz=expr

**kx**, **ky**, **kz** are the Cartesian coordinates of the modified *k*-point. *expr* are algebraic expressions involving these variables:

qxkqy_{x}kqz_{y}kq |_{z}k|=[k_{x}^{2}+k_{y}^{2}+k_{z}^{2}]^{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 *k _{x}* such that the kinetic energy is increased by 0.1

^{2}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 normal to the (1,-1,0) direction, while preserving 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 *k _{x}* and

*k*are unchanged, but

_{y}*k*is slightly modified. Similarly the bands are slightly modified.

_{z}#### 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 as a good quantum number and there is one radial function for each . 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 . 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.

#### The *basp* file

File *basp.***ext** contains information about the *lmf* basis set. In the Bi_{2}Te_{3} 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 *spf*n*.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:*

*A*is the spectral function.- The frequency is
*ω*=*E−E*_{F}. - 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**. - 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}
```

```
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 **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 generic file elements 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
```

*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
- 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. - Optional extra points where the self-energy is to be calculated off the regular mesh.

- The offset-gamma method is used to handle the
- 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**)

- regular mesh points distributed on a uniformly distributed grid with
- 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**)

- data elements are cutoffs (

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 intermediate stages, before merging files QGpsi, QGcou, QGcou2 . Headers:

nqfbze is also written to QGpsi and QGcou headers as ngc

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

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

nqirre is also written to QGpsi and QGcou headers as nqirre

idigv is also written to QGpsi header as imx

idigvc is also written to QGcou header as imx

nqibz is also written to QGpsi and QGcou headers as nqibz

nqibzc0 is also written to QGcou2 header as nqibz

nqc is also written to QGcou2 header as nqc

ngmbx is also written to QGcou2 header as ngmbx

ngmbrx is also written to QGcou2 header as ngmbrx

ngwf2x is also written to QGcou2 header as ngwf2x

body

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

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

ngmbn is also written to QGcou2 as ngmbn

ngmbrn is also written to QGcou2 as ngmbrn

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 generic file elements 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 l 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 l
nphimx {1} dimensioning, Max no. partial waves for a given l
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
```

*pqmap*

The *pqmap* file is used by the new *GW* implementation to accelerate performance on HPC architectures. It begins 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*

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

**q**:**k**point.**state**: Band index*n*, with*n*=1 corresponding to lowest eigenvalue.**SEx**: where 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).**SExcore**: where is computed from core1 levels.**SEc**: where is the correlation self-energy computed from valence + core2 levels.**vxc**: LDA exchange correlation energy 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.**dSE**: QP shift relative to LDA including a*Z*factor, .**dSEnoZ**: QP shift relative to LDA without a*Z*factor : .**eLDA**: LDA eigenvalues , 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*.**eQP**: QP level with shift computed including the*Z*factor, .**eQPnoZ**: QP level with shift computed omitting the*Z*factor, .**eHF**: Hartree Fock energy .**Z**:*Z*factor, evaluated at .**FWHM**: . This quantity is related to the quasiparticle lifetime.**ReS**(elda) :

*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 *lmfgws*. *spectral* 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:

- Header, three records
- 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 Σ^{0}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) - 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 - list of integers indicating which bands are supplied in the file. List uses Questaal standard syntax for integer lists.

An entry**0**flags that all 1…*nband*bands are given.

- has four elements:
**k**-points**qp(3,nqp)**, written as a single record.- Quasiparticle levels
**eig(nband,nqp,nsp)**, written as a single record.*Note:*these levels are saved relative to the chemical potential. - QP Σ
^{0}=**sigm(nband,nqp,nsp)**, in one record (written if 10s digit**file-contents**contains 1) - Fock exchange Σ
_{x}=**sex(nband,nqp,nsp)**, in one record (written if 10s digit**file-contents**contains 2) - LDA exchange-correlation V
_{xc}=**vxc(nband,nqp,nsp)**, in one record (written if 10s digit**file-contents**contains 4) - If 100s digit
**file-contents**= 0 : -dependent self-energy =**sigm(1:nw,1:nband,1:nq)**

If 100s digit**file-contents**= 1 : -dependent spectral function

or 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: .

- File
*seia.***ext**(*seia2.***ext**) - Spectral function at a specific q-point. The header describes each column. Note that is not the true self-energy. It is the last is subtracted so that at the QP level.

- File
*pes.***ext**(*pes2.***ext**) - Simulation of photoemission spectra.

- File
*pesqp.***ext**(*pesqp2.***ext**) - Simulation of photoemission spectra from noninteracting . 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.

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

- 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

**omega**contains the vector of**nomg**frequencies.

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

- 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*_{1},*i*_{2},*i*_{3}, to microcell in the full Brillouin zone**qpr**=*k*point in units of 2π/*a*

*G*in the basis of 1-particle eigenstates