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.

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:

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 first line declares dimensions used to generate the file: nqp is the number of q-points in IBZ, nkabc is the token &THINSP;NKABC&THINSP;, lshft has the same meaning as the token BZJOB , ntet is the number of tetrahedra for each microcell in irreducible Brillouin zone.

Next come the list of k points, together with the k point weights.

Next come information about tetrahedra: the second column is the number of occurences of the tetrahedron, 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. See this tutorial for a demonstration using the full-potential code lmf in this mode, and this tutorial using the ASA code lm.

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:

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 ki (3 numbers).

one or more lines with the energy levels for ki

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)

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.

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.

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 calculatormcx. 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=expr][,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~...

The mesh is specified by a file containing lines of the form

vx range nx vy range ny height band

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.

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 calculatormcx 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).

Transformation of the supplied k-points

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 kx, ky, or kz, which modifies one of more of the Cartesian components of .

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=exprky=exprkz=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 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:

–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 wkp file

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

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

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:

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, symmetrized over k-points, while optdatac.ext contains matrix elements of the velocity operator itself. It is not symmetrized.

Both files are written in binary format. 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

4. (optdatac)

optmt(1:3,nfilo:nfiup,nemlo:nemup,nspx,nkp)

5. (optdatac)

optmc(1:3,nfilo:nfiup,nemlo:nemup,nspx,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 nkpk-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 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.

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.

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

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:

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.

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.