Questaal Home

The supercell and superlattice maker lmscell

lmscell is a supercell or superlattice maker that reads standard input files, constructs supercells or superlattices, and writes supercell information to site files.


lmscell has two modes:

  • supercell maker (default mode)
    In the default mode an existing structure is enlarged into a supercell. It is up to the user to to modify the site file resulting from lmscell. This style is useful for building supercells with point defects, and the command options below apply to the default mode only.

  • superlattice editor
    In this mode, different site files are stacked together to assemble a superlattice. This mode is useful for constructing superlattices along a particular dimension. To use this mode invoke lmscell with --stack[~options]. lmscell starts a superlattice editor, which can be run interactively or in batch mode.

In either case, to get started you need a standard setup that works either for the full-potential code lmf for an ASA program such as lm.

Supercell maker

The only input you must supply in addition to a standard setup are the superlattice vectors. lmscell reads them from standard input (alternatively you can supply them in the ctrl file with tag STRUC_SLAT).

lmscell will prompt you for 9 numbers:

Enter lattice vectors of supercell, or ? for help:

Enter either:

  • 9 floating point numbers, corresponding to the first, second, and third lattice vectors of the supercell.
    Here you supply the lattice vectors directly in Cartesian coordinates. This method is useful, if you know what supercell you want at the outset. Be advised that lmscell will not work properly unless the vectors you specify can be constructed as integer multiples of the original lattice vectors.
  • m or p followed by 9 integers.
    Now the lattice vectors are given as as integer multiples of the lattice vectors of the original lattice. By construction this is always an exact supercell of the original lattice.

lmscell will generate a supercell. To create a site file, use  --wsite  or  --wsitex.  lmscell has numerous other command line options.

Superlattice editor

In this mode, lmscell starts up a superlattice editor. Unit cells are taken from site files you specify and stacked up to build a superlattice. You can build the superlattice interactively, or in batch mode. Once completed you can save the superlattice structure in a site file (by default this file is named sites.ext).

Interactive mode
To operate lmscell in interactive mode, invoke
lmscell --stack

You should see:

 Welcome to the superlattice 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.
lmscell -vz=11.5/11.43 ctrl.inas '--stack~size~site site.inas'

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

Superlattice editor instructions

This section documents the instruction set of superlattice editor. You can operate it in interative mode or batch mode, or a mix, as described above.

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

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

  • file[@options]@sitefn
    reads site file sitefn and inserts basis vectors into the existing lattice, as described below.
    P ,  Pi , and  Ps  refer the lattice vectors of the existing, insertion, and super lattices, respectively.

    1. No extension is added to sitefn; supply the full file name.
    2. The first two lattice vectors  Pi(1)  and  Pi(2)  (specifying the basal plane of the superlattice) must match the existing structure,  P(1)  and  P(2) .
    3. The superlattice  Ps  is constructed from  P(3) + Pi(3) .
    4. By default, the bottom plane of inserted lattice is offset to coincide with the top plane of the existing lattice.
      • @insert=#      insert new sites before site  # . Sites below  #  remain unchanged.
      • @scale=#      scale the lattice constant of the insertion lattice by  # .
      • @stretch=#     stretch P(3) of the insertion lattice by #. Basis vectors are kept as fixed multiples of P(3).
      • @dpos=#1,#2,#3   rigidly shift the basis vectors of the insertion lattice by (#1,#2,#3), expressed in Cartesian coordinates
      • @dup=#       repeat insertion  #  times.
      • @rsasa[options]   read ASA sphere condtions for sites being inserted (see --rsasa below)

    Example adapted from Nb/Fe superlattice tutorial (requires ctrl.nb and site3.nb) :
    site3.nb is a unit cell with 3 atoms in a single plane. The third lattice vector is  P(3)  = (0,0,1).
    The instruction below adds a new plane, shifts it by (0,0,1), and inserts a third plane betweenthe first two, making planes equally spaced :

    lmscell -vfile=3 ctrl.nb --stack~file@site3.nb~addpos@dx=0,0,1@targ=4:6~file@site3.nb@insert=4@dpos=0,0,1~show@planes

    (An unnecessarily complicated way to stack three layers! but it demonstrates several features.)

  • scale@#
    Scales lattice constant by  #

  • stretch@#
    Scales third lattice vector p3 by  #. Basis vectors are kept as fixed multiples of p3.

  • pad@#1,#2,#3
    Adds vector (#1,#2,#3) to p3, keeping site

  • sort@expr1[@expr2][@expr3] | sort@targ=lst
    Reorder sites. You can do this by:
    • By sorting them with up to three algebraic expressions of site-related parameters (optional second and third expressions have lower precedence).
      Parameters that can be used in expressions:
      • is,ib,z   site and species index, and species atomic number
      • x1,x2,x3  site positions, Cartesian coordinates
      • p1,p2,p3  site positions, projections onto lattice vectors (p1,p2,p3)
      • h1,h2,h3  site positions, projections onto reciprocal lattice vectors
    • Specifying the permutation directly (sort@targ=lst)
      Example : order sites by distance from the plane normal to p1×p2 :   sort@h3
  • newpos | addpos [@options]@dpos-specification
    Shifts or replaces a subset of site positions by dpos.
    By default the operation is performed on all sites, but the target list can be restricted.
    The source for dpos is specified in one of three ways:
    1. @dx=#1,#2,#2  uniform dpos for all sites, in Cartesian coordinates
    2. @dp=#1,#2,#2  uniform dpos for all sites, in fractional multiples of lattice vectors .
    3. @fn=filnam    dpos is read from positions file filnam By default elements 1,2,3 … nbas of the source are applied to the target.
               The number of elements in the source list cannot be smaller than the target.
    • @shorten=#,#,#  Adjusts positions of additional sites by adding lattice vectors according to conventions in shorps.f.
               #,#,# are three integers corresponding to three lattice vectors.
               #=0 suppresses the shift, #=1 places site in 1st quadrant, #=2 minimizes distance to origin
    • @targ=tlst    Restrict the operation to subset of target sites given by integer list tlst.
    • @src=slst     (use with @fn=) cull a list of source sites to be copied to target. The source becomes the list of positions defined by integer list slst.
    • @wdx=nwfile   writes shifts to a positions file nwfile.ext .
  • rsasa@options
    Reads contents (most importantly P and Q specifying log derivative parameters and sphere moments) and possibly some other parameters from ASA-style restart file. Some portions of the file (number of atoms, nuclear charge) must match the structure. This switch is designed for ASA only.
    • @fn=filename  Read information from file filename (supply the full name; no extension is appended)
    • @fn=rdim[=tag,tag,…]  replace the following data with file values
                   a : radial mesh parameter controlling spacing between points near the sphere augmentatation radius
                   nr : number of radial mesh points
                   z : atomic number
                   lmxa : augmentation l
                   class : class index
                   ves : electrostatic potential
                   rmt : sphere augmentation radius
  • initpl@left=site-list@right=site-list
    (for lmpg) Initialize principal-layer indices, supplying a list of all sites belonging both to left and another list for the right PL. The PL for the active region are not determined, but they can be found automatically using setpl@withinit.
    This switch works only if PGF_MODE is nonzero.

  • setpl[@options]@range=#  |  setpl[@options]@rangea=#
    (for lmpg) Assign to each site a principal layer index, determined by the range of a neighbor table The neighbor table is assembled by finding all pairs within # of each other.
    Principal layers are used by lmpg and are constructed so that any site connects only to its own PL, or to a nearest neighbor.
    Range is given either in atomic units (range=#) or in multiples of the lattice constant (rangea=#)
    This switch works only if PGF_MODE is nonzero.
    • @withinit     tells the editor that the left- and right- PL are given a priori (see initpl). Otherwise setpl will try to identify them from the size of PLATL and PLATR.
    • @shorps=#,#,#  Adjusts positions of each site by adding lattice vectors according to conventions in shorps.f.
              #,#,# are three integers corresponding to three lattice vectors.
              #=0 suppresses the shift, #=1 places site in 1st quadrant, #=2 minimizes distance to origin
    • @sort      re-orders sites by increasing height along the PL axis. setpl will not work unless sites are ordered.
  • cmppos[@options]@fn=file
    Read positions from file, and display shifts relative to current positions.
    • @shorten    shortens each shift by adding possible lattice vectors
    • @targ=lst    Restrict the operation to subset of target sites given by lst. See this page for the syntax of integer lists.
    • @wdx=nwfile  Writes shifts to positions file nwfile.ext
  • rmsite@targ=list
    Removes a list of sites from the structure. *targ specifies an integer list of indices to sites.

  • shorten:quad1
    Shifts site positions to lie in the first quadrant.

  • newspec | newspec=t | newspec=f
    If newspec is T, any sites added will be assigned new species names
    • newspec toggles the current status
    • newspec=t sets newspec to T
    • newspec=f sets newspec to F
  • basp@f1@f2…@fn=filename
    (application to lmf) assembles a basp file from constituent basp files f1, f2, ….
    Result is written to filename. No extension is added to f1, f2, …, or to filename.

  • cart2lat[@q]@x=#1,#2,#3 | lat2cart[@q]@x=#1,#2,#3
    Convert Cartesian coordinate (#1,#2,#3) into multiples of lattice vectors or vice-versa.
    Optional @a convert a q point into multiples of reciprocal lattice vectors.

  • show[@options]
    shows information about the current structure
    • @all :    show all of the information below (does the same no options given)
    • @size :     show size of the structure
    • @pos :   show positions of basis atoms in the structure
    • @ovl :   show overlap between spheres
    • @planes : project positions onto axis normal to basal plane
  • wsite[@options]  |  wsitex[@options]
    writes to disk a site file corresponding to the current structure
    wsite writes positions in Cartesian coordinates; wsitex as as fractional multiples of lattice vectors.
    • @fn=file :   names the file (default name is sites.ext)
    • @short :   write file in short format
    • @quad1 :   translate basis to first quadrant before writing
    • @rsasa[options] write ASA sphere condtions to file (see --rsasa above)
  • wpos[@fn=nwfile]
    writes current positions to positions file nwfile.ext. If not specified, nwfile.ext is pos.ext

  • q
    quit editor and stop

Other resources