Questaal Home
Navigation

Command Line switches

Preliminaries


Most executables in the Questaal suite accept command-line arguments. This input stream acts in parallel with data read from the input file. Note that variable declarations used by Questaal’s preprocessor assigned via command line arguments are prior to other assignments, and take precedence. Variable declarations and a few other switches are shared in common by the great majority of Questaal’s executables.

This page documents the common and program specific command-line switches for many of the Questaal codes.

Table of Contents


Introduction


All of the programs have special branches that may be (and sometimes must be) set from command-line switches.

Here is an example:

$ lmf cafeas -vns=4 -vnm=5 --rpos=pos

Following unix style, switches always begin with dash (). Many codes have command-line switches unique to their purpose, but a number of switches are shared in common.

Some switches have a single dash ; some have two. Those with two tend to control program flow (e.g. --show), while those with a single dash tend to have an “assignment” function, such as a variables declaration (e.g. -vns=4). Sometimes there is not a clear distinction between the two, e.g. the printout verbosity --pr accepts either one or two dashes (see below).

In the example above, -vns=4 -vnm=5 assigns variables ns and nm to 4 and 5, respectively, while --rpos=pos tells lmf to read site positions from file pos.cafeas.

Switches Common to Most or All Programs

  • --help | --h
    • Lists command-line switches for that program and exits.
  • --input
    • Lists tags (categories and tokens) a program will read. Same as turning on IO_HELP=T
  • --showp
    • Prints out input file after parsing by preprocessor, and exits. It shows the action of the preprocessor, without parsing any tags.
  • --show | --show=2
    • Prints the input file parsed by preprocessor, and the value of the tags parsed or default values taken.
      --show=2 causes the program to exits after printing.
  • ---rpos[=fnam]
    • Read site positions p from file fnam, superseding data read from input or site files.
      The true file name has the extension appended : fnam.ext. If fnam is not specified, pos.ext is used.
      For more detailed explanation for how site data is read, see this page.
  • ---rdpos[~scale=fac][~fn=fnam]
    • Reads from file fnam site displacements Δp to be added to positions p supplied by the normal input stream.
      If fnam is not specified, dpos.ext is used. Optional scale=fac adds fac×Δp to p.
  • --shorten  |  --shorten[~ib=i1[,i2]]~#1,#2,#3
    • Shortens basis vectors by adding multiples of lattice translation vectors. Optional ib limits shortening to sites i1 and higher, or to range [i1,i2].
      #1,#2,#3 are conditions for each axis. Use 0 to suppress shortening, 1 to place in first quadrant, 2 to minimise length. If not specified, #1,#2,#3 are all set to 2.
      Some programs (notably blm and the full potential programs such as lmf) shorten basis vectors by default. To suppress shortening in such cases, use --shorten=no.

Note: the preceding switches are intended to assist in managing and reading input files. They are discussed in more detail in this tutorial.

  • --pr#1[,#2] | -pr#1[,#2]
    • Sets output verbosities, overriding any specification in the ctrl file.
    • Optional #2 sets verbosity for the potential generation part (applicable to some codes)
  • --quit=keyword
    • quit after execution of certain blocks (electronic structure programs only). Keywords are:
      –quit=ham  quit after printing hamiltonian setup (lmf, lm, lmgf, lmpg)
      –quit=pot  quit after potential is assembled (lmf)
      –quit=dos   quit after Fermi level is found and dos weights are written to disk (lmf)
      –quit=rho  quit after a band pass has been completed, the output charge assembled and forces calculated (lmf)
      –quit=band  similar to –quit=rho, but performs a bit more post-band processing (checks for convergence and writes forces) (lmf,lm)
  • --noinv  |  --nosym apply to programs that use symmetry operations
    • --noinv  suppresses the automatic inclusion of inversion symmetry (this symmetry follows from time reversal symmetry).
    • --nosym  suppresses symmetry operations all together
  • --time=#1[,#2]
    • Prints out a summary of timings in various sections of the code. Timings are kept to a nesting level of #1.
      If #2 is nonzero, timings are printed on the fly.
  • --iactive
  • --iactive=no | --no-iactive
    • Turns off ‘interactive’ mode.
  • -cname=”string
    • Declares a character variable name and gives it a value string. The quotation marks are not needed if string has no spaces.
  • -vname=expr
    • Declares a numeric variable name and assigns its value to the result of expression expr. Only the first declaration of a variable is used. Later declarations have no effect.
      Note: there are also generalized assignment operators  *=,  /=, +=,  -=,  and ^= that modify already-declared variables, following C syntax.

Switches Common To Programs Using Site Information

Most Questaal codes read structural information (lattice and position vectors). For any program reading site information the following switches apply:

  • --rpos=fnam
    • Tells the program to read site positions from file fnam.ext after the input file has been read. fnam.ext is in standard Questaal format for 2D arrays.
  • --fixpos  |  --fixpos[~tol=#]  |  --fixpos=#
    • Adjust positions slightly, rendering them as consistent as possible with the symmetry group. That is, if possible to slightly displace site positions to make the basis conform to a group operation, make the displacement. Optional tolerance specifies the maximum amount of adjustment allowed. If --fixpos is given without argument,  # defaults to 1d-4.
      Example:lmchk --fixpos:tol=.001
      See also Example 5 of this tutorial for a detailed exposition, and also Example 6 which deals with a complex case.
  • --fixlat  |  --fixlat[~tol=#]  |  --fixlat=#
    • Adjust lattice vectors and point group operations, attempting to render them internally consistent with each other. If --fixlat is given without argument,  # defaults to 1d-4.
      See Example 5 of this tutorial for a detailed exposition of --fixlat. Note: this algorithm is not very sophisticated, and sometimes fails.
  • --tidy[opts]
    • is an enhanced version of --fixpos and --fixlat. The switch is documented below, and this tutorial](/tutorial/importing_input/#9-the-tidy-and-related-switches–cleaning-up-imprecision-in-input-files) has many details. Note: if you need this switch, is recommended you use it at an early stage (with blm) to make clean input files.
  • --sfill[options]
    • Runs the sphere resizer. The same function is performed if SPEC_SCLWSR is set. Using this command-line argument you control the tags SCLWSR, WSRMAX, OMAX1, and ATOM_CSTRMX, overriding those in the ctrl file. The first character in options acts as a delimiter separating them. Here we assume it is  ’~’.
      Options:
      • ~sclwsr=#       Scales sphere radii, trying to reach volume = # × cell volume
        • Add 10 to initially scale non-ES first
        • Add 20 to scale ES independently
      • ~lock=#1,#2,…    exclude this species when resizing.   #n corresponds to species n .
      • ~omax=#1[,#2,#3] #1 limits maximum overlaps between actual atoms.   #2 and #3 concern A-E and E-E overlaps respectively, where A are true atoms and E are empty spheres.
      • ~wsrmx=#      If present, # sets upper bound to sphere radius.

      Example: –sfill~sclwsr=11~lock=1,1,1~omax=.16,.20,.26~wsrmx=3.3

See Table of Contents

Questaal editors

Questaal has several kinds of editors to manipulate data it generates. Invoke an editor with a particular command-line switch described below. Each editor is embedded in the executable most closely associated with the editor’s function, and you run the excecutable in the usual way but with an extra command line argument, such as   lmscell inas --stack.

For most editors, invoking it without starts the editor in an “interactive mode”. -lmscell for example, prints out

 Welcome to the superlattice editor.  Enter '?' to see options.

 Option :

and then it waits for an instruction from standard input. To see what instructions it knows about, type ? <enter>.

Most of the editors can operate in batch mode as well. String together instructions separated by a delimiter, which is the first character after the editor tag; it cannot be a space. In the lmscell example the following command

lmscell ctrl.inas '--stack~size~site site.inas'

starts the editor, runs the size instruction, next the instruction site site.inas. Neither instruction causes lmscell to exit, so the editor returns to the interactive mode, waiting for a new instruction.

Restart file editor
Edits restart files, built into lmf. Invoke with lmf --rsedit.
There is another ASA-specific form built into lm, lmgf and lmpg. The ASA version is documented here.
Optics editor
Extracts information generated by lmf optics when information is resolved by band or k. Invoke with lmf --popted. See this tutorial for some explanation of its usage.
QSGW static sigma editor
Edits and transforms quasiparticlized self-energies generated by QSGW, built into lmf. Invoke with lmf --wsig~edit.
Magnetic susceptibility editor
For spin susceptibility, built into lmf. Invoke with lmf --chimedit. See this tutorial for a demonstration.
Dynamic self-energy editor
Manipulates and generates properties from dynamical self-energies (usually made by GW or DMFT). This tutorial explains its operation. Invoke with lmfgws --sfuned.
Superlattice stack editor
Superlattice editor built into lmscell. Invoke with lmscell --stack. See this tutorial for an example and also documentation of the editor’s instructions.

Switches for blm

blm creates input files (the ctrl file and sometimes the site file) from structural information.
Note: Use blm --h for a quick reference to blm’s options.
Command-line switches:

  • --brief[=n] | --simple
    • Set simplicity of input file. With larger n, the file becomes simpler, supplying fewer tags and relying more on default settings. n can vary between 0 and 6. If --brief is given without argument n a default value of n=3 is used, and it also effectively activates the --genbas switch. --simple is similar, but is like --brief=6 The introductory tutorial uses --simple, and Exercise 1 compares --simple and --brief.
        n  mode
      • 0:  Expert: Contains the most tags; no supporting informational comments are supplied.
      • 1:  same as --brief=0
      • 2:  Verbose: Similar to brief=1, with comments added
      • 3:  Standard: Similar to brief=2, but some duplicate tags are removed
      • 4:  Small: Most tags covered by defaults are removed.
      • 5:  Light: No preprocessor instructions, variables or expressions are used
      • 6:  Simple: Minimal input file
  • --express[=n]
    • Express style input file level n. If n>0, an express category is created. This category adds no new functionality, but groups commonly used tags spread among multiple categories into a single category, EXPRESS. The same information may then reside in two places; if both are present, tags in EXPRESS take precedence. The file tag is included in EXPRESS, so a site file is created and the structural information will be read from it. As with the --brief=n switch, the input file becomes sparser as n increases. If --express is given without argument n a default value of n=6 is used.
      n  mode
      • 0:  Expert: Standard mode (same as brief=0). No EXPRESS category is created.
      • 1:  Expert: Similar to mode 0, but the EXPRESS category is added. Input is terse with no informational comments
           Tags duplicated by EXPRESS are retained in their original categories to facilitate editing by the user (however EXPRESS takes precedence).
      • 2:  Verbose: Similar to mode 1, with informational comments added
      • 3:  Standard: Similar to mode 2, but some duplicate tags are removed
      • 4:  Small: Most tags covered by defaults are removed.
      • 5:  Light: No preprocessor instructions, variables or expressions are used
      • 6:  Simple: Minimal input file

The following switches tailor the input file to a target method. Options or modifiers for tags are delimited by  ~  (or the first character following the tag).

  • --asa[~options]
    Tailor the autogenerated input file to an ASA calculation.
    Options:
    • ~rmaxs=#   Sets range for the ASA tight-binding structure constants, by adding tag STR_RMAXS
    • ~scr=#     Sets the value of OPTIONS_ASA_SCR (default value is  4 )
    • ~adnf=#    Turns on/off automatic downfolding ( #  is  1  for true or  0  for false).
    • ~nodnf     Turns off downfolding
    • ~p0ree    Adds HAM_PMIN=-1 : restricts the logarithmic derivative to stay above the free electron limit.
      The logarithmic derivative is controlled through the continuous principal quantum number P.
      See this tutorial for an example, or this one.
  • --gw[~options]
    Tailor input file to a GW calculation. Modifies HAM_AUTOBAS; adds a GW category and some GW-specific tokens.
    Options are:
    ~eloc=# :      Sets HAM_AUTOBAS_ELOC to  #
    ~qloc=# :      Sets HAM_AUTOBAS_QLOC to  #
    ~emax=# :     Sets HAM_SIGP_EMAX to  # .
    ~emax=#,#2 :    Like ~emax=#, except the user also specifies the energy window over which the transition to high energy is broadened.
    ~gcutb=# :    Sets GW_GCUTB to  #   (Determines how lmfgwd --job=-1 assigns the G-vector cutoff for interstitial part of one-particle objects).
    ~gcutx=# :    Sets GW_GCUTX to  #   (Determines how lmfgwd --job=-1 assigns the G-vector cutoff for interstitial part of two-particle objects).
    ~getgcut=#    Causes blm to use internal algorithm to find a default for gcutb and gcutx that was not explicitly declared.
             For this switch to work, the automatic basis generator must be turned on (--genbas or --brief or --simple will do this).
             The internal defaults are scaled by  #. If  #  is not supplied, blm does not scale the default.
             For an example, see the Fe tutorial.
    ~rsmin=# :     Tells blm’s internal algorithm to find a default for gcutb and gcutx to use  # as a lower bound for the smoothing radius.
             For some systems, a relatively deep envelope function (e.g. the In 4d level) is also sharply peaked with a small smoothing radius.
             The internal algorithm returns gcutb and gcutx for the worst case, and sets them much larger than they need to be, significantly increasing the cost of the calculation.
             Telling the finder to use  #  (e.g.  #=1.2) as a lower bound for the smoothing radius mitigates this.
    ~pbtol=strn :    Sets GW_PBOL  to  strn   (Determines how lmfgwd --job=-1 assigns G-vector cutoff for interstitial part of two-particle objects).
    ~nvbse=# :     Creates and assigns tag GW_BSE_NV (number of valence states included in BSE).
    ~ncbse=# :     Creates and assigns tag GW_BSE_NC (number of conduction states included in BSE).
    ~delre=#,#2    Creates and assigns tag GW_DELRE with supplied arguments. If  #,#2 is absent, the tag is written with default values.
             For additional information, try lmfgwd --input | grep -A 3 -i gw_delre .
             Note : delre is the analog of  dw  and  omg_c  in the GWinput file, albeit in Ry units.
    ~q0ps=# :     Creates GW_Q0PSCALE and assigns value to variable q0ps, which is assigned value  #. ~q0ps without argument does the same, assigning default value.
    ~vtf=# :      Creates GW_VTF and assigns value to variable vtf, which is assigned value  #. ~vtf without argument does the same, assigning default value.
    ~wemax=# :    Creates SIGP_WEMAX and assigns value to variable emaxw, which is assigned value  #. ~wemax without argument does the same, assigning default value.
    ~lmxa=# :     Sets ATOM_SPEC_LMXA for all species, as current versions of GW codes require
    ~nk=#[,#2,#3] : Sets GW_NKABC to  #,#2,#3 . If  #2,#3  are not supplied, blm will select defaults for all three numbers, using  #  as a characteristic average spacing.
    ~ins :        Similar to nk=#, except a default for  #  is chosen, assuming the system is an insulator.
            Hazard: blm’s selection of a default is by no means robust. It is the user’s responsibility to monitor in the q mesh density.
    ~mixb=#:     creates a tag for the mixing parameter beta (GW_MIXBETA) for mixing the self-energy. ~mixb without argument does the same, assigning default value.
    ~met :       Similar to nk=#, except a default for  #  is chosen, assuming the system is a metal.
            Hazard: blm’s selection of a default is by no means robust. It is the user’s responsibility to monitor in the q mesh density.
    For examples, see this tutorial and this tutorial.

  • --gf
    add a GF category and BZ_EMESH required by lmgf. This tutorial uses blm with the --gf switch. An advanced example can be found here.

  • --pgf~platl=#1,#2,#3~platr=#1,#2,#3
    add a PGF category and BZ_EMESH required by lmpg.  platl and platr become the tokens PGF_PLATL and PGF_PLATR documented here and also explained in this tutorial.

  • --dmft[~options]
    add a DMFT category required by lmfdmft.
    ~beta=#     Inverse temperature, in eV−1
    ~nlohi=#1,#2    First and last eigenstates to include in projector
    ~sites=site-list   Integer list of sites in the DMFT block.

  • --fpandasa
    tags for both ASA and FP.

The following set switches allow you to set parameters for which no defaults are supplied. You can enter them through command line arguments to blm as shown below, or edit the ctrl file later.

  • --gmax=#
    specify mesh density cutoff HAM_GMAX. You can use lmfa to determine this number for you, once the basis set has been supplied. See this tutorial for an example.

  • --nk=#1[,#2,#3]  |  --nk[~nochk]~#1[,#2,#3]  |  --nk[~nochk]=−#  |  --nk[~met]  |  --nk[~ins]
    k-mesh for Brillouin zone integration; sets up token BZ_NKABC.
    --nk~… is more sophisticated than --nk=… : it picks  #1,#2,#3  to render spacings along the three reciprocal lattice vectors approximately equal.
    --nk=−# generates a mesh of  (#1,#2,#3)  divisions, with  #1×#2×#3 ≈ #  ( #i rounded to nearest integer) and  #i / |qlati| ≈ constant ( #i rounded to nearest integer).
    Thus spacing between k points is approximately uniform in all directions.
    --nk~nochk~… forgoes an internal sanity check that the selected mesh is consistent with given symmetry operations.
    --nk[~ins] picks default values for an insulator; --nk[~met] picks default values for a metal. Typical values for  #1 , #2  and  #3  for semiconductors with small unit cells is  6, and  10  in metals.
    Warning: Proper values are materials- and property- specific. The user should take care that blm’s default values are reasonably converged for your purpose.
    See this tutorial for an example.

  • --nkgw=#1[,#2,#3]
    Similar to --nk but applies to the GW k-mesh. Same as --gw~nk=…

The following set of switches control the approach to charge self-consistency.

  • --nit=#
    specify max number of iterations to attempt on the approach to self-consistency.
    Program ends after  #  iterations, or when self-consistency is reached, whichever occurs first. For an example, see this tutorial.

  • --conv=#
    specify tolerance for energy convergence (ITER_CONV), overriding default

  • --convc=#
    specify tolerance for charge convergence (ITER_CONVC), overriding default

  • --dhftol=# (lmf only)
    Adds another convergence criteria (ITER_DHFTOL), which requires that the correction to Harris forces fall below this tolerance for self-consistency to be reached.

  • --convp
    Tags ITER_CONV ITER_CONVC, ITER_DHFTOL are assigned to variables conv, convc, dhftol, so that they are controllable from the command line.

  • --mixb=#
    Set default value of charge mixing parameter beta

  • --mixs=strn
    User-defined choice of string that controls charge mixing, normally read as token ITER_MIX

  • --sampling[~tetra=#~n=#~w=#]
    Adds tokens BZ_TETRA, BZ__N, BZ_W to turn on sampling integration.
    Also creates the preprocessor variables listed below to enable control of these tokens from the command line. Default values are supplied.
    Options to enable you to override the default values:
    ~tetra=# :      Assigns value to tetra, which is assigned to BZ_TETRA. tetra=0 turns off tetrahedron integration.
    ~nmp=# :      Assigns value to nmp, which is assigned to BZ_N (Methfessel-Paxton sampling order).
    ~w=# :       Assigns value to wsamp, which is assigned to BZ_W (Gaussian sampling width).

The following miscellaneous set of switches control program flow.

  • --rsham[~options]
    Adds category STR and tokens STR_RMAXA, STR_ENV_MODE, STR_ENV_NEL, STR_ENV_EL for screened LMTO basis.
    Also creates the preprocessor variables listed below to enable control of these tokens from the command line. Default values are supplied.
    Options to enable you to override the default values:
    ~rsham=# :    Assigns value to rsham. rsham>1 turns on screened LMTO basis.
    ~rscut=# :     Assigns value to rscut, which is assigned to STR_RMAXA : range of strux in units of lattice constant.
             If you do not specify rscut, blm will find a default based on the average cluster size npr.
    ~npr=# :      Selects the average cluster size to determine rscut. Default is 50.
    ~el=#,# :      Assigned to STR_ENV_EL(1) STR_ENV_EL(2) : LMTO energies (EH)

  • --mag
    sets up for a spin polarized calculation. Note that you should also supply a trial magnetic moment on magnetic atoms. See this tutorial for lmf or this tutorial for lmgf.

  • --optics
    Adds tags to the input file to enable calculation of dielectric functions. Default values are supplied.
    Options to enable you to override the default values:
    ~delre=#[,#] : (GW) sets energy mesh for optics branch. Meaning equivalent to  --gw~delre=..  in QSGW branch; see --gw switch.
    ~eta=#[,#] :   (BSE) sets broadening for BSE optics.

  • --pbe
    set switches for the  PBE functional  (libxc version). For an example, see this tutorial.

  • --pbesol
    set switches for the  PBESOL functional  (libxc version).

  • --zbak
    Add token BZ_ZBAK for including constant background charge.

  • --molstat[~options]
    Add DYN_MSTAT tag for molecular statics (used by lmf).
    Options are delimited by  ~  (or the first character following --molstat):
    ~mode=# :    Sets DYN_MSTAT_MODE to  #.
    ~xtol=# :     Sets DYN_MSTAT_XTOL to  #.
    ~gtol=# :     Sets DYN_MSTAT_GTOL to  #.
    ~step=# :    Sets DYN_MSTAT_STEP to  #.
    ~nkill=# :     Sets DYN_MSTAT_NKILL to  #.
    For an example, see this tutorial.

  • --autobas[~options]
    Modify AUTOBAS tags for controlling how the basis set is constructed (used by FP codes). This tutorial uses --autobas[~options].
    Options are delimited by  ~  (or the first character following --autobas):
    ~loc=# :      Sets HAM_AUTOBAS_LOC to  #.
    ~eloc=# :      Sets HAM_AUTOBAS_ELOC to  #.
    ~mto=# :     Sets HAM_AUTOBAS_MTO to  #.
    ~ehmx=# :    Adds a tag HAM_AUTOBAS_EHMX and sets to  #. Used by lmfa to limit the upper bound to LMTO smoothed Hankel energy, when autogenerating a basis set.
    ~rsmmx=#:   Adds a tag HAM_AUTOBAS_RSMMX and sets to  #. Used by lmfa to limit the upper bound to LMTO smoothed Hankel smoothing radius, when autogenerating a basis set.
            #  is a multiple of the MT radius (default = 2/3 ).

  • --genbas[~options]
    Finds parameters for the basis set, using the same algorithm as lmfa uses. It gnerates values not supplied manually and writes them to the basp file.
    Options are delimited by  ~  (or the first character following --genbas):
    ~ctrl :     Also write basis parameters into the SPEC category of the ctrl file .
    ~nofile :    Suppress writing basis parameters to file basp.ext .
    ~wgmax :   Estimate the plane-wave cutoff from the autogenerated basis and write its value into tag HAM_GMAX of the ctrl file .
    ~fn=nam :   Write basis parameters to file nam.ext

  • --lmfit
    Add tag ITER_FIT for Levenberg-Marquardt fitting (used by lm).

  • --pmt[:emax=#]
    Set up input for the PMT basis. It:
  • --dv=string
    Add a variable declaration to the input file, e.g. --dv=idp=0 adds a declaration similar to  %var idp=0  . Note how the preprocessor distinguishes between  %const  and  %var .

  • --nosort  |  --sort=no
    suppress ordering of site positions by species.

  • --frzwf
    Adds FRZWF={frzwf} to the HAM category. This switch will be set if preprocessor variable frzwf is set to nonzero. When  HAM_FRZWF  is set, the basis set is kept fixed the potential used to make partial waves is frozen, and the boundary conditions kept fixed. (In the ASA, only the latter applies).
    For an application, see this tutorial.

  • --amass
    Adds tag SPEC_ATOM_AMASS to each species in the SPEC category.

  • --ewald=#  |  --ewald
    Adds tag EWALD_TOL and sets to  #. Also adds tag HAM_TOL and sets to  #. If  # is missing it is assigned value  1d-16 . For an application, see this tutorial.

  • --clfloat
    use traditional float algorithm (see Troubleshooting issue [4]).

  • --savesym
    tell blm to uncomment the SYMOPS category it writes to the ctrl file

The following set of switches concern augmentation spheres:

  • --nl=#
    Sets default maximum l cutoff to #−1 in augmentation spheres (used in the absence of explicit species-dependent specification).
    The full-potential codes use this default for ATOM_SPEC_LMXA; The ASA codes use it for ATOM_SPEC_LMX.
    This tutorial has an example.

  • --lmxl   |   --lmxl=#
    Add tag LMXL to each species in the SPEC category. The first form assigns the same value to LMXL as to LMXA (the user then sets desired values by hand).
    The latter form sets LMXL to  #  unless  #  is larger than LMXA.

  • --omax=#1   |   --omax=#1,#2,#3
    Override contents of SPEC_OMAX1, which set maximum sphere overlaps to  #1  when the sphere resizer is invoked.
    Optional  #2  and  #3  concern A-E and E-E overlaps, respectively where A are true atoms and E are empty spheres.
    This tutorial has an example.

  • --findes[~options]  |  --resize[~options]
    Search for empty sphere sites (E sites, atomic number 0) to improve lattice packing. The algorithm proceeds as follows:
    1. If spec is specified among the options, selected species are enlarged according to their class.
    2. Empty sites are located. One sphere is added at a time (and its symmetry-equivalent replicas) to the current largest available space.
      This continues until maximum sphere overlap is reached (see --omax above), or until space is filled such that sum-of-sphere volumes = unit cell volume.
    3. If resize is specified among the options, sphere radii are rescaled.
    4. If rcut is specified among the options, E spheres with radii less than rcut are eliminated.
    5. If mino is specified among the options, the position of the E spheres is optimised by minimising sphere overlaps.
    6. If mino and resize are both present, dup will cause the (mino, resize) cycle to iterate

    The equivalent functionality is available in lmchk and lmscell, as well as blm.
    Also lmchk and lmscell also have a similar switch,  --resize[~options]. It performs steps 1,3,4,5, and is equivalent to --findes~nesmx=0~…  .

    Options are delimited by  ~  (or the first character following --findes):

    • ~rmin=# :   exclude empty spheres with augmentation less than  rmin. This radius may be reduced while finding ES; see ~omaxi.
    • ~rmax=# :   Limit new empty sphere radii not to exceed  rmax. This radius may be reduced while finding ES; see ~omaxi.
    • ~float :     Render E sites (sites with atomic number 0) as floating orbitals (no augmentation radius). For full-potential only.
    • ~mino :     Move E sites to minimise sphere overlaps after new spheres have been found.
    • ~omaxi=#1[,#2,#3]  |  ~omaxx=#1[,#2,#3] :
             When finding empty spheres, temporarily resize spheres to specs #1[,#2,#3] (meaning is same as --omax= above).
             After the E spheres are located, omax is restored to its original value read from the ctrl file (possibly overridden by switch --omax=).
             Sphere radii are restored or if resize is present, resized.
             omaxx and omaxi perform the same function, except when mino is used. Then the E sites adjusted minimized with using overlap function with temporary sphere overlaps, rather than final ones.
    • ~resize[=#] : Causes spheres to be resized after ES have been located. If not present, spheres are restored to original size.
             Optional  #  plays the same role as sclwrs in the --sfill option.
    • ~dup=# :     makes the (mino, resize) cycle iterate  #  times. Only active if both ~resize and ~mino are both present.
    • ~nesmx=# :   Add a maximum of  nesmx  empty spheres. nesmx=0 suppresses finding new E spheres but performs other four functions noted above and to the --resize option.
    • ~nspmx=# :   Limit the number of empty species to  nspmx. The MT radius of all new sites exceeding  #  are set to a single species (with the smallest common radius).
    • ~1spec :     Force new empty sites to be the same species. Same as  nspmx=1.
    • ~lock=slst :   When spheres are resized, exclude species in slst in resizing step.
    • ~shorten=#1[,#2,#3] :
             Shorten basis vectors of new additions (one condition for each axis). #2 is copied from #1 if not present; #3 is copied from #2.
             Use #=0 to suppress shortening, #=1 to place in first quadrant, #=2 to minimise length.
    • ~includep=expr  |  ~excludep=expr :
             Restrict lattice points where E spheres are located to those satisfying (not satisfying) expr.
             expr can contain any of x1, x2, x3 (Cartesian coordinates, in units of the lattice constant) or p1, p2, p3 (multiples of lattice vectors).
             ~excludep and ~excludep can be used separately or in conjunction; thus  ~includep=x3>.7~excludep=x3>1.3  is equivalent to  ~includep=x3>.7&x3<=1.3 .
    • ~gran@tol=#@lst=slst :
             Merge species in slst into a single species. All species in the list must have the same atomic number.
             Species whose sphere radii differ by less than  tol  are made into a single species with the smallest common radius.
             ~gran may be repeated for different sequences of species.
    • ~sren :     Rename enumerated species labels (labels ending in a sequence of integers). The integer parts are ordered sequentially for species with the same root and atomic number.
    • ~rcut=# :     After ES have been identified, eliminate any site whose (final) sphere radius is less than #.
    • ~spec[=slst] :  (works only when invoked from lmchk or lmscell). Split species in slst by class. If slst is not specified, all species are split.
             This increases the number of species, which adds to of the input file but gives more flexibility in obtaining sphere radii to meeting spacing-filling constraints.\
    • ~noclass     (for lmchk only) compresses classes into species. This is the default operation for lmscell and blm.

    This tutorial has a simple example; see also this tutorial and this one for more detailed examples.
    ~/lmf/testing/test.lmscell 10 and ~/lmf/testing/test.ovlp 10 demonstrate some advanced features of this switch.
    Also try ~/lmf/testing/test.blm 13 .

  • --addes[~options]
    add tags to prepare for later addition of empty spheres. Options:
    • ~end :     Tells blm to put the E species last in the SPEC category
      This tutorial has an example.

The following concern how structural or chemical data is written to disk or read from disk:

  • --rdsite[=fn]
    read structural data from site file fn. Default fn is sitein.ext. For examples, see This tutorial, this this tutorial, and, for an advanced example, this tutorial.

  • --rdspec[~fn=nam~fn=…]
    may be used in conjuction with --rdsite. Use this switch if you want to supply blm with species-specific information normally found in the init file Examples are given in this tutorial and this one.

  • --rpos=fnam
    reads site positions from file fn.ext, superseding contents of input structure file

  • --usefiler
    tells blm to accept without change any MT radius (R) input in the SPEC category. The default is for blm to determine sphere radii automatically.

  • --noshorten  |  --shorten=no
    suppress automatic shortening of site positions; structural data is written to disk as read.

  • --nfile
    tells blm to insert these lines into the ctrl file:
    %ifdef file>=1
      file=   site{file}
    %endif
    

    Has no effect unless preprocessor variablefile  is set. When  file  is assigned value n, Questaal codes will read structural data from siten.ext.
    For examples, see this tutorial or this one.

  • --ctrl=fn
    write input file to fn.ext instead of default actrl.ext. The introductory tutorial to lmf provides an example.

  • --scala=#
    multiply ALAT by  #, and  PLAT  and  POS by  1/#. See this tutorial for an example.

  • --scalp=#
    like scala, but  #  specifies  PLAT  volume. See this tutorial for an example.

  • --tidy[~args]
    Switches designed to improve precision of lattice vectors and site positions in the init file, consistent with approximate space group operations (that is space group operations that would be allowed within a given precision).
    Without arguments --tidy is equivalent to --fixlat,tol=1e-4 --fixpos,tol=1e-4 --ratx,tol=1e-5.
    --tidy[~args] is used extensively in this tutorial. It provides a detailed exposition of how to use this switch, and several example cases.
    Optional arguments:
    • ~tol=# equivalent to --fixlat,tol=# --fixpos,tol=# --ratx,tol=# --toleqp,tol=#
    • ~fixlat=# equivalent to --fixlat,tol=#
    • ~fixpos=# equivalent to --fixpos,tol=#
    • ~ratx=#  equivalent to --ratx,tol=#
    • ~equp[=#]  equivalent to --toleqp,tol=# causes blm to substitute nearly equal elements in  PLAT  and  POS (within tolerance #) with their average value.
             If ~equp is not present,  #  is zero; if it is present but  #  is not specified, it defaults to  1d-5 .
  • --ratx  |  --ratx=#  |  --ratx[,tol=#]
    Adjust elements in either PLAT or site positions within tolerance within  #  of a simple rational number or the square root or a simple rational number, replace it with that number.
    If --ratx is given without argument,  #  defaults to  1d-6 . See Example 4 in this tutorial.

  • --toleqp  |  --toleqp=#  |  --toleqp[,tol=#]
    Find elements in lattice vectors PLAT equally sized within a granularity of  # , and replace them with their average value. If --tolx is given without argument  #  defaults to  1d-6 .
    See Example 5 in this tutorial.

  • --xshft=#  |  --xshftx=#
    shift site positions by a uniform translation, Cartesian coordinates (xshft) or in crystal coordinates (xshftx). This tutorial provides an example.

  • --digits
    Write lattice vectors and site positions to ten decimal places.

  • --wsrmax=#
    when finding sphere radii, do not permit any radius to exceed  #. This tutorial has an example.

  • --xpos
    write site positions as multiples of  PLAT.

  • --wsite[~options]  |  --wsitex[~options]
    Writes structural data to a site file.
    --wsite   records site positions in Cartesian coordinates while   --wsitex   records site positions as fractional multiples of the primitive lattice vectors.
    Note: For blm, --wsite   is the default mode unless brief=0.
    This tutorial provides an example. Options:
    • ~nofile    suppresses writing a site file; write instead to STRUC and SITE categories in the ctrl file.
    • ~nocat    suppresses writing a SITE category into the ctrl file.
    • ~none    suppresses writing a structural data at all, neither to the site file nor the ctrl file.
    • ~quad1   shift site positions to first quadrant.
    • ~long     writes the site file in long format.
    • ~fn=name   specifies file name.
    • ~ib=list   used to modify certain site-specific inputs. ~ib=list is a list of sites, using Questaal’s standard specification of integer lists (“!” extensions may be used here).
        If this tag is present, selected modifiers following it will modify data written to the site file. These are:
      rlx=#       sets the rlx flag: a triplet of 3 one-integer digits constraining movement along x,y,z when the lattice is relaxed. See Examples below.
      pos=#1,#2,#3   sets the position of this site (note it is nonsensical for the list to exceed one site).
      dpos=#1,#2,#3  shifts the positions of group of sites in list by (#1,#2,#3).
      Example:--wsite~long~ib=1:2,11:12~rlx=010 constrains x and z to stay fixed for sites 1,2,11,12 if lattice is relaxed.
      Example:--wsite~long~ib=1:3~rlx=010~ib=5,7~dpos=0,.01,0 constrains x and z to stay fixed for sites 1,2,3 and also shifts sites 5 and 7 by (0,0.01,0).
  • --wpos=fnam
    write site positions to file fnam.ext file. This tutorial has an example.

  • --wposi
    (molecular statics) at each molecular statics iteration i write write site positions to file pos{i}.ext.

See Table of Contents

Switches for lmchk

lmchk has two main functions: to check augmentation sphere overlaps (and optionally to determine augmentation sphere radii), and to generate neighbor tables in various contexts.

--shell[~options]  |  --shell~tab[~options]  |  --shell~spread@s1=#@@s2=#@d=#[,#]
Print out a neighbor table, in one of the styles described below. Options are delimited by  ~  (or the first character following --shell):
~r=#  Specifies range of neighbor-list, in units of the lattice constant alat. Default value is  2 .
~ra=#  same as ~r=#, but units are atomic units.
~rw=#  same as ~r=#, but units are multiples of the average Wigner-Seitz radius.
~e  prints inner product between Euler angles (relevant to noncollinear magnetism in the ASA)
~fn=fname  writes neighbor table to file fname.ext
~sites~site-list  restricts sites considered to site-list. See here for the syntax of site-list
~pairs~site-list  restricts neighbors to site-list.
~tab  invoke tab mode; see Tab Style below.
~mxcsize=#  you may have to set this parameter if the internal algorithm underestimates the size of the neighbor table.
~nn  restrict table to nearest-neighbor shell (tab mode only)
~checkpl=range  invoke tab mode in special mode to check principal layers.
      range is the range of the hamiltonian lmstr uses to make the structure constants.
      It writes in a format similar to standard mode, but displays only pairs whose principal layer index differs by more than 1.
      Principal layers are needed for the layer Green’s function’s code lmpg.
      A detailed description can be found in Sec 2.14 the Questaal methods paper Comp. Phys. Comm. 249, 107065 (2020).


Styles:

  • Standard style: a neighbors is printed, grouped in shells of neighbors centered the site in question. A table is made for one site in each inequivalent class. Neighbors are grouped by shell:
 Shell decomposition for class K1        class   1  z=19
 shell   d     nsh csiz  class ...
   1  0.000000   1    1  1:K1
   4  0.880105   8   15  4:Se1(8)
   5  1.000000   4   19  1:K1(4)
   6  1.026646   8   27  2:Fe1(4)      3:Fe2(4)
 
  • Tab style: (--shell~tab) a table of neighbors is printed in a table format, for all sites.
 # neighbor list for site 1, class 21x
     1   1   0.0000000   0.0000000   0.0000000     0.0000000  21x      21x
     1  44  -0.2500000   0.2500000  -0.2500000     0.4330127  21x      21
     1  48   0.2500000  -0.2500000  -0.2500000     0.4330127  21x      21
 

This mode prints out site indices to pairs, connecting vector and length, and class labels.

  • Compact Tab style: (--shell~tab=2) prints out the connecting vector only, e.g.
 # neighbor list for site 1, class K1
     0.0000000   0.0000000   0.0000000
     0.0000000   0.0000000  -0.6814628
     0.0000000   0.0000000   0.6814628
 
  • Tab displacement style: (--shell~tab=2~disp=file) special purpose mode that reads in a second set of site positions from file.ext.
    It lists only connecting vectors that are changed relative the original vectors.
    file should take the standard Questaal style for 2D arrays. It can be generated with --wpos.
    This mode synchronizes with lmscell switch --disp~tab2.
    The table prints out both the original vector and the displacement vector, e.g.
 # neighbor list for site 1, class K1
     0.0000000   0.0000000   0.0000000     0.0000000   0.0000000   0.0100000
     1.0000000   0.0000000   0.0000000     0.0000000   0.0000000  -0.0100000
    -1.0000000   0.0000000   0.0000000     0.0000000   0.0000000  -0.0100000
     0.0000000   1.0000000   0.0000000     0.0000000   0.0000000  -0.0100000
 
  • Sparse style : (--shell~tab=3) prints out the connecting vectors in a sparse matrix format

  • Principal layer check mode: (--shell~tab=4~checkpl=#  |  --shell~checkpl=#)
    Special purpose tab mode for lmpg to check for pairs violate requirement that the range of the hamiltonian be limited to nearest neighbor principal layers. Requires that the principal layer indices be assigned.
    A detailed description of the real-space structure constants and how principal layers are used can be found in Sec 2.14 of the Questaal methods paper Comp. Phys. Comm. 249, 107065 (2020).

Example:--shell:tab=2:disp=pos:sites:1:r=3:fn=tab2:nn
writes to tab2.ext a table in this format. The table is restricted to displacements around site 1, distance less than 3 a.u.

--angles[options]
Prints angles between triples of sites.

Options are delimited by  ~  (or the first character following --angles):
~r=#:  Specifies range of neighbor-list, in units of the lattice constant alat~ra=#:  same as ~r=#, but units are atomic units.
~rw=#:  same as ~r=#, but units are multiples of the average Wigner-Seitz radius. Default value is 2.5\
Hazard: Before October 2022, only ~r=# was the only range specification and it had the meaning of ~rw=#.   ~sites~site-list:  loops over center atoms in site-list. See here for the syntax of site-list.
~bonds~site-list:  prints out table only for triples whose neighbors are in site-list.

Example:--angles~sites~1,2~bonds~style=2~z==34
finds triples of atoms connected to sites 1 and 2. Both sites connected to the central site must have atomic number 34 (Selenium). See this tutorial

--euler[options]
Prints angles between spins (applicable to ASA noncollinear magnetism)

Euler angles must be supplied either in the input file, or in the Euler angles file eula.ext (in the standard Questaal format).
Options are delimited by  ~  (or the first character following --shell):
~r=rmax[,rmin]:  Include in table only pairs closer than rmax. If rmin is also given, exclude pairs closer than rmin.
~sites~site-list:  include only sites in site-list. See here for the syntax of site-list.\w   ~sign:  If present, rotate angle by 180° for each member of the pair whose magnetic moment is negative.

Example:--euler~r=10,6~sign~sites~style=2~z==26
finds angles between Fe atoms (Z=26) between 6 and 10 atomic units apart.

--findes[options]
tells lmchk to locate empty spheres to improve sphere packing. This switch operates in the same way as it is used by blm and is documented there. Tags in the ctrl file affecting this switch are:

They can also be included as options to --findes.

--getwsr
tells lmchk to use an algorithm to determine augmentation sphere radii.
Results are printed to stdout; you must modify the input file by hand.
--mino~z  |  --mino[~dxmx=#][~xtol=#][~style=#][~nkill=#][~irlxyz=###][~xrlxyz=###]~site-list
tells lmchk to shuffle atom positions in a site-list to minimize some objective function of the overlap. Using a nonlinear solver, it moves selected site positions iteratively seeking a minimum in the overlap.
(For now, the objective function has been fixed to the sixth power of sum of all positive overlaps).
--mino~z :   construct list from all sites with atomic number Z=0
--mino[~switches]~site-list :   list of sites; see here for site-list syntax.
Each site in the list has three coordinates, x, y and z. By default all the coordinates are relaxed but irlxyz and xrlxyz can constrain the default.
Switches:
  • ~dxmx=#     # = maximum step change in a coordinate in any one iteration
  • ~xtol=#     convergence criterion : no step change larger than #
  • ~style=#    not documented now
  • ~nkill=#    tells the relaxation algorithm to start fresh after # iterations, discarding information it has built up about the hessian matrix
  • ~irlxyz=###    3 digits, not documented now
  • ~xrlxyz=###   3 digits each either 1 or 0, masking default. Thus ###=110 allows x and y to move but not z.
--terse
print minimum information about overlaps.
--wpos=fnam
Writes site positions to positions file fnam.ext.
--wsite[options]  |  --wsitex[options]  |  --wsitep  |  --wpos[~switches] --wdpos[~switches]
Writes structural data to a site file or a positions file.
  • --wsite    writes a site file, with site positions recorded in Cartesian coordinates.
  • --wsitex   writes a site file with site positions recorded as fractional multiples of the primitive lattice vectors.
  • --wsitep   writes a VASP style POSCAR file.
  • --wpos    writes site positions to file, named pos.ext by default. lmf has the equivalent instruction, which see for optional switches.
  • --wdpos   same as --wpos, except that a reference position is subtracted (user must specify reference with switch pos0=filnam)
    Example:--wdpos~shorten~pos0=pos0~fn=dpos

Options/switches to --wsite and the others are delimited by  ~  (or the first character following --wsite):
~short :    write site file in short form
~fn=file :   writes site data to file.ext.
~scala=# :   scales the lattice constant by # and the lattice and basis vectors by 1/#. This performs the same function as switch --scala=# available in the blm code.

If used in conjunction with --findes, lmchk writes to file essite.ext with the basis enlarged by the new empty sites.
blm has a --wsite switch with a similar purpose, but the options are different.

--wspec[~options]
Writes a template SPEC category to file spec. You can also modify some elements written to that file. Options work by specifying a species, and then modifiers pertaining to that species. Specifications and modifiers are delimited by the first character following wspec ( ~  in this case).
Options are:
~nohead :     Omits the first line SPEC (category specification)
~fn=nam :     writes output to file nam
~z=# :      Sets current species to first species with nuclear charge  #
~is=# :      Sets current species to  #
~atom=nam :   Sets current species to species named by nam
~lmx=# :      Assigns  #  to SPEC_ATOM_LMX of current species
~r=# :      Assigns  #  to SPEC_ATOM_R of current species
~rx=# :      Scales SPEC_ATOM_R of current species by  #
~lmxa=# :    Assigns  #  to SPEC_ATOM_LMXA of current species
.
--basis=file
checks whether the given basis matches the basis in site file, up to a fixed translation
--syml[~options]
Creates a symmetry lines file for plotting energy band structures fully automatically. The syntax for this switch can be found here.
--syml~switches-specifying-lines
Creates a symmetry lines file for plotting energy band structures. In this semi-automatic mode, you must specify the endpoints on the lines to draw and the connecting vectors. The syntax for this switch can be found here.

See Table of Contents

Switches for lmfa

lmfa makes atomic densities and basis set parameters for the crystal code lmf. See the PbTe tutorial for a fuller description.

Command-line switches:

  • --tbeh
    • Take smooth Hankel energies for basis from STR_ENV_EL.
  • --noopt
    • Suppress optimization of s.m. Hankel basis.
  • --nopz
    • Suppress search for local orbitals.
  • --norscnst
    • In optimization of s.m. Hankel basis, do not constrain rsm < rmt.
  • --basp[~ctrl~eh=#~eh2=#~incrlmx]
    • Turns on autofind RSMH,EH (also accomplished through HAM_AUTOBAS)
      Options below are delimited by  ~  (or the first character following --basp):
    • ~ctrl:  Use any parameters RSMH,EH, RSMH2,EH2 already specified (from the ctrl or basp files)
    • ~eh=#:  Specify fixed EH
    • ~eh2=#:  Specify fixed EH2
    • ~incrlmx:  Include RSMH,EH to one higher l when writing basp0.ext. Extra RSMH,EH is used only if SPEC_ATOM_LMX is also increased.
  • --basfile=fn
    • write the autogenerated basis set parameters to file fn.ext instead of default basp0.ext.
  • --usebasp
    • Tells lmfa to:
      1. Remake the core density after the search for local orbitals, if one or more has changed.
      2. Write the basis file to basp.ext.

    With this switch you do not have to copy basp0 to basp, or run lmfa again if the valence-core partitioning has changed.

  • --plotwf
    • Writes atomic wave functions to files wfa_spid.ext.
  • --dumprho
    • Dumps atomic density and potential to disk, file out.ext. Operates interactively.

Switches for lmf

lmf is the main density-functional code in the Questaal suite.

Command line switches with links are organized by function in the table below. Use the links for quick reference.

Affects program flow--tbeh  --v8  --ef  --no-fixef0  --ngabc  --getqp  --oldvc  --optbas  --optbas  --quit  --rdbasp  --rdatrho
--rhopos  --rpos  --rs  --shorten=no  --findq  --symsig  --mixspin0  --fixmm  --vext  --zhblock
Additional files generated--band  --cv --wforce  --mull --dos --pdos --scell --pwz --putp
--wden  --wpos  --wrhomt  --wpotmt  --wrhoat   --wratrho
Additional printout--efrnge  --pr  --SOefield  --minmax  --qpate=#
Optics specific--jdosw  --jdosw2  --opt  --cls
QSGW specific--mixsig  --rsig  --wsig  --scrsig
Editors--chimedit  --rsedit  --popted  --wsig~edit

Command-line switches:

--rs=#1[,#2,#3,#4,#5]
tells lmf how to read from or write to the restart file.
  • #1=0: do not read the restart file on the initial iteration, but overlap free-atom densities. Requires atm.ext.
  • #1=1: read restart data from binary rst.ext
  • #1=2: read restart data from ascii rsta.ext
  • #1=3: same as 0, but also tells lmf to overlap free-atom densities after a molecular statics or molecular dynamics step.
  • Add 10 to additionally adjust the mesh density to approximately accommodate shifts in site positions relative to those used in the generation of the restart file. See --rs switch #3 below for which site positions the program uses.
  • Add 100 to rotate local densities, if the lattice has been rotated.

  • #2=0: serves same function as #1, but for writing output densities.
  • #2=1: write binary restart file rst.ext
  • #2=2: write ascii restart file rsta.ext
  • #2=3: write binary file to rst.#, where # = iteration number

  • #3=0: read site positions from restart file, overwriting positions from input file (default)
  • #3=1: ignore positions in restart file
  • #3=2: Like 1, but shifts relative to those in restart file are minimized by adding lattice translations vectors

  • #4=0: read guess for Fermi level and window from restart file, overwriting data from input file (default). This data is needed when the BZ integration is performed by sampling.
  • #4=1: ignore data in restart file

  • #5=0: read logarithmic derivative parameters P from restart file, overwriting data from input file (default).
  • #5=1: ignore P in restart file

Default switches:  --rs=1,1,0,0,0.  Enter anywhere between one and five integers; defaults are used for those not given.

--band[~options]
tells lmf (or any program that accepts --band to generate energy bands instead of making a self-consistent calculation. The energy bands (or energy levels) can be generated at specified k-points in one of three formats, or modes.
  • Symmetry line mode is designed for plotting energy bands along symmetry lines. In this case k-points are specified by a sequences of lines with start and end points. The output is written in special format that plbnds is designed to read.
    This is the default mode; alternatively you can select the list or mesh modes:
  • The 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 Questaal format with k-points followed by eigenvalues.
  • The mesh mode 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 standard Questaal format designed for contour plots.
  • The box mode is a (fourth) special purpose mode used by the band-edge utility.

Unless you otherwise specify, input file specifying the k points is qp.ext, and the output written to bnds.ext for all three modes.

Options below are delimited by  ~  (or the first character following --band):

  • ~qp:  list mode. An arbitrary list of k points can be specified. See here for the input file format.
  • ~con:  mesh mode for contour plot. k-points are specified on a uniform 2D grid; data is written for a specified list of bands.
    The first axis is written to bnds file as the first (row) index; the second as the second (column) index.
    Thus, for a given column the second axis is fixed and increments in row correspond to increments in the first axis;
    while for a given row the first axis is fixed and and increments in column correspond to increments in the second axis.
    Use your favorite contour plotter or fplot’s contour plotting mode that enables you to draw Fermi surfaces in a plane, which uses rows for abscissa and columns for ordinate.
    See here for input file format in this mode.
  • ~box=#[,#…],shape,q0=#1,#2,#3
    Special purpose mode to generate k-points in shells around a central point q0. It is used by the band-edge utility.
    #  is the radius of the shell; you can choose up to 9 shells by specifying multiple values of  #.
    shape  must be one of the following:   n=6[+o]n=8[+o]n=12[+o]n=20[+o]n=32[+o] ,
    which generate a shell of points on cube faces, corners, icosahedra vertices or vertices+faces.
    If  +o  is appended, the origin q0 is added to the points in the shell.
  • ~h5  write bands in hdf5 file format, file name bnds.h5. Works only with ~qp and ~con modes.
  • ~bin:  write bands as a binary file, file name bbnds.ext. Works only with ~qp and ~con modes.
  • ~fn=fnam:  read k points from file fnam.ext. Default name is qp.ext.
  • ~ef=#:  Use # for Fermi level.
  • ~spin1:  generate bands for 1st spin only (spin polarized case).
  • ~spin2:  generate bands for 2nd spin only (spin polarized case).
  • ~mq:   q-points are given as multiples of reciprocal lattice vectors. Applies to symmetry line and qp-list modes only.
  • ~long:  write bands with extra digits for higher precision.
  • ~putqp:  (lmf and lm only) tells calling program to write the q-points read by --band to file qpts.ext, in a qpts file format, and exit.
    A subsequent run of a (any) band program you can use --getqp to substitute this list for the standard mesh.
    Note: this substitution will not be allowed in conjunction with the tetrahedron method, unless the file contains tetrahedron weights.
  • ~rot=strn:  rotates the given k by a rotation given by strn.
  • ~lst=list:  write only a subset of energy levels: specify by an integer list
  • ~rdcolwt=#:  special purpose mode where some color weights may be generated from an external source, e.g. by the --scell construct. # is the total number of color weights.
  • ~nband=#:  Write out no more than # bands (not to be used in conjunction with ~lst !)
  • ~evn=# keep track of smallest and largest eigenvalue for #th band. Print result on exit (purely for informational purposes).
  • ~scol@spec:  assign a family of orbitals for a color weight as specified through the string spec, to emphasize selected orbitals in band plotting.
    It resolves an eigenfunction into orbital contributions using a Mulliken population analysis The list of orbitals you specify are combined to make a weight that should be between 0 (no orbitals) and 1 (all orbitals).
    spec must first identify one or more species or sites; then orbitals are assembled that specification. Specify by one of (1) species name, (2) nuclear charge, or (3) a list of site indices, as shown below. Following the species/site specification, options are available to downselect orbitals a site, e.g. a particular or spin, The syntax is then:
    ~scol@atom=name|@z=#|@sites=ilst[@downselect-opts]
    Here ilst is a integer list of sites, e.g. 1,7.
    You can expand the list of sites with multiple specifications as follows:
    ~scol@atom=name|@z=#|@sites=ilst[@downselect-opts]^atom=name|@z=#|@sites=ilst[@downselect-opts]^…
    The caret  (^)  separates the multiple specifications.
    Note that other delimiters can be substituted for  ~  and  @, though  ^  is reserved for the special meaning above.
    @downselect-opts consist of one or more of:
    • @l=#… (a list of quantum numbers e.g. @l=02 for s and d orbitals (equivalently you can use @l=sd)
    • @m=#… (a list of m quantum numbers e.g. @m=−2,−1,1 which picks up the t2g orbitals dxy, dyz, dxz when is 2 (see this page).
    • @spin1 (noncollinear case) include only the orbitals belonging to the first spin
    • @spin2 (noncollinear case) include only the orbitals belonging to the second spin
  • ~col=orbital-list:  assign a color weight from a collection orbitals specified in an integer list, to emphasize selected orbitals in band plotting.
    orbital-list is extended: e.g. you can use the shriek  (!)  in this context. See this tutorial in the full potential context, or this one in the ASA context.
    Note: ~scol and ~col perform equivalent functions; you can use one or the other, but not both. ~col is completely general, but it is more cumbersome to use.
  • ~scol2@spec:  is like ~scol, but assigns orbitals to the second independent color weight.
      With this option you can create bands with a second independent color.
    Example:--band:scol~z=27~l=d~spin1:scol2~z=27~l=d~spin2:... is for a noncollinear case.
    It assigns any majority spin d orbital resident on a Co atom (Z=27) to the first color, and minority spin d orbital resident on a Co atom to the second color.
  • ~col2=orbital-list generate a second weight to orbitals specified in a list.
    Note: ~scol2 and ~col2 perform equivalent functions; you can use one or the other, but not both.
  • ~scol3@spec:  is like ~scol, but assigns orbitals to the third independent color weight.
      With this option you can create bands with three independent colors.
  • ~col3=orbital-list generate a third weight to orbitals specified in a list.
    Note: ~scol3 and ~col2 perform equivalent functions; you can use one or the other, but not both.
  • ~scolst@spec:  is like ~scol but generates four color weights corresponding to charge and x,y,z spin components of the magnetization.
    This switch is conveniently used together with plbnds in conjunction with the --fplot~spintexture switch. Examples are given here.
  • ~colst  |  ~colst=orbital-list generates four color weights corresponding to charge and x,y,z spin components of the magnetization
    Addition of orbital-list has the same meaning as for usual color weights: each weight is computed from the Mulliken projection of orbitals in the list onto the Pauli matrices.
    Note: ~scolst and ~colst perform equivalent functions; you can use one or the other, but not both.
  • ~coldos   At each q point the DOS is computed and the (first) color weight assigned it. Designed to be used with the ~con switch.
    Note: to use this option dosq.h5 must be present, which is generated by lmdos with the --kresm switch.
    Example:  Assuming ~/lmf/b is your build directory do ~/lmf/b/fp/test/test.fp al 3
  • ~shlist:  Rotate eigenvectors to true spherical harmonics before evaluating color weights
  • ~kmulist:  Rotate eigenvectors to relativistic (kappa-mu) basis before evaluating color weights (SO coupling must be on)

The scol or col option tells the band generator to save, in addition to the energy bands, a corresponding weight for each energy. Each band is resolved into individual orbital character by a Mulliken decomposition The sum of Mulliken weights from orbital-list is the weight assigned to a state. Thus if orbital-list contains all orbitals the weights will be unity. There is an example in the plbnds documentation, which shows how to use that utility to make plots with color weights.

colst is designed to resolve magnetization directions for the noncollinear cases. The four color weights correspond to projections onto the 2×2 unit matrix, and the three Paul spin matrices σx, σy, σz. In the absence of orbital-list the first weight should be unity (unit norm of eigenvector), and the remaining three the x, y, and z components of the magnetization of that state. See the spin texture example in the plbnds documentation.

The individual orbitals make up the hamiltonian basis. States specified in orbital-list corresponding to the ordering of the orbitals in the hamiltonian. You can get a table of this ordering by invoking lm|lmf --pr55 --quit=ham .... Choose orbital-list from the orbitals you want to select out of the Table.

This list can sometimes be rather long and complex. For most cases the simple ~scol option can specify lists without trouble, but there are special cases where the more general ~scol is needed. To accommodate this, some simple enhancements are added to the standard integer list syntax.

--rhopos
Render all three components density everywhere positive. (This can be in an issue because of the three-fold representation of the density). --rhopos
Override EWALD_TOL and HAM_TOL read from input file, substituting #. Optional #2 overrides HAM_TOL differently from EWALD_TOL.
--rpos=fnam
tells lmf to read site positions from fnam.ext after the input file has been read. fnam.ext is in standard Questaal format
--wpos[options]
tells lmf to write site positions to positions file fnam.ext after self-consistency or a relaxation step.
Simple option: specify name by --wpos=fnam. Fuller options are delimited by  ~  (or the first character following --wpos):
  • ~scale#:  scale all coordinates by #
  • ~mode=#:  write file in mode=#. mode can select an alternate format for this file.
  • ~fn=nam:  specify file name
  • ~wdlat:  Write the change in positions relative to those initially read from the ctrl, site or a positions file, or contents of the rst file if they are read from there. This may used to determine the lattice translations vectors that were added to position vectors to shorten them.
    Example: : lmf -vnit=0 --wpos~wdlat~fn=dlat~shorten=1
    reads positions from the rst file, performs no iterations, adds lattice vectors to shift positions to the first octant, and writes tthe difference to file dlat.
    If --rs=0,0 were also included, lmf would write lattice translations that modify the positions as read from the input.
  • ~shorten[@opts]:  shorten site positions before writing. Options are the same as for --shorten described above, e.g. --wpos~shorten@1,1,2. Note: If you use ~shorten, make it the last tag to avoid ambiguities in parsing its subarguments.
--wposi
Similar to –wpos , used in conjunction with relaxation algorithms. Site positions are written at each relaxation step to file posi, where &\thinsp;i&\thinsp; is the relaxation step.
--dos[~options]
tells lmf to generate weights for total density-of-states. This switch uses the following options also used by the switch  lmdos --dos  for lmdos’s postprocessing step to generate partial DOS:
npts=#h5ef0idoswindow=#,#
Example: : lmf --dos:h5:ef0:window=-1,1
--pdos[~options]  |  --mull[:options]
tells lmf to generate weights for partial density-of-states (projected onto augmentation spheres) or Mulliken analysis resolved by orbital. Options are described here.
--scell[~options]
A switch to use the Brillouin zone unfolding function.
Options:
  • ~job=-1   generates bands and plane-wave expansion coefficients of eigenfunctions for the supercell, written into evec.h5.
  • ~job=1    reads bands and plane-wave expansion coefficients of the supercell, construct a projection onto k in the primitive the eigenfunction of the supercell
  • ~job=2    construct a projection onto k in the primitive the eigenfunction of the supercell
  • ~job=11    same as ~job=1, but uses 1−projection onto k for the weight.
  • ~job=12    same as ~job=2, but uses 1−projection onto k for the weight.
  • ~shear    allows for the supercell to include a shear relative to the primitive cell.
--pwz~mode[~options]
Generates plane representation of eigenfunction, for various purposes.
For mode, choose between one of the following
  • ~env Substitute for envelope
  • ~aug Substitute for envelope
  • ~all Generate as
    Options:
  • ~norm Normalize eigenfunctions
  • ~pprt[=#1,#2] Prints information about . Depending on whether #1, #2 are present:
       #1 refers to which eigenvector, and prints , , on the regular mesh
       #2, if present, prints , , in spheres, in the representation. #2 refers to which lm.
  • ~ipar Generate inverse participation ratio, defined as .
--optbas[~sort][~etol=#][~spec=spid[,rs][,e][,l=###]…]
Operates the program in a special mode to optimize the total energy wrt the basis set.
lmf makes several band passes (not generating the output density or adding to the save file), varying selected parameters belonging to tokens RSMH= and EH= to minimize the total energy wrt these parameters.
Options are delimited by  ~  (or the first character following --optbas):
  • etol=#:  only adjust parameter if energy gain exceeds #.
  • spec=spid,rs: Optimize wrt RSMH for a particular species.
  • spec=spid,e: Optimize wrt EH for a particular species.
  • spec=spid,rs,e: Optimize wrt both RSMH and EH for a particular species.
  • spec=spid…,l=###: Specify which to optimize (default is all in the basis)
  • No species given:  lmf optimizes wrt RSMH for each species.
  • sort: sort RSMH from smallest to largest. The total energy is more sensitive to small RSMH;, then the most important parameters are optimized first.
--putqp[:fn]  |  --getqp[:fn]
--putqp tells the program to write the list of q-points to file qpts.ext, and exits.
If fn is supplied, qp and weights are written to fn.ext. If the tetrahedron method is set, data for the tetrahedra are also written.
--getqp performs the inverse operation: it tells the program to read the q data from file qpts.ext (or fn.ext if supplied), substituting it for the regular mesh.
qpts.ext takes a special-purpose format specific to qp data.
--rdbasp[:fn]
tells the program to read basis parameters from file fn. If not present, fn defaults to basp.ext. This supersedes settings in HAM_AUTOBAS.
--ngabc=#1[#2,[#3]]
Specifies the charge density mesh from the command line, overriding input read through HAM_GMAX or HAM_FTMESH in the ctrl file. If not specified, #2 takes the value of #1; if not specified, #3 takes the value of #2.
The three numbers correspond to the number of divisions in the lattice vectors and have the same meaning as n1,n2,n3 in the description of --wden.
--wden[~options]  |  --wden[~atpos]
tells lmf to write the charge density to disk, on a uniform of mesh of points.

At present, there is no capability to interpolate the smoothed density to an arbitrary plane, so you are restricted to choosing a plane that contains mesh points. To make this translation a little easier, there is second form,   --wden~atpos   : a special-purpose information mode to help you locate site positions as multiples of mesh points. You can run this mode at any time; it does nothing but print out an information and exit.

Options syntax:
[~fn=fnam][~core=#][~spin][~3d][~ro=#1,#2,#3 | ~o=#1,#2,#3][~shft0][~q=#1,#2,#3][~lst=band-list][~l1=#1,#2,#3,[#4]][~l2=#1,#2,#3,[#4]]

Information for the plane is specified by three groups of numbers: the origin (o=), i.e. a point through which the plane must pass; a first direction vector l1 with its number of points; and a second direction vector l2 with its number of points. Default values will be taken for any of the three sets you do not specify. The density generated is the smooth density, augmented by the local densities in a polynomial approximation (see option core)

To comply with this restriction, all three groups of numbers may be given sets of integers. Supposing your lattice vectors are p1, p2, and p3, and the smooth mesh has (n1,n2,n3) divisions. Then the vector (l1=#1,#2,#3) corresponds to
v1 = #1/n1 p1 + #2/n2 p2 + #3/n3 p3
Specify the origin (a point through which the plane must pass) by
~o=i1,i2,i3
Default value is o=0,0,0. Alternatively you can specify a the origin in Cartesian coordinates by:
~ro=x1,x2,x3
(x1,x2,x3) a vector in Cartesian coordinates, units of the lattice constant alat, and it is converted into the nearest integers i1,i2,i3. Thus the actual origin may not exactly coincide with (x1,x2,x3).

Options are delimited by  ~  (or the first character following --wden):

  • ~l1=#1,#2,#3[,#4]  first direction vector as noted above, that is:
    #1,#2,#3 select the increments in mesh points along each of the three lattice vectors that define the direction vector.
    The last number (#4) specifies how many points to take in this direction and therefore corresponds to a length. Default values : l1=1,0,0,n1+1 where n1 is the number of points on the third axis.
  • ~l2=#1,#2,#3[,#4]  second direction vector as noted above, and number of points (#4)
    Default values : l2=0,1,0,n2+1 where n2 is the number of points on the second axis.
  • ~core=# specifies how local densities are to be included in the mesh.
    Any local density added is expanded as polynomial * gaussian, and added to the smoothed mesh density.
    • #=0  includes core densities + nuclear contributions
    • #=1  includes core densities, no nuclear contributions
    • #=2  exclude core densities
    • #=-1  no local densities to be included (only interstitial)
    • #=-2  local density, with no smoothed part
    • #=-3  interstitial and local smoothed densities
      Default: core=2
  • ~fn=filnam  specifies the file name for file I/O. The default name is smrho.ext
  • ~veff  write (pseudo-) effective potential to file, instead of charge density
  • ~3d   causes a 3D mesh density to be saved in XCRYSDEN format
  • ~shft0  (used for output in 2D) cyclically shifts rows and columns so the origin falls in the center of the raster, rather than as the first point.
  • ~q=q1,q2,q3 and lst=list-of-band-indices
    These switches should be taken together. They generate the density from a single k-point only (at q) and for a particular set of bands. Use integer list syntax for list-of-band-indices.

Example:  suppose n1=n2=48 and n3=120. Then
--wden~fn=myrho~o=0,0,60~l1=1,1,0,49~l2=0,0,1,121
writes to myrho.ext a mesh (49,121) points. The origin (first point) lies at (p3/2) since 60=120/2. The first vector (l1=1,1,0,49) points along (p1+p2) and has that length (48+1); the second vector points along p3 and has that length.

Example:  suppose the lattice is fcc with n1=n2=n3=40. Then
--wden~q=0,0,0.001~core=-1~ro=0,0,.25~lst=7~l1=-1,1,1,41~l2=1,-1,1,41
generates the smoothed part of the density from the 7th band at Γ, in a plane normal to the z axis (q=0,0,0.001 is slightly displaced off Γ along z), passing through (0,0,0.25).

See this tutorial for a demonstration.

--cv:lst  |  --cvK:lst
Calculate electronic specific heat for a list of temperatures. You must use Brillouin sampling with Fermi function: BZ_N=−1.
Data is written to file cv.ext. An application of this switch can be found here.
--wforce=fn]
causes lmf to write forces to file fn.
--efrs
Use the Fermi level read from the rst
--ef
Override file Fermi level; use with --band

--v8 Uses Pashov’s redesign of lmf. Note that Pashov’s redesign can operate in either an unscreened mode a screened one. For the latter, set STR_ENV_MODE=1.

--tbeh
Makes global substitution of smooth Hankel energies EH and EH2. Taken from STR_ENV_EL.
Useful when turning on the screening mode in lmf-related programs (STR_ENV_MODE=1).
--efrnge
Print out indices to bands that bracket the Fermi level
--no-fixef0
Do not adjust estimate of Fermi level after first band pass
--oldvc
chooses old-style energy zero, which sets the cell average of the potential to zero. By default average electrostatic potential at the augmentation boundary is chosen to be the zero. That puts the Fermi level at roughly zero.
--findq=q1,q2,q3  |  --findq~mq~q=q1,q2,q3
When generating a k-mesh of points, find the mesh point closest to q=(q1,q2,q3).
Optional mq declares that (q1,q2,q3) is expressed in terms of crystal coordinates, i.e. fractional multiples of reciprocal lattice vectors.
--symsig  |  --symsig=no
Symmetrize sigma overriding default behavior, or suppress symmetrizing it
--SOefield
Makes SO-weighted average of electric field at each site. Used for estimating size of Rashba effect.
--minmax[~ef0[=#]][~ev]
Prints highest and lowest eigenvalue found for each band. Options:  ~ef0  aligns the levels relative to the Fermi level;  ~ef0=#  aligns the levels relative to  #;  ev  scales the energies from Ry to eV.
--qpate=#
Finds bands and tetrahedra that encompass a given energy  #, and prints out estimated k point for each band. Must use in conjunction with tetrahedron integration.
--mixspin0
When the charge density is mixed in a spin-polarized case, the spin component is zeroed out.
--fixmm[~options]
Constrains selected site-local magnetic moments to target values. This is done by varying an external magnetic field iteratively until the constraints are satisfied. This can be a tedious process unless the Hessian (bare susceptibility χ0 = dMi/dj) is known. In this context χ0 it is found numerically from small discursions in around a starting point, which you supply. Information needed to build χ0 is assembled in one of two ways: the gradient method (default) or a modified regula falsi method. After all constraints have been passed through, a Hessian matrix is available, which supplies the inverse of χ0. An estimate for the change in the external magnetic field Δ can be obtained from χ0−1 ΔM, where ΔM is the deviation of the magnetic moment from the target value, for some reference .
χ0−1 and a reference pair of (M,) vectors is written to file chi0.ext.h5.
Options:
  • grad (gradient method): dM/d is made by finite difference, to construct the Hessian.
  • rfalsi (regula falsi method): Each constraint is satisfied using a modified regula falsi method, neglecting cross coupling between constraints.
    χ0 is not required with regula falsi, but there is an option to use the available information to estimate for χ0−1, and follow up with linear response iterations.
  • nrfalsi=# : same as rfalsi, but also specifies maximum number of rfalsi steps taken for a particular channel.
    Note: choose either rfalsi or grad, but not both.
  • linresp=# Number of cycles to estimate for Δ by linear response for a given χ0, before updating χ0 with the gradient or rfalsi method. In the gradient case, this must be at least one; in the rfalsi case it can be a number, or zero. Default is 2.
  • mxcycle: Maximum number of constrained-moment cycles before exiting to outer self-consistency loop. This number will be rounded to be constisent with linresp.
  • writeb=# Frequency at which external field file (bfield.ext) is written
         #=0 : never
         #=1 : after global convergence
         #=2 : after convergence in a cycle
         #=3 : after convergence in a channel
  • writec=# Frequency at which χ0−1 is written to chi0.ext.h5
         #=0 : never
         #=1 : When linear response estimate for change Δ in is less than btol
         #=2 : Any time χ0−1 is updated
  • readc  : In this mode, χ0−1 is not calculated, but it used to estimate Δ. χ0−1 must have been calculated previously and reside in chi0.ext.h5.
  • writem  : Special mode to record a consistent set of (M,ᗷ ) pair of vectors. After one band pass, (M,ᗷ ) are written to chi0.ext.h5, and the code exits.
  • fullrho  : The calculated magnetic moments are taken from the full density. By default it is taken from the ASA moment, i.e. the products of partial waves of the same .
  • mom=#  : Target local moments specified sites should meet. Site specification precedes this tag; see below.
    Note: this should be the last argument of any constraint.
  • z=#  : specify that a target moment following this tag (mom=#) apply to all sites with this Z.
  • ib=lst  : specify that a target moment following this tag (mom=#) apply to all sites in lst
  • eq=lst  : list of sites which are linked to the previously specified site. for all sites changes in tandem
  • beta=#  : Mixing for linear response, thus Δᗷ actual = beta × χ0−1 ΔM.
  • mtol=#  : Tolerance (deviation from target) ΔM to be satisfied before exiting to self-consistency cycle
  • db=#  : Initial step when taking finite difference in
  • dbmx=#  : Do not allow any change Δ to exceed #.

Example : –fixmm~writeb=1~mtol=1e-3~z=28~mom=0

A tutorial using this method can be found here.

--vext~step[~options…]~v=#  |  --vext~igv[~options…]~v=#
An external potential is added to the LDA hamiltonian. The size of the external potential is given by the argument following (~v=).  (Options are delimited by the first character following --vext, which is assumed to be  ~  in this description.)

is specified by a rule which can assume one of two forms (in reciprocal space, through --vext~igv~…, or in real space, through --vext~step~…). In either case is symmetrized by whatever symmetry operations are used.

The ~eps and ~eps=# _options
For either style, you may add an optional switch ~eps or ~eps=#. This will cause lmf to print an analysis of the response function. This analysis is printed at each iteration in the self-consistency cycle.

For the input density it prints a table including the static inverse dielectric function defined as , in a table like the following:

ig       kv       pi8/q2             dphitot               phiext               eps^-1
 2   1   1  88   336.143728   0.0034403 0.0000000   0.0100000 0.0000000   0.3440276 0.0000000
 3   1   1   2   336.143728   0.0034403 0.0000000   0.0100000 0.0000000   0.3440276 0.0000000

In this case (called phiext in the table) has two Fourier components, which correspond to two points (kv) on the density mesh (reciprocal space). Note: index 1 corresponds to k=0 along the direction of that lattice vector.

For the output density a table is printed including the response function, defined as , in a table like the following:

ig       kv       pi8/q2              drho                dphitot                phiext                R
 2   1   1  88   336.143728   -2.017e-5 0.0000000   0.0039812 0.0000000   0.0100000 0.0000000   -0.002017 0.0000000
 3   1   1   2   336.143728   -2.017e-5 0.0000000   0.0039812 0.0000000   0.0100000 0.0000000   -0.002017 0.0000000

The analysis applies if either ~eps or ~eps=eps0 is specified. The latter option has an additional feature, namely at the starting iteration it estimates the screening charge for a dielectric constant you specify by eps0. It assumes that, for each Fourier component, . It will print out a table similar to the following:

ig       kv        pi8/q2             rho0                 drho                  dphi
 2   1   1  88   336.143728   0.0000000 0.0000000   -1.983e-5 0.0000000   0.0100000 0.0000000
 3   1   1   2   336.143728   0.0000000 0.0000000   -1.983e-5 0.0000000   0.0100000 0.0000000

The ~pot0 option

To calculate the perturbation there has to be a memory of the initial unperturbed potential (density). lmf keeps track of the intial potential. If you begin execution from a self-consistent density for the unperturbed case, at self-consistency the difference in starting and final potential are indeed the perturbation. However, if you start from a different density, e.g. the self-consistent density after the perturbation was added, or a density modified with ~eps=#, the perturbation lmf prints out is fictitious.

The ~pot0 switch makes it possible to retain an original potential so perturbations can be properly calculated. Including this switch causes lmf to write whatever Hartree potential it has generated from the given density to file smpot0.ext, and exit.

Any subsequent invocation of lmf with --vext~eps will cause the reference potential and density to be read from this file, and the perturbation is calculated as the change in the current potential (density) relative to the reference potential (density) stored in smpot0.ext.

Specifying with a single Fourier component

The syntax is : --vext~igv=#1,#2,#3[~eps[=#]][~pot0]~v=#

~igv=#1,#2,#3 defines a particular k point, by . , , and are the number of divisions along each of the three reciprocal lattice directions. This information is printed at the start of execution: in this example, it prints out

GVLIST: gmax = 10.5 a.u. created 12317 vectors of 22528 (54%)
        mesh has 16 x 16 x 88 divisions; length 0.352, 0.352, 0.320

Evidently has nonzero points (1,1,2) and (1,1,88), which correspond to the first and last points along . It was specified by --vext~igv=0,0,1; to make the potential real two Fourier components are required, corresponding to mesh points (1,1,2) and (1,1,88). Note: in the specification indexing starts at 0, while the indexing of the mesh density starts at 1.

Example : –vext~igv=0,0,1~eps=3~v=.02

Specifying in real space

At present the available option is to specify a step potential for a family of adjacent planes.
The minimum syntax is : –vext~step=#~l1=#1,#2,#3~l2=#1,#2,#3~v=#\

  • ~step=# tells lmf how many planes the potential spans. You can use ~stepx=# in place of ~step=#: this shifts the average perturbation to zero.
  • ~l1 and ~l2 define points in a plane in the same manner as described for the --wden switch.
    The first plane can also be specified with [~ro=#1,#2,#3] or [~o=#1,#2,#3] as described there.
  • ~v=# gives the size of the step.
  • You can use the ~eps, ~eps=#, and ~pot0 options in this mode.

Example : –vext~stepx=44~o=0,0,22~l1=1,0,0~l2=0,1,0~eps=3~v=.02

With a mesh density of 16×16×88 divisions and the following lattice vectors:

0.000000   0.500000   0.500000
0.500000   0.000000   0.500000
2.500000   2.500000   0.000000

a step potential in 44 planes perpendicular to is created, with zero average value:

Add external potential vext = 0.02 in 44 planes passing through origin at (0,0,22)
Origin, in cartesian coordinates  0.625000 0.625000 0.000000
v1: (16+1 pts) = (1,0,0)(p1,p2,p3) = (0.000000,0.500000,0.500000) l=0.707107
v2: (16+1 pts) = (0,1,0)(p1,p2,p3) = (0.500000,0.000000,0.500000) l=0.707107
Angle between vectors : 1.047198 radians = 60 deg

Unit normal vector (0.577350,0.577350,-0.577350).  Origin lines in plane 22
NN planes connected by (0,0,1)(p1,p2,p3) = (0.028409,0.028409,0.000000)
Planes separated by 0.032804, 88 planes to shortest period, 88 planes in normal direction
Put vext in 44 planes in interval [22,65] (50.0 %)
vext added to 11264 points out of 22528 (50.0 %)  <v>=0.01 (remove avg => <v>=0)
--rdatrho[~v0]   |   --wratrho
Reads/writes the =0 part of sphere densities and potential to atmx.ext. This file has the same form as the atomic file atm.ext generated by lmfa. However the spherical density and spherical potential V0 are taken from lmf’s current contents, e.g. the self-consistent density. By reading data from atmx.ext you can start with a better trial density when overlapping “atoms” Also, V0 is used to make partial waves φl. If also V0 is frozen (e.g. using HAM_FRZWF=t), the partial waves are constructed from this information, when V0 is read from this file.
--wrhoat
Write partial atomic densities to atom files.
--wrhomt  |  --wpotmt
Not documented yet.
--zhblock~block[~~block…]
Modifies selected blocks of the hamiltonian and overlap matrices, H and S. Both H and S are modified, though there are exceptions (see ~orth and ~nos below). Modifications are performed for one block, and if a subsequent block is specified, modifications are performed for it. Each block operates in one of two modes, scale and shift. The remaining discussion refers to a single block.

Scale mode This is the default mode (if ~shft=# is not encountered). Of the following tags that are sought, either rows or rowsx must be specified; the remaining are optional. Note that whatever is done to a row is also done to a column, to preserve the hermiticity of the matrix. This is implied when referring to rows in the following.

  • ~rows=list    Scale a list of rows and corresponding list of columns. list is an an integer list. The corresponding list of columns is implied, or specified through ~cols.
  • ~rowsx=list   Same as ~rows=list, but the list is comprised of all rows are not in list.
  • ~cols=list    If not specified, the column list is comprised of all columns not not in the row list.
  • ~colsx=list    Same as ~cols=list, but all columns are taken not included in list.
  • ~s=#      Scale off-diagonal elements by #, if specified. If this tag is not present, # is 0. You can also specify two numbers, #1,#2. If #2 is not specified it is assigned to #1.
  • ~e=#      Assign the diagonal element Hii to # × Sii if S is present, and to # if it is not. In the spin polarized case, you can specify two numbers #1,#2, corresponding to two spins. If #2 not given, #1 is used for both spins.
  • ~orth       S is Cholesky-decomposed into U† U, and internally the routine operates on (U†)−1H (U)−1. On exit H is restored with the scaling U† HU,
  • ~nos      Modify H only; leave S untouched.

Example 1:   --zhblock~e=-1.5,1.4~rows=10:16~cols=1:rank
For each i among 10:16 and j spanning the entire basis, Hij and Sij are scaled to 0.
The block structure of H (divided into rows and columns 1:9, 10:16, 17:rank) should be as follows.
  U | 0 | U
  0 | D | 0
  U | 0 | U
U means unchanged, D means diagonal, 0 means zero. The (H,S) pair should yield 7 eigenvalues at −1.5 Ry, and the remaining eigenvalues should correspond to those of the hamiltonian with the middle block absent.
This enables you to determine the effect a block of orbitals on the environment. Note that you may use symbol rank to denote the hamiltonian rank, i.e. the number of rows.
Other things to try:

  1. leave out the e=-1.5,1.4. Now the diagonal elements of D are preserved
  2. leave out both e=-1.5,1.4 and ~cols=1:rank. This leaves the full subblock D intact and the eigenvalues will be that of the isolated subblock, together with the eigenvalues of the remainder of the hamiltonian.

Example 2:   --zhblock~rows=10:16~cols=10:16
Leaves H unchanged except the (10:16,10:16) block becomes a diagonal matrix. This enables you to see the effect of the off-diagonal, onsite matrix elements.

Example 3:   --zhblock~rows=5,6,8~cols=7,9
Leaves H untouched, except for matrix elements coupling the on-site t2g to the eg block. Both t2g and eg remain coupled to the rest of the lattice.

Example 4:   --zhblock~rowsx=1,17~colsx=1,17~e=5~~rows=1,17 (an example with two blocks)
In the first block, all off-diagonal elements apart from rows and cols not in (1,17) are zeroed out, and the diagonal element set to 5 Ry. In the second block all off-diagonal elements linking rows or columns 1 or 17 are zeroed out. The end result is the 2x2 block comprised of (1,17) are isolated from the rest, and the rest of the hamiltonian is diagonal, and will yield eigenvalues = 5 Ry.

Shift mode : diagonal elements Hii are shifted.
To invoke this mode, specify ~shft=#. ~rows=list, ~rowsx=list, ~orth, ~nos have the same meaning as in the scale mode, and ~rows=list or ~rowsx=list must be specified as in the scale mode. However, you cannot use ~cols=list or ~colsx=list because only diagonal elements are affected.

Example 5:   --zhblock~orth~rows=9,25,30,seq=39~shft=.1
Shifts diagonal elements Hii by 0.1 Ry, for i=9,25,40,39,55,60. ~orth causes H to internally orthogonalized before adding the shift; the nonorthogonality is restored on exit.

To facilitate the construction of  list, you can see how the basis is ordered by invoking lmf this way:

lmf --pr55 --quit=ham ...

Inspect the table following this header:

Orbital positions in hamiltonian, resolved by l:


The following switches concern the optics branch of both lmf and lm.

--jdosw  |  --jdosw2
Mulliken projection of channels for optical properties.

You can project onto one linear combination of basis functions (--jdosw) or two (also use --jdosw2).

  • For joint DOS and optics, use --jdosw~list1~list2; use --jdosw2~list1~list2 for a second projection.
    list1 is an integer list referring to occupied states, list2 to unoccupied states.
  • For single DOS, use --jdosw~list1 and optionally --jdosw2~list1.

Data is written to file jdos.ext; source code is found in optics/optint.f.

See this tutorial for an example.

--opt:read  |  --opt:write
Read or write matrix elements of the square of the velocity operator |v|2 to file optdata.ext.
  • Data is read or written for each band pair, k point, and spin (optical matrix elements).
  • |v|2 is symmetrized according to the given symmetry operations.
  • In the read case, the band pass is skipped and the band code proceeds directly to making the dielectric function (or a similar property).
  • In the write case, the band pass is skipped and the band code exits after writing; the dielectric function is not made.
--opt:woptmc  |  --opt:woptmc,rdqp
Writes the matrix elements both of the velocity operator v and |v|2, to file optdatac.ext.
  • |v|2, is symmetrized, but v is not.
  • Addition of modifier  ,rdqp  causes lmf to read the k-points from qpts.ext.
    Note:  to cause lmf to read the k-points in the same order that the GW codes require them, run lmfgwd with  --job=6  or  --job=7  and run lmf with  –opt:woptmc,rdqp.. This is necessary when setting up the velocity operator for Bethe-Salpeter equation.

See optics documentation.

--cls[.ib,l,n[.ib,l,n][.lst=list,l,n][.fn=file]]
Core level spectroscopy. After lmf completes, follow up the calculation with lmdos to generate a DOS-like file.
The theory used for this switch is described in J. Phys.: Condens. Matter 12 (2000).
To carry out CLS calculations in a potential containing a core hole, see tags SPEC_ATOM_C-HOLE and SPEC_ATOM_C-HQ when making the self-consistent density.

You must supply a list of core levels (site, , and principal quantum number n) for which to calculate CLS.
Do it in one of three ways, through modifiers. Modifiers are separated by   .  (any separator will do, e.g.   # , other than   :   or   , ).

  • ib,l,n is a triple of site,core-l,core-n
  • lst=list,l,n is a list of sites having and n in common
  • file=fname is a file of records of triples ib,l,n.

Example:  --cls#2,1,2#4,2,3#lst=3,5:7,0,1
produces the following list of (ib,l,n) for which to calculate CLS.

siteln
212
423
301
501
601
701

Tutorial:  See this tutorial and this tutorial.

Demonstration:  This makes CrN self-consistent with a core hole on a N 1s state, and performs CLS calculation in that potential. It corresponds to a ‘sudden approximation’ (system relaxes instantaneously from electron ejected out of a core hole).
In your build directory do

./fp/test/test.fp crn

The CLS is written to a file in the DOS format. The script will ask you if you want to draw a figure of the CLS.

See Table of Contents

The following switches affect how lmf reads, writes, or modifies the QSGW self-energy Σ0.
Note:  Σ0 is stored in practice as , so that this potential can be added to the LDA potential.

--mixsig=#1[,#2]
lmf reads QSGW self-energy Σ0 from two files, sigm.ext and sigm1.ext. For Σ0 it takes the linear combination  #1×sigm.ext + #2×sigm1.ext.
If #2 is missing, it does not read sigm1.ext but scales Σ0 by #1.
--rsig[~options]
Tells lmf about the form of the input self-energy file.
Options are delimited by  ~  (or the first character following --rsig).
  • ~ascii  read from file sigma in ASCII format (see table below)
  • ~rs  read in real space (see table below)
  • ~null  generate a null consistent with the hamiltonian dimensions. Useful in combination with the static sigma editor.
  • ~fbz  flags that is stored for all k points in the full Brillouin zone. Equivalent to setting 10000s digit=1 in token RDSIG= . (Not meaningful if the ~rs switch is used)
  • ~spinav  average spin channels in spin-polarized sigma
  • ~rlxkp  when reading , do not impose requirement that each k correspond to the file k.
    Not generally advised, but useful in certain contexts, e.g shearing a lattice.
  • ~shftq=#,#,# indicates that sigma was generated on a kmesh offset by  #,#,#  are optional; then a default of three small numbers is used.

If either ~ascii or ~rs is used, the input file name may change:

 k-spacereal-space                                
binarysigmsigmrs
asciisigmasigmars
--wsig[~options]
Writes a possibly modified QSGW self-energy to sigm2.ext (or sigm2rs.ext if ~rs is present) and exits.
Options are delimited by  ~  (or the first character following --wsig):
  • ~ascii  read sigm in ascii format (see table below)
  • ~newkp  generate sigma on a new k mesh. It reads the mesh from GW_NKABC.
  • ~edit  invoke the static sigma editor. This editor has many options, which you can see by running the editor.
  • ~rs  write in real space, to file sigm2rs.ext. Note that --rsig:rs reads R.S. from file sigmrs.ext. Rename sigm2rs.ext to sigmrs.ext to read this file.
  • ~fbz  causes lmf to ignore symmetry operations and generate a sigma file for k-points in the entire BZ. It is useful when generating a sigma file that allows fewer symmetry operations, e.g. when making the m-resolved density-of-states, or a trial sigm for a case (such as a shear) where symmetry operations are lowered.

The following are special-purpose modes:

  • ~spinav  average spin channels in spin-polarized sigma
  • ~onesp  Replace spin-polarized sigma with non-spin polarized one, averaging spins. Cannot be used in conjunction with wsig~edit
  • ~rot    rotate the sigma matrix.
  • ~trans=## specifies how sigma is to be modified, or if some special object is to be constructed instead of a band pass.
    • trans=1  Read sigm, save as-is Bloch-transformed sigm into file sigm2.ext.
    • trans=2  Read sigm, rotate from orbital basis to LDA basis and save into file sigm2.ext.
    • trans=3  Read sigm, approximate high-energy block by a diagonal matrix, and save sigm in LDA basis
    • trans=4  Make and save LDA eigenvalues, eigenvectors
  • ~phase  Add phase shift to sigma
  • ~sumk  sum sigma over k. Implies fbz
  • ~wvxcf  read vxc file and write as vxcsig (used by lmfgwd).
  • ~shftq  add qp offset to qp where sigma is made.
--scrsig[~switches]
Reads and subsequently writes a QSGW self-energy , possibly converting to/from screened form, and possibly to/from h5 format.
Switches are delimited by  “:“  for now:
  • :ifl=infile  : read from infile, which must be the full file name. If extension .h5 appears at the end, it is assumed to be in h5 format; otherwise traditional binary format is assumed.
  • :ofl=outfile  : write to outfile, which should be the full file name. If extension .h5 appears at the end, it is assumed to be in h5 format; otherwise traditional binary format is assumed.
  • :in=s  |  :in=u : infile is either screened (in=s) or unscreened (in=u)
  • :out=s  |  :out=u : outfile is either screened (out=s) or unscreened (out=u)

Additional notes:

  • This switch is only active if you have turned on the screened branch of lmf  (--v8 --tbeh)
  • Switches ifl, ofl, in, out are all required.
  • outfile and infile should be different.
  • If in and out are equal, no transformation is performed; the file contents are copied unchanged.
  • You are advised to include --shorten=no in conjunction with this switch.

Example:   lmf ctrl.yfege --tbeh --v8 -vrsham=2 --scrsig:ifl=sigm.yfege:ofl=sigm.screened:in=u:out=s

See Table of Contents

Switches for lmfgwd

lmfgwd is the interface to the GW code.

Command-line switches:

--jobgw=#  |  --job=#
Tells lmfgwd what to make.
  1. Performs some sanity checks on GWinput.
  2. create GWinput template, and also KPTin1BZ, QIBZ.
  3. init mode : create files SYMOPSSYMOPSLATTCCLASSNLAindx.
  4. driver mode: make interface to the GW code: files  gwb.extgw1.extgw2.extgwa.extvxc.extevec.extnormchk.extrhoMT.*.
--vxcsig
Write QSGW Σ0 in place of LDA exchange-correlation potential into vxc file. Use this switch when you are performing 1-shot GW calculations as a perturbation around the QSGW potential: the perturbation is Σ−Σ0.
--lcut~switches
Assigns augmentation lcutmx for selected sites. Syntax is:
~site-id=strn~l=#
site-id= can be one of z=# or is=# or atom=name.
Example:--lcut~z=8~l=3 sets lcutmx to 3 for all O atoms.
--shorbz=no
Suppress shortening of k-points.

The following switches apply to GWinput creation mode (--job=−1):

--gwin0
Read parts of GWinput template from GWin0. Portions of GWin0 may substitute for corresponding parts in GWinput.

The GWinput syntax is roughly similar to the standard Questaal format but the syntax is more restricted. The file structure is documented here.

  • Header (comments and tags at the top of the file, preceding the <PRODUCT BASIS> category. The header is read from GWin0 and used in place of GWinput. Next, the following line is written to GWinput:

    ! Supply possible tags not found in GWin0
    

    As the GWin0 file is read, the following tags are logged:

    • GWversion
    • KeepEigen
    • KeepPPOVL
    • BZmesh
    • WgtQ0P
    • NormChk
    • n1n2n3
    • QpGcut_psi
    • QpGcut_cou
    • unit_2pioa
    • alpha_OffG
    • emax_sigm
    • dw
    • omg_c
    • iSigMode
    • niw
    • delta
    • deltaw
    • esmr
    • rsm
    • GaussSmear

    Any tags in this list not logged are written to GWinput. in the same form that they would have been otherwise written.

  • Product basis section, which begins with delimiter <PRODUCT_BASIS>.
    These lines follow the delimiter:

    tolerance = minimum eigenvalue in PB overlap to reduce linear dependency
    [one or more floating point numbers]
    lcutmx(atom) = l-cutoff for the product basis
    [sequence of integers, one for each atom]
    

    If tolerance is present in GWin0, that line and the line following are substituted for the two lines that would normally be written.

    If lcutmx(atom) and the following line are present in GWin0, they are substituted for the two lines that would normally be written.

  • QPNT section, which begins with delimiter <QPNT>.

    If the following line is present in GWin0, it and the one following it are substituted for the two lines that would otherwise be written.

    *<b> Sigma ...
    

    If the following line is present in GWin0, it and the pair following it are substituted for the three lines that would otherwise be written.

    </b>* no. ...
    

    If the following line is present in GWin0

    *<b> q-points ...
    

    it and all subsequent lines to the end-of-section (delimited by </QPNT>) are written to GWinput.

    Example

    Make a GWinput template in the usual way and copy it to GWin0, e.g.

    lmfgwd --job=-1 --classicGWinput
    cp GWinput GWin0
    

    Run lmfgwd again with the switch --gwin0 and compare GWinput to GWin0:

    lmfgwd --job=-1 --gwin0
    diff GWinput GWin0
    

    They should differ only in that an additional line is written to GWinput.

    ! Supply possible tags not found in GWin0
    

    Remove or modify various parts of GWin0 and see how GWinput changes.

--sigw
Add lines to GWinput needed to make the dynamical self-energy, Σ(ω).
Note: With these modifications the 1-shot self-energy maker, hsfp0, must be run with --job=4. They do not affect QSGW self-energy maker, hs0fp0_sc.
--ib=list
Specify list of QP levels for which to make sigma (for 1-shot case only)
--make-Q0P
Make file Q0P. Usually this file is made by the GW package.
--lmqp~options
Generates information about q points for the GW cycle (Using this switch supersedes the need to run qg4gw).
Options supply information that would be read from GWinput:
  • ~rdgwin : Read selected tags from GWinput, if not otherwise specified by this switch.
    Specifically, parse the following: GWversion, Q0PChoice, Q0PScale, n1n2n3, QpGcut_psi, QpGcut_cou, BZmesh, Chi_RegQbz, TimeReversal, AnyQ,
  • ~vsn=# : Set GWversion (corresponds to GWversion in GWinput)
  • ~job=# : Set job (1 for QSGW, 2 for response functions)
  • ~q0choice=# : Chooses length of offset gamma points; to be phased out (corresponds to Q0PChoice in GWinput)
  • ~q0scl=# : scale factor for offset Gamma Q0P (corresponds to Q0PScale in GWinput)
  • ~qa : Align offset Gamma points along reciproal lattice vectors
  • ~qm : Align offset Gamma points along mid plane axes of reciproal lattice vectors
  • ~ltop=# : Sets l cutoff when making invariant dielectric tensor
--batch~switches
Turns on special mode when lmfgwd is run in job 0 that generates portions of a batch script and a pqmap canvas file to run lmgw.sh. For description, interpretation and application of this switch, see this page.   --batch can be also invoked by lmchk, but to make use if it you need to supply information lmfgwd generates that lmchk does not.
--batch writes sections of a batch script to file batch.#, and optionally pqmap.# and plot.pq#, where # is the number of MPI processes.
Options are:
  • ~np=# : specifies the number of MPI processes for the computationally demanding step lmsig, and to some the other steps unless a different specification is supplied. This tag is required.
  • ~nodes=# : Specify number of nodes. Alternatively, use ppn=#. One of them is required, unless ~noscript is present.
  • ~ppn=# : Specify number of processors per node. Alternatively, use node=#. One of them is required, unless ~noscript is present.
  • ~vanillan | gravity | eagle | juwels : tune the variables for these machines (the available machines as of this writing).
    This tag is required, unless ~noscript is present.
  • ~nplm=# : Number of MPI processes to apply to lmf. If omitted the value for np is used.
  • ~npgwd=# : Number of MPI processes to apply to lmfgwd. If omitted the value for np is used.
  • ~noscript : Suppress generating template portions
  • ~nqlmf=#: Number of irreducible q points lmf evaluates for a band cycle. lmfgwd will calculate this value and supply the appropriate default. This tag is required when invoked by lmchk.
  • ~nqgwd=#: Number of irreducible q points lmfgwd evaluates for the GW codes lmfgwd will calculate this value and supply the appropriate default. This tag is required when invoked by lmchk.
  • ~nqvc=#: Number of irreducible q points for which matrix elements of the Hartree potential are made (regular + offset gamma points) lmfgwd will calculate this value and supply the appropriate default.
    This tag is required when invoked by lmchk.
  • ~maxit=#: adds a tag --maxit # to the lmgw.sh invocation written in batch.#
  • ~bsw: adds a tag --bsw to the lmgw.sh invocation written in batch.#
  • ~pqmap@options : Generate a file pqmap.n a template pqmap to be used by lmsig
    Options are:
    • @qk=#,#,… : supplies number of k points for each q point, superseding internally generated values. This tag is required when invoked by lmchk
    • @incloff : Include offset-gamma points when making qk combinations
    • @onlyoff : Include only offset-gamma points when making qk combinations
    • @job=0 : Make a “safe” pqmap, but probably a clumsier one than the default (job=1)
    • @fill=# : set the tolerance in filling a superblock — superset of individual q, that fills all columns (default = 0.95). Smaller fill makes the pqmap maker’s job easier, but the result may be less good.
    • @rdmap : Do not make pqmap but read it from file pqmap
    • @plot : Generate a script for fplot, that renders a graphical representation of the canvas.

See Table of Contents

Switches for lm

lm is the main ASA density-functional code in the Questaal suite. See also lmgf and lmpg.

Command-line switches:

  • --rs=#1,#2
    • causes lm to read atomic data from a restart file rsta.ext. By default the ASA writes potential information, e.g. logarithmic derivative parameters P and energy moments of charge Q for each class to a separate file. If #1 is nonzero, data is read from rsta.ext, superseding information in class files. If #2 is nonzero, data written rsta.ext.
  • --band[~options]
    • tells lm to generate energy bands instead of making a self-consistent calculation. See here for options.
  • --pdos[~options]
    • tells lm to generate weights for density-of-states or Mulliken analysis resolved into partial waves. Options are described here
  • --zerq[~options]
    • Invokes lm’s charge neutrality enforcer. One of the options must be a prescription for a list of classes.
      Ways of specifying a class list
      • ~ic=lst : An integer list of indices to classes
      • ~expr:expr : lst is comprised of classes for which expr is nonzero. expr may contain: atomic number z, site index ib, species index is, class index ic
      • ~all : lst consists of all classes
      • ~es : lst consists all classes with atomic number 0 (empty spheres)
        Other options:
      • ~add : Add charge to sphere, rather than the default (which is to scale the sphere charge)
      • ~qin : Do scaling before iterations proceed
        Examples:
        –zerq~expr:z==41~qin
        –zerq~qin~ic=1
  • --mixonlyp
    • A special-purpose mode that mixes only the logarithmic derivative parameters Pl, keeping fixed the moments Ql. This can useful when starting a new self-consistent calculation, or modifying an existing one (e.g. adding spin orbit coupling), this mixing affects only the boundary conditions and not the charge, which has long-ranged interactions. Example:  assuming ~/lmf is your Questaal source directory, run the following:
      ~/lmf/nc/test/test.so --quiet 1
  • --mix=#
    • start the density mixing at rule  ’#’. See here for a description of the mixing tag.
  • --onesp
    • in the spin-polarized collinear case, tells the program that the spin-up and spin-down hamiltonians are equivalent (special antiferromagnetic case)
  • --sh=cmd
    • invoke the shell cmd after every iteration. (Not maintained).

See Table of Contents

Switches for lmgf

lmgf is Green’s function code based on the ASA. See also lm and lmpg.

To obtain the charge density or other integrated properties, lmgf requires an energy integration in addition to the k integration. The Fermi level must be found by iteration; alternatively (which is what this code does), it shifts the system by a constant potential to reach the prescribed Fermi level.

Many of the switches for lm also apply to lmgf, in particular --rs, --pdos, --zerq, --mixonlyp, --mix.

Command-line switches:

  • --ef=ef
    Assign ef, overriding value from BZ_EMESH
  • --band[args]
    Generates spectral functions along symmetry lines you specify. These are the analog of energy bands in a band code, and arguments for the --band switch. apply here, even though the output is different. When the coherent potential approximation is used, spectral functions are broadened out.
  • –fileef
    Read Fermi level from vshft.ext and shift energy mesh parameters emin and emax (read from BZ_EMESH) by the change in Fermi level.

The following is specific to the exchange modes GF_MODE≥10 are explained further on the Green’s function webpage.

  • –sites[~pair]~site-list
    • (for GF_MODE=10 | GF_MODE>11):  calculate exchange interactions only for atoms in site-list
      Additional ~pair also restricts coupling to neighbors for sites in the list.
    • (for GF_MODE=11):  Analyze exchange interactions only for atoms in site-list.
  • –vshft
    Read and apply constant potential shifts from file vshft.ext

The following are specific to the exchange-analysis mode GF_MODE=11

  • –wrsj[:j00][:amom][:sscl][:[g]scl=#][:tol=#]:
    Write exchange parameters to file, which can be used, e.g. by lmmag.
  • –wmfj:
    Output J(q=0) as input for mean-field calculation
  • –rcut=rcut:
    Truncate J(R-R’) to radius rcut
  • –tolJq=#:
    Sets tolerance for allowed deviation from symmetry in Jr
  • –amom[s]=mom1,mom2,…:
    Overrides moments calculated from ASA moments Q. Affects scaling of exchange parameters.\ Particularly useful when lmgf is being used to analyze exchange interactions computed from the GW code.
  • –2xrpa:
    Doubles the mesh of J(q) when estimating the critical temperature in RPA.
  • –long:
    Write spin wave energies with extra digits
  • –qp=fn:
    Read qp for SW energies from file fn

See Table of Contents

Switches for lmdos

lmdos is a postprocessing step that generates partial densities-of-states. It reads the weights file moms.ext generated by another program and makes partial contributions to the total DOS. Partial dos can be computed either with tetrahedron integration or with gaussian sampling moms.ext must be made in advance by a generating program, typically lmf, lm or tbe.

How channels for partial DOS are specified depends on the context. Typically you generate moms.ext specifying channels with --pdos. lmdos expects the DOS to be ordered as specified by the switch. lm will generates moms.ext even without --pdos, and orders the channels by class. If you invoke lmdos without --pdos, it assumes the ASA ordering.

Otherwise it assumes the weights are generated and stored by class. This works with lm and tbe, but otherwise, generate moms.ext with --pdos or something similar.

lmdos doesn’t need to know what the origin of the channels is; it simply reads the number of channels from the weights file. However, to assist you in making an identification of the channels with atom-centered functions, it will print out what it thinks the connection is.
Caution: lmdos may print out if you use the generating program inconsistently with it.

lmdos has a variety of options; for example it can generate the ballistic conductivity as matrix elements of the velocity operator.

Either of the following switches causes the generating program (lmf, lm, or tbe) to create moms.ext

--pdos[~mode=#][~sites=site-list][~group=lst1;lst2;...][~nl=#][~lcut=l1,l2,...]
--mull[~mode=#][~sites=site-list][~group=lst1;lst2;...][~nl=#][~lcut=l1,l2,...]

Run the postprocessing lmdos after moms.ext has been made, with the same switch and arguments.

Command-line options:

--pdos | --mull [~mode=#][~sites=site-list][~group=lst1;lst2;…][~nl=#][~lcut=l1,l2,…]
Specifies the channels for which partial DOS are generated or analyzed.
Note: this switch applies to the both the generating program and lmdos. Use the same arguments for generating and postprocessing.
--pdos  partial DOS
--mull  Mulliken DOS
Options are delimited by  ~  (or the first character following --pdos):
  • ~mode=#:
    • #=0  DOS resolved by site
    • #=1  DOS resolved by and site
    • #=2  DOS resolved by and site.
  • ~sites=site-list:  make DOS for a list of sites.
  • ~group=lst1;lst2;…:  DOS for a list of groups. A group can consist of one or more sites, which are added together to make a single channel.
  • ~nl=#:  a global cutoff: are written to maximum value of  #−1.
  • ~lcut=l1,l2,…:   -cutoff for each group or site in the group or site list.

Example from the pldos manual :   --pdos~mode=2~group=1:3;4:9~lcut=2,1
makes DOS for sites 1:3 combined for the first channel, sites 4:9 for the second. DOS is resolved by and m (mode=2), with =0,1,2 for the first group and =0,1 for the second.
See also this tutorial.

--dos~options
Various options that affect the action of lmdos (some elements apply to lmf for the total DOS).
Options are delimited by  ~  (or the first character following --dos):
  • wtfn=fname: name the file containing bands and DOS weights. By default, lmdos uses moms.ext.
  • cls:  equivalent to wtfn=cls. To be used in conjunction with lmf’s core-level spectroscopy (--cls switch).
  • tbdos:  sets defaults for to generate dos generated by tbe, which uses slightly different conventions.
  • idos:  generate energy-integrated DOS.
  • npts=#:  number of energy points. If unspecified with this command-line argument, user is prompted for this pair (lmdos only).
  • window=emin,emax: energy window over which data is to be computed. Defines the mesh together with npts, possibly shifted by −EF (see ef0). If unspecified with this command-line argument, the user is prompted for this number (lmdos only).
  • ef0:  Shift DOS by the Fermi level. emin and emax are not shifted; instead the DOS is generated over a window shifted by −EF. The energy mesh in the generated DOS file corresponds to frequency ω: it is zero at EF.
  • mode=# compute quantities other than the DOS.
    • #=0  Standard DOS, i.e. ∫ d3k δ(E(k)-E)
    • #=1  Ballistic conductance, Landauer formula, i.e.   1/2 ∫ d3k δ(E(k)-E) ∇E(k) See PRL 74, 586 (1995).
      In this mode, you must supply vector vec to indicate which direction the gradient is to be projected.
    • #=2  diffusive conductivity in the relaxation time approximation ∫ d3k δ(E(k)-E) ∇1E(k) · ∇2E(k) . See Ashcroft and Mermin, Eq. 13.25. In this mode you can supply vec2 as well as vec.
    • #=3   absolute value of the velocity, i.e.   ∫ d3k δ(E(k)-E) |∇E(k)|.
      Note: the conductivity modes require that you use tetrahedron integration. The BZ is divided into tetrahedra; any tetrahedron that encompasses a given energy will contribute to the number of states at that energy.
  • vec=#1,#2,#3:  k direction vector 1 for mode=1 or mode=2. You must use tetrahedron integration.
  • vec2=#1,#2,#3: k direction vector 2 for mode=2. You must use tetrahedron integration.
  • totdos: compute total DOS by combining weights from all partial DOS.
    Note: if input moments file has no special channels, this is the default.
  • rdm: write DOS in standard Questaal format.
  • h5: write DOS in hdf5 format.
  • ldig: read/write DOS with extra digits.
  • sam[@options]: Generate DOS with sampling integration (lmdos only).
    • @n=# Methfessel-Paxton polynomial order (defaults to ctrl file input for BZ_N).
    • @w=# Gaussian width (defaults to ctrl file input for BZ_W).
    • @kres Resolve DOS by wave number: a separate dos is written for each k.
  • bands=list: compute contribution to DOS from a prescribed list of bands.
  • classes=list: generate DOS for a specified list of classes
    Caution: this option is only compatible with default moments files generated by the ASA, which stores dos weights by class. It is incompatible with the --pdos switch which stores weights by site.

Compare modes 0,1,2 to analytic results for energy bands , evaluated at .

Mode 0:

Mode 1:

Mode 2

Example : compute the ballistic conductance in the z direction over an energy range (-0.8,0.5)Ry:
--dos:mode=1:npts=501:window=-.8,.5:vec=0,0,1

--cls[.ib,l,n[.ib,l,n][.lst=list,l,n[.lst=list,l,n]][.fn=file]]
tells lmdos that the moms.ext holds data for core-level (EELS) spectroscopy (lmf output).
--kres=E  |  --kresm=E
actives a special mode that finds all tetrahedra that encompass an energy E, and write the DOS (or some conductivity derived from it) to file dosq.ext. Also written is the k point corresponding to the center of the tetrahedron, and the band index. Thus you can resolved a quantity such as the velocity by k and band. If E is the Fermi level, you can for example determine the average Fermi velocity as well as its k-resolved and band-resolved value.
This tutorial demonstrates the --kres switch.

--kres and --kresm perform similar functions: --kresm writes an additional file dosq.h5, which is similar to dosq.ext but is q points are unfolded to the full Brillouin zone It is particularly useful for making Fermi surfaces plots with the color varying with the Fermi velocity. This tutorial demonstrates an application of this for Fe.

See Table of Contents

Switches for lmstr

lmstr is the (screened) structure constants generator for the ASA. The structure constants are needed to define the hamiltonian. lmstr generates them in real space, building a neighbor table around each atom that defines the range of the hamiltonian.

Structure constants are required by the lm, lmgf, and lmpg codes prior to performing electronic structure calculations, and are described in some detail in Sec 2.9 of the Questaal methods paper Comp. Phys. Comm. 249, 107065 (2020). In the lmpg case, structure constants are generated for trilayers, as distinct from periodic boundary conditions (Sec. 2.14).

--checkpl
search for pairs in the neighbor table which link atoms whose principal layers index differs by more than 1.
Principal layers are needed for the layer Green’s function’s code lmpg. A detailed description can be found in Sec 2.14 of the Questaal methods paper Comp. Phys. Comm. 249, 107065 (2020).
--plot
writes pointwise data about the screened structure constants, useful e.g. for plotting
Example :   lmstr --pr51 gas --plot:con   (this instruction is part of the test ~/lmf/testing/test.lm gas).
--chk
compares the structure constants now being made against a reference

Switches for lmscell

lmscell operates in one of two modes: supercell maker and superlattice editor. By default, lmscell operates in the supercell mode; the command-line switches corresponding to that mode are explained there.
For the latter, invoke lmscell --stack. This page documents instructions to the stack editor.

Caution: lmscell may fail if you choose a supercell significantly elongated from the original, because the list of lattice vectors may not encompass all the translations needed to create the new basis.

--stack
Invokes the stack editor. This page documents the editor.
--plx[~m]~#1,#2,#3,#4,#5,#6,#7,#8,#9
Specifies the three superlattice vectors, equivalent to reading them from stdin. The [~m] indicates that #1,…#9 are multiples of the lattice vectors, rather than Cartesian coordinates.
You must specify this vector either via stdin as   [m] #1 #2 #3 #4 #5 #6 #7 #8 #9   or by --plx.
--wsite[x][~map][~salat=#][~sort][~fn=file]  |  --wpos=file
Writes a site file to disk, or a positions file to dist.
--wsitex writes positions in crystal coordinates. --wpos writes a file of site positions in standard Questaal format.
  • ~fn=file :   writes site file to file.ext.
  • ~quad1 :   translates site positions to first quadrant in unit cell.
  • ~shorten=#,#,# :   shorten vectors when writing site file see common switches
  • ~short :   write site file in short form
  • ~salat=# :   scale lattice constant by  #  and lattice vectors by  1/#  before writing
  • ~map:   appends a table mapping sites in the original cell to the supercell
--refsite[~scl=#][~fn=fnam][~plx][~swap]
Modifies site positions p by scaling excursions around a reference position pr. Computes the difference ppr, scales it, and adds the scaled difference to pr. This becomes the new position p. If the scale factor is unity, the positions are unchanged.
  • ~scl=# :   scale displacements by  #. This tag is required.
  • ~fn=fnam :   names reference site file. If fnam.ext exists, it is read; otherwise fnam is read. This tag is required.
  • ~plx :     Displacements expressed in crystal coordinates.
  • ~swap :   exchange role of site and reference files.
--xshft[x]=dx,dy,dz
Translate basis atoms by constant vector (Cartesian coordinates; use xshftx for crystal coordinates).
--block  |  --sort~”expr1 [expr2] [expr3]”  |  --swap~i1,i2[,i3,i4,…]  |  --ring:i1,i2
Different (mutually exclusive options to rearrange order of sites in the supercell.
  • --block groups supercell sites into n blocks, each block a rigid translation of the original lattice. The original lattice occupies the first block.
    n is the multiple of the number of original sites; n must be an integer.
    Example (assuming that ~/lmf is the top level of your Questaal directory) ~/lmf/testing/test.lmscell 2
  • --sort orders site table according to ordering algebraic expressions associated with them.
    Expressions can use Cartesian components x1, x2, x3, e.g. --sort:’x3 x2’.
    Optional expr2 sorts subsets of sites with equivalent values of expr1, similarly expr3 sorts within subset given by expr2.
    Example :   ~/lmf/testing/test.lmscell 1
  • --swap swaps pairs i1 with i2 (and optionally i3 with i4 …).
  • --ring shifts sites i1…i2-1 to one position higher, and site i2 cycles to position i1.
--sites:site-list
Make supercell of subset of sites in original basis. See here for site-list syntax.
--rsta  |  –rsta,amom
(ASA only) Makes ASA restart file for the supercell from existing file rsta.ext.
Optional amom applies to noncollinear magnetism: it flips the majority and minority spins for sites where the magnetic moment is negative, while rotating the Euler angle by 180°
--pl:expr
Assign principal-layer index according to expr. Sites with equivalent values of expr are assigned the same PL index.
Principal layers are needed for the layer Green’s function’s code lmpg. A detailed description can be found in Sec 2.14 of the Questaal methods paper Comp. Phys. Comm. 249, 107065 (2020).
--wrsj[~fn=name][~scl=#]
Writing the pairwise exchange parameters of the supercell generated, e.g., from lmgf. Input file rsj.ext must be present.
--disp~fnam~site-list
Displace a set of atoms in the neighborhood of a given one, e.g. --disp:tab2:style=3:Fex
Use in conjunction with lmchk command line argument (--shell~tab=2~disp=file). See here for site-list syntax.
--keep
Do not search for sites in supercell, but preserve sites as given. Neither site positions nor the size of the basis will be altered (except they will be shortened if you also use the --shorten switch).
--tfix[~shorten=#,#,#]
Build supercell as the original cell, translated by one of a fixed set of lattice vectors of the unit cell. The number of these lattice vectors must be an the ratio of the supercell volume to the original cell volume. They are determined before the supercell is assembled. Optional shorten shortens them, depending on mode specifed by  #.
--sqs~args[~options]
Make a Special QuasiRandom Structure. It works by minimizing an objective function.
The objective function is obtained by assigning a weight to each pair and three body correlator, and summing the individual weights.

Options are delimited by  ~  (or the first character following --sqs):
~seed=#:  initial seed for random number generator. For a fixed seed the algorithm proceeds the same way each time.
~r2max=#:  Maximum distance between pairs for pairs to participate in the objective function.  #  is units of the lattice constant alat)
~r2a=#:   same as r2max, but  #  is in atomic units
~r3max=#:  Maximum sum of legs between for triples to participate in the objective function.  #  is units of the lattice constant alat)
~r3a=#:   same as r3max, but  #  is in atomic units
~spec1=#:  index to first species to swap (default is 1)
~spec2=#:  index to second species to swap (default is 2)
~alf2=#:   weight assigned to pair contribution to correlation function exp(−alf2 d), where d is connecting vector length
~alf3=#:   weight assigned to triplet contribution to correlation function is exp(−alf3 d), where d is the length of the triangle perimeter
~r3mode=#:  add additional constraints limiting whether a triplet is accepted

Hazard: The sqs functionality is still experimental.

--scala=#
Multiply lattice constant by #, divide lattice and site vectors by # before making supercell.

See Table of Contents

Switches for lmfgw

lmfgw is a modernized replacement for some of the executables in the GW package.
At present it provides a replacement for the product basis maker, hbasfp0, and the maker of the coulomb integrals hvccfp0, needed e.g., for the Fock matrix. It also computes matrix elements for the incomplete basis correction.

Product basis maker
  • --pb[~options]:
    Rons a product basis maker, making products B of partial waves , and local orbitals inside the augmentation spheres.
    Options are delimited by the first character following --pb ( ~  in this case).
    In the absence of modifying options the standard product basis is made and the result written to pb.h5.
    Options are:

    • ~core
      Constructs a product basis for the core partial waves, and writes the result to file pbc.h5.

    • ~gradpb
      Constructs a product basis for the core partial waves, and writes the result to file pbc.h5.

    • ~bbb
      Constructs a double product basis ᗷ consisting of all possible products B × B

    • ~checkrpb
      Checks completeness of product basis

    • ~checkrpb=2
      Checks completeness of product basis, verbose output

    • ~w=legacy
      Write product basis in legacy (binary) format (used by antecedent codes)

    • ~w=mixed
      Write product basis in hdf5 format used by gw-speedup, spring 2023. Less compact than default format

    • ~mxcstr=#
      When refining B, maximum number of constraints to fit.

    • ~addrl=#
      cutoff for adding analytic functions to product basis, in addition to products of partial waves.

Integrals for incomplete basis correction
  • --ibc[~options]:
    Generates matrix elements to correct incomplete basis, using a local Sternheimer equation, ala Phys Rev. B 92, 245101.
    It follows that reference in restricting possible variations in potential to the shape of a given product basis.
    In the absence of modifying options the product basis defining variations in potential is read from pb.h5.
    This mode is still a work in progress and no file is written yet.
    Options are:

    • ~core
      Integrals for core partial waves. Read product basis from file pbc.h5.

    • ~fn=name
      Specify file name for product basis file.

    • ~debug
      Debugging mode: verify that partial waves via Sternheimer match those calculated by finite difference

    • ~sumchk
      Calculates matrix elements of the partial waves and prints out a sumcheck.

Coulomb integrals

lmfgw automatically generates the coulomb integrals areunless you include --stop=prbas' on the command line. Writes file vc.h5 for the valence states and vcc.h5 for the core states.

Switches for lmfgws

lmfgws is the analyzer of the dynamical GW self-energy. You need to create the self-energy first and set up the input file (se) using spectral. See this tutorial.

  • --sfuned
    Run the spectral function editor. Its usage is documented in this tutorial. There is also a help mode when you run the editor interactively.

  • --chksig
    When a dynamical self-energy Σ(ω) is read, it is checked for causality, i.e. that Im Σ>0 for ω<0, and Im Σ<0 for ω>0. Only checked for Σ read on the real axis.

Switches for lmgw.sh

Usage: lmgw.sh [--switch arg | switch=arg] ctrl.ext

lmgw.sh is a shell script for the fast, parallel form of the QSGW codes.

A command-line switch can be expressed as two strings: --switch arg pair, or as a single --switch=arg. Be sure to enclose arg in quotes if it has spaces.

Command-line switches are documented in the user guide.

Switches for lmgwsc

lmgwsc is a shell script for the classic implementation of QSGW. lmgw.sh is the modern replacement for lmgwsc; it is recommended you use it.

lmgwsc is a wrapper for lmgw to the static QSGW self-energy Σ0(k). It iterates until convergence is reached, or the maximum number of iterations is encountered. To see command-line switches, run lmgwsc with no arguments.

Switches for lmgw

lmgw is a shell script for the classic GW code that manages the various kinds of quantities it can make. lmgw.sh is the modern replacement for it; it is recommended you use it.

To see command-line switches, run lmgw with no arguments.

Switches for lmfdmft

lmdmft serves both as an interface linking lmf with DMFT solvers, and as a means to extract results given a DMFT-generated self-energy.\ lmdmft requires an extra input file, indmfl.ext, that specifies the correlated orbitals and other conditions for DMFT calculations.

The DMFT code will generate a self-energy for the correlated channels. In the interface to Haule’s CTQMC code, this file is called sig.inp. If sig.inp is missing, lmdmft will make template for a Matsubara frequencies specified in the ctrl file, and populate the DMFT self-energy with 0.

Switches:

  • --job=#:
    Set DMFT job to #
    • 0 creates files lattice, class
    • 1 setup for DMFT run or to perform analysis
    • 2 create file Trans.dat for Haule’s CT-QMC
  • --dc~switches   |   --ldadc~switches:
    Specifies double counting via a command-line argument. Data can be:
    1. read from a list embedded in the command-line argument
    2. read from a file
    3. estimated from DMFT Σ(ω→∞)

    The double counting has the same structure as the hybridization: there is one value for every channel in each inequivalent cix block. Let the (maximum) number of channels be ndsig and nicix the number of inequivalent blocks. The number of values read must be either nicix or ndsig × nicix. In the former case, a constant value is used for each channel in a given block.

    Switches:

    • ~siginf[=#]   estimate double counting from Σ(ω→∞). By default Σ(ω→∞) is estimated from Σ(ωmax).
      If # is specified, make a least-squares fit of Σ for the last  #  frequencies, as a linear function of 1/ω2, and extrapolate to 0.
      In this case lmfdmft does not continue, but exits after the estimate is calculated.
      If the ~fn tag is also present, lmfdmft writes the result to file </b>filnam before exiting.
    • ~fn=filnam   read data from file filnam.ext, in the standard Questaal format for 2D arrays.
      The file must have nicix rows and either 1 or ndsig columns. If used in conjunction with ~siginf, this file is output, not input.
    • ~dc=list     a list of values, separated by commas. The list must contain either nicix or ndsig × nicix elements.
    • ~spinav    (spin polarized cases only) spin-average the up- and down- elements.
      Thus --dc~spinav~dc=1,2,3,4,5,5,4,3,2,1 creates 10 channels with value 3 in each channel.
  • --makesigqp[:mode=#]:
    makes quasiparticle DMFT sigma, in format of QSGW sigma file.
  • --udrs:
    Generate and save output density.
  • --gprt[~rdsigr=fn][~rdsigr=fn][~mode=#][~band[@flags]][~nom=#]:
    Write local Green’s function gloc to disk. Options are delimited by the first character following --gprt ( ~  in this case).
    • ~rdsigr=fn   reads frequencies and self-energy from file fn. Frequencies are taken to be real.
    • ~rdsig=fn   reads frequencies and self-energy from file fn. Frequencies are taken to be Matsubara frequencies (imaginary).
      If you do not read frequencies, the code will use the standard (Matsubara) frequencies that build the hybridization function.
    • ~nom=#   calculate G only for the first # points.
    • ~band[@flags]   generates the self-energy for an independent set of k points, specified through the options modifying band.
      Flags are identical to those following the --band switch, and delimited by the first character following band (taken to be  @  in this documentation).
      It must be distinct from the delimiter to --gprt.
    • ~mode=#   choose from the following:
      • #=1   k-integrated gloc (this is the default)
      • #=2   k-resolved gkloc (output in gkloc.ext)
      • #=3   both 1 and 2
      • #=4   k-resolved hkloc (output in hkloc.ext)
      • #=8   k-resolved G in the basis of 1-particle eigenfunctions (output in gk.ext)
      • #=18   write diagonal in the basis of 1-particle eigenfunctions (output in se.ext)
      • #=19   write diagonal in the basis of 1-particle eigenfunctions (output in se.ext)
      • #=20   Like 19, but an effective diagonal sigma defined from diagonal part of matrix gij. Causes g computed from diagonal sigma to match diagonal gij.
    • ~ef0    Noninteracting bands are referenced to noninteracting chemical potential (default is to subtract interacting one). Applies to modes 18-20.
    • ~mu=#   Set the chemical potential manually to  # .
    • ~broad=#   Set the DMFT Green’s function broadening parameter δ to  # (δ is added to Im Σ)
  • --dos:     Make density-of-states (not documented; also implementation is correct only when sigma is static).
  • --mu=#:    Use  #  for chemical potential, instead of calculating it.
  • --pade~nw=#~window=#1,#2[~icut=#1,#2]   |   --pade~fn=fnam[~icut=#1,#2]   |   --pade~khm~d=ω1~n=n~[l=l|m=ωlast]
    Make a Pade approximation to map the self-energy from the Matsubara axis to the real axis.
    First form specifies a uniformly spaced mesh; the second reads an arbitrary energy mesh from the first column of file fnam. The third form constructs a sequence of energy windows with uniformly spaced points. Each successive window begins where the prior window ends, with twice the spacing between points.
    • ~nw=#         specifies first form and number of mesh points on the real axis.
      • ~window=#1,#2   first and last frequency on the mesh.
    • ~fn=fnam       specifies second form and file name containing frequencies.
    • ~khm        specifies the third form
      • ~d=ω1      highest frequency of first level
      • ~n=n      n = number of mesh points in one level
      • ~l=l       l = number of levels or stages
      • ~m=ωlast     stop when a mesh point exceeds ωlast.
    • ~icut=#1,#2    all modes; applies to the fitting on Matsubara axis.
      • #1   if nonzero, for frequencies with index exceeding #1, use only every second point.
      • #2   if nonzero, exclude frequencies with index exceeding #2.

See Table of Contents

Switches for spectral

spectral is a postprocessor of the raw GW dynamical self-energy files SEComg.UP and SEComg.DN.
Its main purpose is to translate self-energies generated by the GW self-energy maker hsfp0, into an input file se.ext that the dynamical self-energy analyzer, lmfgws, can read.

spectral also has a limited ability to make spectral functions, and most of its command-line switches are intended for that purpose.

spectral is used in the GW self-energy tutorial in both contexts, illustrating the switches below.

Note on interpolation: the spectral function is only reliable on a fine energy mesh. Unless many-body effects are very pronounced (rare in a GW context), varies smoothly with ω and can be interpolated to a fine mesh. nw and domg are designed to interpolate Σ. If you want to interpolate, choose one or the other.

If you are using spectral only to make se for lmfgws, it is better not to interpolate and use --nw=1.

Switches:

  • --ws  |  --ws:x
    Does no analysis but write a self-energy file (se) for all k, suitable for reading by lmfgws.
    --ws:x performs the same function but also writes the exchange potential to se.ext.
    Note: when using this switch, --nw=1 is advised, since lmfgws can do its own interpolation.
  • --nw=nw
    Subdivide input energy mesh nw times
  • --domg=#
    Target energy spacing for A(ω), eV. nw is chosen that bests fits target domg.
  • --1shot
    eigenvalues do not correspond with QP levels
  • --range=ω1,ω2: restrict generated results to ω1 < ω < ω2
  • --eps=#
    smearing width, in eV.
  • --cnst:expr
    Exclude entries in SEComg.{UP,DN} for which expr is nonzero. expr is an integer expression that can include the following variables:
    • ib (band index)
    • iq (k-point index)
    • qx,qy,qz,q (components of q, and amplitude)
    • eqp (quasiparticle level)
    • spin (1 or 2)

Example :   Use only the first k-point and exclude Σ from QP levels whose bands fall below -10 eV.
--cnst:iq==1&eqp>-10

See Table of Contents

Switches for SpectralFunction.sh

SpectralFunction.sh reads spectral function files in the spf format, and makes figures from them. It reads a file spf.ext and writes data specfun.pm3d and gnu plotting script gnu.plt

The script is self-documenting. For help, try:

$ SpectralFunction.sh  -h

Switches for fplot, plbnds, pldos

Switches for these utilities are found in the fplot manual, plbnds manual, and pldos manual.

Switches for vextract

vextract is a script that extracts values associated with variables from a list of lines, such as is found in a save file, for example

i gmax=4.4 nkabc=3 ehf=-0.2950731 ehk=-0.2950686
i gmax=6 nkabc=3 ehf=-0.294891 ehk=-0.294886

The script is self-documenting. For help, try:

$ vextract --h

Switches for symlinepoints

Note : This script is obsolete. Use lmchk --syml... documented here.

symlinepoints is a script that structures a file containing k point information into Questaal’s symmetry lines format. The symmetry lines file is used to generate energy band structures. You can supply k points in one of several possible forms.

This script is self-documenting. For help, run symlinepoints with no arguments or with --h, viz

$ symlinepoints --h

Switches are:

  • -nk=#
    Specify number of k-points on a line as (length of line)×#.
    This is useful because points on each line will be have approximately the same spacing.

  • -qlat=qfile | -qlatl=qfile
    Tell symlinepoints to read k-points in crystal coordinates, i.e. fractional multiples of the reciprocal lattice vectors (RLV).
    qfile is a file containing is a 3×3 matrix (9 elements) with elements ordered as follows:

      Qx1 Qy1 Qz1 Qx2 Qy2 Qz2 Qx3 Qy3 Qz3
    

    Questaal codes print out the RLV in this order. You can create qfile by doing, e.g.

      $ lmchk ext [switches] | grep -A 3 Qlat | tail -3 | awk '{print , , }' > qfile
    

    See this tutorial for an example.

    -qlat and -qlatl both interpret input k points as multiples of the reciprocal lattice vectors (crystal coordinates). The former writes them out as Cartesian coordinates, while the latter as multiples of RLV. Note: if the symmetry lines file contains k points in multiples of the RLV, be sure to generate the bands with  --band~mq .

  • –in=all (default)
    Each row has format: nk q1x q1y q1z q2x q2y q2z [string]
  • –in=q
    Each row has format: q1x q1y q1z q2x q2y q2z [string]
  • –in=q1
    Each row has format: q1x q1y q1z [string]

  • –help  |  –h show this message

Switches for lmctl

lmctl is an adjunct to the ASA, that read sphere moments from class files and writes the data in a form suitable for the input file. It is an easy way to collect the results into the ctrl file.

Command-line switches:

  • -spin1:  add spin-polarized moments into a non-polarized set
  • -spinf:  exchange up- and down- moments
  • -mad:  also write out the electrostatic potential, ves, at RMAX

See Table of Contents

Switches for tbe

tbe is the empirical tight-binding code. tbe-specific options:

  Mixing options
 --mxq          mix multipole moments and magnetic moments together: beta
 --mxq2         mix multipole moments and magnetic moments separately: beta, betav
 --mxr          mix Hamiltonian

  MD options
 --st           start new MD run (otherwise strt is read); begin new md, mv and xyz files
 --md=#         in MD write info to the md file every # timesteps
 --mc=#         in MD or static relaxation write to the xbs mv file every # steps
 --mv           append to file mv.ext (xbs mv file format)
 --wforce=fn    write forces to file fn.ext
 --xyz=#        in MD or static relaxation write to a standard xyz file every # steps

  i-PI integration options
 --ipi-host=host the i-PI server host
 --port=#        i-PI server port to connect to

  Diagonalization options
 --DC           use divide and conquer (sca)lapack routines (the default)
 --RRR          use multiple relatively robust representations (sca)lapack routines
 --MAGMA        use the magma library diagonalisation routines, if linked.
 --MAGMA2       use the 2 stage magma diagonalisation routines.
 --ELPA2        use the elpa diagonalisations routines (if linked).

  Core options
 --rdham        load ham.ext and ovl.ext files (strx format)
 --point        use point charges only (instead of multipole expansion)
 --sfly         make strux on the fly to save memory at the expense of substantial loss of efficiency
 -ef=# override Fermi energy
 --efield=#,#,#  (MOL=T only) apply an electric field (atomic Rydberg units)
 --leanrho       in MPI, try to save memory at the expense of some communication

  MPI process mapping options. In most cases the default mapping is the optimal choice
 --kblocks=#    Number of rectangular processor blocks over which to distribute the k-points
 --nprows=#     Number of rows of the ScaLAPACK/BLACS process arrays/blocks.

   Linear scaling options
 --linscl {msi|ls++}
                Switch to linear scaling branch:
                  msi : matrix sign iterations/polynomial mode
                  ls++: use the LS++ library (MPI C++),from T. Kuehne et. al. (incomplete integration)
 --bgc          Set expected band gap centre
 --lstol        Set tolerance/accuracy for iterations
                and threshold for values stored in sparse matrices (second argument, if present)
 --lsxxp        the LS++ p parameter (ls++ branch only)
 --lsxxb        the LS++ beta parameter (ls++ branch only)

Switches for lmxbs

lmxbs generates input for the graphics program xbs, a program written by M. Methfessel, which draws cartoons of crystals. See this page.

Command-line switches:

  • -bs=expr:  factor that scales the default ball (sphere) size. This factor scales SPEC_RMAX by expr. By default, the scaling is 0.5.
  • -ss=expr:  controls the criterion for what length defines a connected bond. This switch scales the default factor scaling a ‘bond length’ which must be closer than RMAXi+RMAXj.
  • -shift=x1,x2,x3:  shifts all the coordinates by this amount, in units of ALAT.
  • -scale=val:  sets the xbs variable scale.
  • -spec:  shifts Organize sites by species (e.g. colors). By default sites are organized by classes.

  • -sp:rule1[:rule2][…]:  modifies the species rmax and colors.
    rule has the syntax
    expr,rmax,red,green,blue
    expr is a logical expression involving the class index ic and atomic number z. If expr evaluates to true, the rule applies to this class. rmax, red, green, blue are the ball size, and RGB colors for the ball. Default values are taken for those numbers omitted. For the colors, the defaults are random numbers between 0 and 1.

Example :   lmxbs '-sp:z==0,.5,.1,.1,.1:z==13&ic>3,,1,0,0:z==13,,0,1,0'
Empty spheres are nearly black, with rmax=.5 and Al atoms class index > 3 are red, with all remaining Al atoms green.

  • -dup=n1,n2,n3[,expr]:  duplicates the unit cell n1+1,n2+1,n3+1 times in the three lattice directions. Optional expr is a constraint. If expr is present, sites whose for which expr is zero are excluded.
    Variables that may be used in expr are:
    • x1,x2,x3 site positions, in units of ALAT
    • p1,p2,p3 site positions, as projections onto plat
    • ic,ib,z,r class index, basis index, atomic number, and radius

Example :   lmxbs "-dup=4,4,4,0<=x1&x1<1.01&0<=x2&x2<1.01&0<=x3&x3<1.01&z>0"   selects sites in a (dimensionless) cube of size 1 and exclude empty spheres.

See Table of Contents

Switches for site2init

site2init converts a site file to an init file, writing it to stdout, as explained here.

Usage:
site2init   [-switches]   [site-filename]

sitefile-name is the full filename (no extension is appended). If the argument is missing, sitein is used.

Switches:

  • -header=string:  Uses string for the header.
  • -wsitex  |  --wsitex:  writes basis vectors as multiples of the lattice vectors, instead of Cartesian coordinates.

Switches for genflags.py

All flags are optional, flags separated by “|” are incompatible with each other. Refer to README.md for common use scenarios.

   prefix=directory install to the given directory.

   intel|gcc|cray   use preset flags for the given environment.

   opt|opg|dbg      build type:
                      opt: performance optimised flags
                      dbg: flags suitable for development and debugging
                      opg: debugging flags with high -O setting for higher performance

   openmpi|intelmpi use mpi wrappers:
                      openmpi:  the usual mpif90/mpicc
                      intelmpi: mpiifort/mpiicc/mpiicpc specific to the intel compiler suite

   native|knl       add the -march=native flag,
                       knl: forces knl native build in case the compilers do not recognise the cpu

   static|pic       link type:
                      static: tries to link all libs statically,
                      pic: produces pie code and links internal libs dynamically
   mkl|openblas     blas/lapack implementation
                      mkl: intel's math kernel library, it also supplies scalapack and fftw

   cuda             link nvidia's cuda libs, can be utilised in tbe and gw

   scalapack        enable scalapack, useful if mkl not present

   elpa             link the elpa library for diagonalisation

   ls++             link the linear scaling++ library (T. Kuehne, incomplete integration)

   cov              enable measurement of test coverage

   trace            enable (ugly but useful) backtraces on any abnormal exit status

   as-needed        add "-Wl,-as-needed" to ldflags

   idbc             ensure debuginfo is written in format compatible with the now discontinued idbc from intel

   nohdf5           try to build without hdf5 (use only if you know what you are doing)

   dissect          try to unpick wrappers using the "-show" argument (e.g. mpif90 -show)

Switches for mlist

mlist parses a list in Questaal’s standard integer list format and returns the sequence of numbers in the list. The list need not be composed of integers, but options available are larger if you specify an integer list.

Usage:
mlist   [-switches]   list

Switches:

  • −n   Returns size of list, instead of the contents
  • −i   specify that list is an integer list
  • −il   same as −i, but return list in compact standard integer list format.
  • −sort   sort the list in ascending order. When used with −i, duplicates are pared
  • −map=expr  replace element with expression. Allowed variables in expr : only x for now (x is variable assigned to element)
  • −ndec=n   specify minimum number of decimals to print out. Not available with −i.
  • −ffmt   formatting style (default=’g’); see bin2a conventions. Not available with −i.
  • −sep:c   specify character separating elements to be printed

See Table of Contents

Switches for fftc

fftc is a Fast Fourier Transform utility that convolves two functions.

It runs in a multivariate mode, and also a one-dimensional mode. While the latter is a special case of the multivariate, that mode offers more options.

Usage in 1D mode:
fftc   [-fformat] -convolve1d~[~origin=#][~npad=#][~reverse][~gauss=#] file1 file2

file1 and file2 should take the standard Questaal format for 2D arrays.
Options for data format:

  1. Reads data in one column. If function is complex, imaginary part should follow real.
  2. Reads data in two or three columns. If cast is specified, data should be declared as real.
    Column 1 is the abscissa x. Points should be evenly spaced in x; spacing sets the scale for the absicssa.
    Column 2 is taken to be the real part of the function; if column 3 exists it is taken to be the imaginary part

Switches to -convolve1d :

  • [~origin=#]   specify offset to point # to be the origin (x=0). Default is #=0.
  • [~brute]     also does the convolution by brute force.
  • [~npad=#]    Add # rows farthest from the origin, pad with zeros
  • [~reverse=#]  Reverse convolution
  • [~gauss=#]   Do not read file2; instead replace it with .
  • [~wab]     Write the output in format 2 noted above.

Example :   Convolve a (discretized) δ-function with a Gaussian. Copy the following box into file in.fft

% rows 40 cols 2
  0  4
% repeat i=1:39
 {i/4} 0
% end

Confirm that it is a discrete δ-function on an interval [0,10] :

mcx in.fft

Note that the “area” is unity since the function is 4 at the origin and the x spacing is 1/4.

Make the convolution with a gaussian with smoothing radius 2 (standard deviation 2/√2)

  fftc -f3f20.15 '-convolve1d~off=0~npad=0~brute~gauss=2~wab' in.fft

Confirm that the convolved function integrates approximately to 1. Since the function is periodic with period 10, we extract the first point and append it as the last point with x=10 . Then we can do the integral numerically on a mesh of points between 0 and 10:

fftc -f3f20.15 '-convolve1d~off=0~npad=0~brute~gauss=2~wab' in.fft | mc . -p -rowl 1 -e2 10 x2 -rcat -int 0 10

You should see this:

   10.000000    0.999580

See Table of Contents

Site-list syntax


Site-lists are used in command-line arguments in several contexts, e.g. in lmscell, lmgf’s exchange maker, and lmchk’s --shell and --angles switches.
For definiteness assume  ~  is the delimiter and the segment being parsed is sites~site-list.
sites~site-list can take one of the following forms:

sites~list
list is an integer list of site indices, e.g. 1,5:9. The syntax for integer lists is described here.
sites~style=1~list
list is an integer list of species or class indices (depending on the switch).

All sites which belong a species in the species (or class) list get included in the site list.

~style=2~expr
expr is an integer expression. The expression can involve the species index is (or class index ic) and atomic number z.
The species list (or class list) is composed of members for which expr is nonzero.
All sites which belong a species in the species (or class) list form the site list.
~style=3~spec1,spec2,…
spec1,spec2,… are a string of one or more species names. The species list (or class list) is composed of species with a name in the list.

All sites which belong a species in the species (or class) list form the site list.

Note: some ASA-specific switches refer to class-list. The structure is identical to the construction above, except that the class list is not expanded into a site list.

See Table of Contents

Footnotes and References