Questaal Home
Navigation

Specifying Lattice and Site Information

Introduction

Structural information has two elements : lattice information (lattice vectors including lattice constant), and the basis, i.e. positions of atoms within the unit cell (site information). Unless you specify otherwise, these data are read from the main input file, ctrl.ext. Lattice information data are read from the STRUC category and site information from the SITE category. You can choose to read one or the other, or both, through special tags in ctrl.ext, as explained in the section below.

How site positions are read or modified

Site information contains two essential things: the chemical species it belongs to, and the site positions, and optionally several bits of secondary information associated with it. Initially this information is read either from ctrl.ext or the site file, so that a correspondence between sites and species is established. These positions can be re-read from a positions file, using command-line switch --rpos=filename. The contents of file filenam.ext supersede the initial positions.

The full-potential codes, e.g. lmf, will attempt to shorten the basis vectors, to bring them as close to the origin as possible. This is done to facilitate calculation of Ewald sums.

Site positions are also stored in the restart file. By default, lmf will read these positions, superseding the existing data for site positions.

In summary the site positions are read or translated multiple times, in the following order:

  1. Read from either the main input file ctrl.ext, or the site file (see below).

  2. Overwritten with contents of filenam.ext, if command-line switch --rpos=filenam is present.
    filenam.ext should have the standard Questaal format for two-dimensional arrays.

  3. Some lattice vector may be added to minimize distance to origin, unless command-line switch --shorten=no is present.
    Applies to full-potential codes only.

  4. Read from the restart file, unless argument #3 in the command-line switch --rs=#1[,#2,#3,#4,#5] is set to 1.
    Applies to full-potential codes only.

Note: in the DFT case, shifting site positions by a lattice translation vector should have no effect. But matrix elements in the QSGW self-energy Σ0 do change by a phase. If the site positions are shifted by a lattice translation vector, the phase in Σ0 must also be updated to correspond to the translated positions.

Note: the ASA codes read site positions when making the structure constants (program lmstr), which are stored on disk. The ASA codes lm, lmgf, and lmpg read the structure constants. If the site positions read by one of these codes do not tally with a checksum in the structure constants file, the program will abort.

Reading structural information from a site file

The site file has no predetermined name; you specify it in ctrl.ext.

  • To read lattice information from sname.ext, use the FILE token in STRUC.
  • To read site information from sname.ext, use the FILE token in SITE. The following snippet does both:
STRUC  FILE=sname
       ...
SITE   FILE=sname
       ...

Note: If you use the file token in the EXPRESS category, it performs the function of both STRUC_FILE and SITE_FILE, and supersedes both of these tags.
Note: The site file is normally read through the file preprocessor.

In the EXPRESS mode the species labels are determined from the site file; and the number of atoms and species are determined from the site file so that STRUC_NBAS and STRUC_NSPEC are not used. For every species label in the site file there must be a corresponding label in the SPEC category.

Structure of the site file

The first nonblank, non-preprocessor directive, should begin with:

% site-data vn=#

Note: Version 7 of the Questaal suite writes version 3.0 site files; it can read versions 3.0 and prior versions.

This first line must also contain token io=#.   io=14 tells the reader that minimal information is available in the file:

  • the number of sites in the lattice
  • the lattice vectors
  • the basis vectors and their species ID.

Usually the first line contains the lattice constant as well. Consider the following snippet:

% site-data vn=3.0 xpos fast io=62 nbas=64 alat=7.3956 plat= 2.0 0.0 0.0 0.0 2.0 0.0 1.0 1.0 3.58664656
#                        pos                                vel                     eula              vshft   PL rlx
 K1        0.0000000   0.0000000   0.0000000    0.0000000    0.0000000    0.0000000    0.0000000    0.0000000    0.0000000 0.000000  0 111
 Fe1       0.3750000   0.1250000   0.2500000    0.0000000    0.0000000    0.0000000    0.0000000    0.0000000    0.0000000 0.000000  0 111

The first line tells the parser the following:

  • io=62 indicates that the following information is available for each site, in the order listed:
    • species index (labels must syncrhonise with the SPEC category in the ctrl file.
    • site positions (expressed as multiples of plat because xpos appears in the first line).
    • velocities – used in molecular dynamics.
    • Euler angles. Rotates the spin quantization axis used by noncollinear parts of the ASA code.
    • site potential shifts, which may be used by the ASA.
    • principal layer index used by the layer Green’s function code.
    • three binary integers nnn specifying which of the three Cartesian components are frozen in molecular dynamics or statics.
      1 allows to relax while 0 freezes that coordinate.
  • xpos indicates that the basis vectors are written as fractional multiples of lattice vectors. By default these vectors are written in Cartesian coordinates in units of the lattice constant alat.
  • fast tells the parser to read basis information with FORTRAN read. By default it will parse each element as an algebraic expression. FORTRAN read is much faster, but you lose the capability of using expressions.
  • nbas=64 tells the parser that there are 64 atoms in the crystal.
  • alat=7.3956 specifies the lattice constant, in atomic units.
  • plat=… specifies the lattice vectors, P1, followed by P2 and P3.

The second line in the snippet above is a comment line. Then follows a sequence of 64 lines, one line for each atom. As a minimum, the row must contain a species label and the site position (io=14). In the snippet above (io=62) the extra information is given.

The bottom of the file may contain “map” data similar to the following snippet

#map   4   2   5   3   9   8   6   1   7   4   2   5   3   9   8   6   1   7   4   2   5   3   8   9
#map   6   1   7   4   5   2   3   9   8   6   1   7

This is generated by the supercell maker lmscell. It maps current sites into original sites from which the supercell was constructed. The mapping is needed to generate the density restart file rst.ext of the supercell from the original one, or the GW self-energy file, sigm.ext.

Other resources

Many of the tutorials, e.g. the basic lmf tutorial, make use of site files. The input file maker, blm, typically generates ctrl and site files as a pair.

Questions or Comments


If this page has any errors, there is something you think is missing or unclear, or for any other issues, you can create a post here letting us know.