The restart file

In density functional theory, complete information about the system is formally contained in the density. In practice the density must be represented somehow, and information pertaining to the way it is representation must also be supplied.

The codes that generate a density, e.g. lmf, store complete information to (re)start a calculation for a given density (typically generated as an output in a self-consistency cycle). Thus you can converge a system to partial self-consistency, and start again where you left off. Questaal is an all-electron method, so the density has a representation in each augmentation sphere. (Valence and core densities are kept separately.) The full-potential codes, e.g. lmf, also contain information about the interstitial part, represented on a uniform mesh. The ASA codes lm, lmgf, and lmpg, do not have an interstitial and keep the $\ell{=0}$ part of the density only. This enables a simplification to represent the density as a set of three moments of the density.

Full-potential restart file

This is normally kept in a binary file, named rst.ext; though it can be read from, or written to an ASCII file rsta.ext. Here we will refer to the file as the rst file.

The rst file contains all the necessary input conditions need to generate the effective one-electron hamiltonian not already given in the input files needed to start the calculation, e.g. the ctrl file). If you have made the density self-consistent, it is a convenient way to store all the information needed to generate the effective hamiltonian system.

The rst file contains:

• Header information: identification, time stamp, size of basis, number of species number of spin channels, what form of relativity it uses
• Structural information: lattice constant and primitive lattice vectors
• The interstitial density represented on a uniform mesh of n_a, n_b, n_c divisions along the three axes (a, b, c) of the primitive lattice vectors
• The Fermi level and (if sampling integration was used) information about the (Methfessel-Paxton broadening)(http://link.aps.org/doi/10.1103/PhysRevB.40.3616) parameters used to generate the density
• Information about each atom in the basis, and
  • Species identification (number and label)
  • Coordinates specifying site position
  • Euler angles defining the spin quantization axis for the basis set (noncollinear case)
  • $\ell$-cutoffs for augmentation and representation of the site density
  • Polynomial cutoff used for one-center expansion of envelope functions around other sites
  • The sphere logarithmic derivative parameters P. defining the boundary conditions of the partial waves
  • Density on a radial mesh, representation as a sum of (radial part × spherical harmonic up to $\ell$ cutoff). Both the true density and the one-center expansion of the interstitial density are kept, in keeping with the philosophy of a three-fold representation of the density.
  • The (spherically symmetric) potential for which the partial waves are made that form the basis set.
    Note: this potential can be kept distinct from the potential derived from the density.
• Information about each chemical species
  • Parameters specifying shifted logarithmic radial mesh (sphere radius, number of mesh points, spacing)
  • Atomic number, core charge
  • Parameters needed to extrapolate the core charge into the interstitial
  • Information about the kinetic energy (needed for total energy calculations if the core is kept frozen).

ASA restart file

The ASA codes, e.g. lm, lmgf, and lmpg can also read input from a rst file. In this case the file is always ASCII (rsta.ext) and the format is different. The full density is not kept, but only the logarithmic derivative parameters P, and the energy moments of the density Q₀, Q₁, Q₂.

Restart file editors

There is a restart file editor for ASA, documented on this page.

lmf also has an editor that enables you to edit rst files in different ways, which is documented here.

You can operate the editor in interactive mode or batch mode, or a mix, as you can for other editors.

Interactive mode

To operate lmscell in interactive mode, invoke

lmf --rsedit

You should see:

 Welcome to the restart file editor.  Enter '?' to see options.

 Option :

The editor operates interactively. It reads a command from standard input, executes the command, and returns to the  Option prompt waiting for another instruction.
The editor will print a short summary of instructions if you type   ? <RET> .

Batch mode

You can also run the editor in batch mode by stringing instructions together separated by a delimiter, e.g.

lmf -vz=11.5/11.43 ctrl.inas '--rsedit~rs'

The delimiter ( ~  in this case), as the first character following --rsedit. lmf will parse through all the commands sequentially until it encounters “quit” instruction ( ~q ) which causes it to exit. If no such instruction is encountered, lmf reverts to the interactive mode.

Restart file editor instructions

Most instructions have optional arguments. They separated by a delimiter, taken as the first character, e.g. you can use a space.
In the description below it is assumed to be  @ , though you can use a more pleasing character such as the blank character.
Note: if you are operating the editor in batch mode, be sure to distinguish this delimiter from the batch mode delimiter.

The restart file editor can carry simultaneously two densities (1^st and 2^nd density); the 2^nd can be combined with the first to make a new density.

Instruction set:

• ?
  prints out a brief summary of editor’s instructions

• rs@[fn] read density and associated parameters from binary restart file. Use fn to specify file name, or if it not supplied, the editor will read from rst.ext
• rsb@[fn] equivalent to “rs”
• rsa@[fn] similar to “rs”, but read from ASCII file. Default name is rsta.ext.
• rsfa generate density and associated parameters from the atm file generated by lmfa (which makes free atomic densities).
• rs2@[fn] analog of rs, but read into second density
• rsa2@[fn] analog of rsa, but read into second density

• rsfa2 analog of rsfa, but read into second density

• show Show summary information about densities

• onesp Merge spin polarized density into one spin

• wrhoat Write atomic densities to rhoMT.{1..nbas}

• symrho Symmetrize site densities

• scell[@outfile=outnam  | @outfilea=outnam]@fn Generate a rst file for a supercell of the given cell, write to output file, and exit.
  Specify supercell lattice with site file fn.
  Optional outfile=outnam writes the rst file to outnam.ext.
  Optional outfilea=outnam write the rst file to outnam.ext, in ASCII format.
  If output file not not specified, editor writes to file rst2.ext.

• addspec@# append species # from 2nd density to 1st density. If  #  is zero, append a generic floating orbital species.

• addflt@#1@#2 posx posy posz insert a floating orbital at site #1. #2 = species index; it must point to a floating orbital.

• rmsite@#1 remove site #1 from site data

• chsite@#1,#2 copy site #2 density into site #1

• save[@fn] saves restart data in binary restart file (name=”rst” unless fn supplied)
• savea[@fn] saves restart data in ASCII restart file (name=”rsta” unless fn supplied)

• ssave@fn saves site data in file fn

• exch 1|2 [flip] site1 site2 Exchange the $\ell$=0 parts of two site densities.

• samparms replace file sampling parameters BZ_N, BZ_W with file values

• batch=fn read editor instructions from file fn

• q to quit the editor

• a to abort the editor

The set and add instructions

These instructions generate combinations of the charge or magnetic moment of a density, or some related parameter:
Both set and add require arguments prescription what manipulation is to be performed and on what objects (the documentation uses a space as the delimiter to avoid clutter).

1. set modifies the object at hand (in either the first or second density), while
2. add takes a combination of density 2 and density 1, and modifies density 1. For either set or add, the first argument specifies which objects are affected:

1. all applies to all quantities
2. allnc to all quantities excluding the core
3. n to the three density types
4. v to the spherical potential, ntrue to the true local density
5. pnu to the linearization parameters
6. asite refers to v+ntrue+pnu

For the set instruction:
The second argument refers to which density (1 or 2)

The third argument is one of:

1. zers: zeros spin part of density: thus n⁺ - n^- = 0
2. zerq: zeros charge part of density: thus n⁺ + n^- = 0
3. flip: exchange n⁺, n^-
4. onesp: condense to nsp=1

The set instruction takes one of these forms:

• set all | allnc | n 1 | 2 zers | zerq | flip | onesp
• set v | ntrue | pnu 1 | 2 zers | zerq | flip | onesp
• set asite 1 | 2 zers | zerq | flip | onesp site-list

For the add instruction:
The second argument must either be sync, in which the editor checks whether the densities are compatible (e.g. equivalent radial mesh), making no changes;
or otherwise, two arguments must follow, fac1 and fac2. The specified objects will be replaced by fac1×[object from 1st density] + fac2×[object from 2nd density].

The final arguments may be optional, and consist of one, or possibly two lists of sites and are used to limit application of the transformation to a subset of sites. lst1 and lst2 specify sites for the first and second densities, and follow the syntax for integer lists in the Questaal suite. The two lists are compared to determine that the corresponding site pairs are well enough synchronized to make the operation unambiguous.

For the site-only objects (v and ntrue), lst1 is required. lst2 is a matching site list for the 2nd density, OR lst2 is single site (same info is added to all sites in lst1).

The add instruction takes one of these forms:

• add all | n   sync
• add v | ntrue | pnu   sync   [lst1] [lst2]
• add all | rhoc | n   fac1 fac2
• add asite | v | ntrue | rhoc | pnu   fac1 fac2   [lst1 lst2]

Example: --rsedit~rs~set@asite@1@flip@17,20:22,25,28,30,32~set@asite@1@zers@1:16,33:64~save~q

Footnotes and references