The pldos utility

pldos is designed to make figures of partial densities-of-states (DOS).

It can generate postscript files directly, but this utility is mostly used to render data files generated by Questaal codes into a simple, easy-to-read format. pldos also makes a script for the fplot graphics utility, but the simple data format is suitable for use by any graphics package.

Table of Contents

• Preliminaries
• 1. Introduction
• 2. Examples
• 3. pldos manual
  • Command line switches
• 4. Other resources

Preliminaries

Executables pldos and fplot, are required and are assumed to be in your path. You will also need a postscript viewer. This document assumes you are using the Apple-style open command to view postscript files.

1. Introduction

Densities-of-states (DOS) tell us a great deal about the electronic structure of a system. Many programs in the Questaal suite make DOS for noninteracting hamiltonians, e.g. lm,  lmf,  and tbe. These packages write DOS information directly, to file dos.ext, or create band weights to enable the postprocessing tool lmdos to decompose the DOS into partial contributions. The Green’s function codes lmgf and lmpg can also make DOS or partial DOS by integrating the imaginary part of G over the Brillouin zone for a particular energy, and rastering over energies. See here for a brief description to make the partial DOS, written in the same format as lmdos or lmf.

Some codes make DOS, or spectral functions, for hamiltonians in which the Green’s function does not consist of a collection of sharp poles at the quasiparticle levels. Poles can be broadened by interactions, which at the one-particle level gives rise to a frequency-dependent, complex self-energy Σ(k,ω).

The GW approximation makes such a Σ; this GW tutorial gives a little bit of theory explaining how the Green’s function is modified by interactions. It also presents a tutorial to calculate and analyze Σ(k,ω) in Fe.

Dynamical Mean Field theory makes a k-independent (single-site) Σ(ω), but the Σ(ω) it does make includes all local diagrams. This tutorial explains how to carry out a DMFT calculation. One complication is that DMFT calculations are carried out on the Matsubara axis.

The Coherent Potential Approximation, or CPA, which replaces disorder by an effective single site self-energy Σ(ω). Even though the hamiltonian is non-interacting, disorder gives rise to a complex, frequency-dependent Σ, similar to the DMFT form. This document explains how to compute spectral functions for disordered systems (either chemical disorder or spin disorder) using the lmgf code.

pldos is designed only to analyze files written in the format lmf or lmdos use. It will provide a synopsis of its usage by typing:

$ pldos --h

2. Examples

This example presents a study of the density-of-states in Cr₃Si₆. The same materials system is illustrated in the tutorial on partial densities-of-states. Here we focus on the operation of pldos.

Create a fresh working directory and copy an already prepared DOS file for Cr₃Si₆,  pdos.cr3si6, to it. You can find this file in your clone of the Questaal repository. Assuming your repository resides in directory ~/lm, do:

$ cp ~/lm/fp/test/pdos.cr3si6 .

Partial dos were generated with following --pdos switch:

$ lmdos cr3si6 -vnk2=5 --dos:npts=501:window=-.8,.5 '--pdos~mode=2~group=1:3;4:9~lcut=2,1'

Note: you can generate pdos.cr3si6 and see the commands by running the test : ~/lm/fp/test/test.fp cr3si6 2.

The --pdos switch specifies that DOS are to be resolved by site, and both l and m (mode=2). There are two kinds of sites, corresponding to Cr and Si. DOS are computed to l=2 and l=1, respectively, making $(2{+}1)^2 + (1{+}1)^2 = 13$ channels for Cr spd and Si sp.

Here we draw DOS in 9 panels, corresponding to the following:

Make the panels this way:

$ echo 0.999 3 -8 8 | pldos -ef=0 -esclxy=13.6 -fplot~tmy=.25~ext=2~xl=E~sh -lst='1;2,3,4;5;6;7;8;9;10;11:13' pdos.cr3si6
$ open fplot.ps

Here panels are specified through the −lst switch by sequences of integer lists separated by semicolons (switches are documented in the manual).

There are nine lists, corresponding to the panels described above:  1   2,3,4   5   6   7   8   9   10   11:13 .   Note that 11:13 is equivalent to 11,12,13.

3. pldos manual

Invoke pldos in one of the following ways:

pldos [-switches] filename
pldos -lst=... [-switches] filename
echo dmax, h, emin, emax | pldos -lst=... [-switches] filename

filename is the name of the DOS file generated by the Questaal package, e.g. dos.ext. This may be the total DOS generated by a band code such as lmf or the partial DOS generated by lmdos. The format of the DOS file is detailed here. In the magnetic case, or when partial DOS are generated, dos.ext will contain multiple families of DOS corresponding to different channels, e.g. partial waves s, p, d. In the magnetic case, DOS alternate in spins (channel 1, spin 1, channel 1, spin 2, channel 2, spin 1, etc).

pldos will cull DOS from dos.ext, and combine them according to lists you supply. When multiple DOS are involved, refer to which member by an integer, e.g. 1 for the first DOS, 2 for the second, etc.

Note: In the magnetic case the spin-up and spin-down DOS are interleaved; thus 1,3,5,… correspond to the spin-1 DOS and 2,4,6,… correspond to the same channels, for spin 2.

Using pldos in the first form (without the --lst= switch) you will be prompted with a pair of questions:

 dos 1:  Enter list of dos to be added:
 Weights for dos: 1?

To the first question enter an integer corresponding to which DOS to extract from dos.ext, or a list of integers.
To the second question enter a corresponding list of weights to assign each DOS, one weight for each element in the list.

These questions will be repeated until you enter a blank list in response to the first question. Each group of DOS will generate a new panel; thus multiple panels can be drawn, one below the other.

These interactive questions can be bypassed with the  --lst=  switch described below. Create a sequence of one or more lists list1,   list2,   … using --lst=list1;list2;.... Each of list1,   list2,   … consist of a list of DOS. For each list a new panel will be made.

After the lists are read from standard input (stdin) or parsed from --lst=, pldos reads four numbers from stdin: dmax, height, emin, emax :

• dmax caps the DOS in the figure so as not to exceed this value
• height is of dmax (ordinate), in cm.
• emin and emax comprise the lower and upper energies of the figure (the energy appears on the abscissa).

Command line switches

Optional switches to pldos perform the following functions:

• −lst=list[;list2;list3…]
  Create a sequence of one or more lists list,   list2,   … , each of which are integer lists, or possibly a seq tag described below. The semicolon acts as a delimiter that starts a new panel and a new list. Each of list,   list2,   … consist of a list of DOS which are summed together.

  The seq tag

  Provided a prior list has been established, you can substitute seq=# in place of list.
  seq=# creates a new panel, using the the prior list for DOS list, but shifting each element in the DOS list by a constant so that the first element is  #.
  #  itself can a single number or an integer list. If it is a list, a new panel is created for each member of  #. The preceding list will be replicated, then shifted by the current element in  #.
  Example: : −lst=1:4;seq=11 generates two panels, the first combining 1 2 3 4, the second combining 11 12 13 14.
  Example: : −lst=1:4;seq=5:9:4 generates three panels, the first combining 1 2 3 4, the second combining 5 6 7 8, the third combining 9 10 11 12.

• −lst2 | −lst2=list…
  performs the same function as −lst but for second spin (see Note). In this case, the panel is drawn with both positive and negative DOS: the positive is for spin 1, and the negative DOS is for spin 2.
  Example: : −lst=1,3,5;7,9,11 −-lst2=2,4,6;8,10,12 combines the spin-1 DOS in channels 1,3,5 in the first panel DOS in channels 7,9,11 in the second. Also in the first panel, below y=0, are spin-2 DOS in channels 2,4,6 and in the cond panel, are spin-2 DOS from channels 8,10,12. −lst2 without arguments means to use the list from −lst, but incrementing each element by 1, consistent with interleaving of spins.
  The seq tag cannot be used here.

• −fplot[~options]
  causes pldos to create input for fplot or another graphics package. It does the following:

  1. writes collated dos to file dosp.dat
  2. generates a script plot.dos
  3. Optionally creates a postscript file by invoking fplot in a subshell.
     Options: the first character after −fplot (assumed to be  ’~’  here) delimits the different switches.
     • ~long : writes fplot data files with 6 decimals, rather than 4.
     • ~open : fplot script adapted to give open feel to figure.
     • ~dmin=# : restricts DOS upper bound in any panel to be no smaller than  #.
     • ~tmy=# : Sets the tic mark spacing on the DOS axis.
     • ~xl=strn : assign an x axis label.
     • ~inc=fn : prepends contents of file fn to the fplot script file, plot.dos.
     • ~ext=nam : write data files to dosp.nam instead of dosp.dat.
     • ~sh : invoke fplot in a subshell to make fplot.ps.

  See Examples for an example.

• −long (same as −fplot~long)
  writes fplot dosp.dat with 6 decimals, rather than 4.

• −inc:filname (same as −fplot~inc=filname)
  prepends contents of filname to fplot script file.

• −ext=ext (same as −fplot~ext=ext)
  write data files to dosp.ext instead of dosp.dat.

• −ref:fn=filename[:chan=ref-channel]
  single DOS with color weights.

  • Reference DOS is total DOS file, standard (traditional) format
  • filename is partial DOS file, standard format, e.g.
    pldos -ef=0 -escl=13.6 -fplot ‘-lst=3;1’ -ref:fn=dos.cr:scale dosl.cr

• −dif:#[,rat]]  |  -int
  differentiate or integrate DOS

• −ef=expr||-shiftef=expr
  shift Fermi level to  expr.

• −shiftef=expr
  shift Fermi level by  expr.

• −escl=expr
  scale energy axis (abscissa) by  expr

• −esclxy=expr
  scale energy axis (abscissa) by  expr and DOS (ordinate) by  1/expr
  This is the appropriate switch to keep units consistent.

4. Other resources

See the documentation for fplot and plbnds.