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, from a special-purpose site file, as explained below.
How site positions are read or modified
Site information contains two essential things: the chemical species it belongs to, and the site positions p, (also called basis vectors 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=fnam. The contents of file fnam.ext supersede the initial positions. You can also read a file containing a shift in positions Δp, to be added to p, with --rdpos.
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:
Read from either the main input file ctrl.ext, or the site file (see below).
Superseded with contents of fnam.ext, if command-line switch
--rpos=fnamis present.
fnam.ext an n×3 array, where n is the size of the basis, usually in the standard Questaal format for two-dimensional arrays, though there is an alternate format. You can also use--rposwithout specifying a name in which case the file name becomes pos.ext.Or, you can use
--rdpos. It reads positions in the same way as--rpos, but it adds the file contents to the existing positions. (You can also specify a scaling to the shift). If you do not specify a name, the default name is dpos.ext.You can also use both
--rposand--rdpos: positions are first read via--rposand then shifted via--rdpos.Some lattice vector may be added to minimize distance to origin, unless command-line switch
--shorten=nois present.
Applies to full-potential codes only.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
You can read structural information from a site file. This 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.
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
Note: The site file is normally passed through the file preprocessor before it is parsed.
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.w
- 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.
Site information for Principal Layer geometry
For codes with periodic boundary conditions (e.g. lmgf), boundary conditions are periodic in PLAT. The principal layer code lmpg is similar, except that the boundary condition on the 3rd axis is different. Half crystals extend to the left and right, to ±∞. A single principal layer for each end (which stacks an infinite number of times on a half line) defines the structure of the cladding layers. They must be specified through vectors PLATL and PLATR. These latter quantities are always input in the ctrl file.
Also in the layer geometry, it is necessary that a principal layer index be assigned to each site.
Thus PLAT can be the same for the periodic codes such as lmgf as it is for lmpg.
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.