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.

Introduction

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. A tutorial using this mode can be found here.

• 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]. This switch starts the superlattice editor, which can be run interactively or in batch mode. Numerous tutorials use the stack editor, such as here and here.

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 interactive mode or batch mode, or a mix, as described above.

Most instructions have optional arguments. They are separated by a delimiter, the first character after the instruction (assumed in this documentation to be  ”@”).
Note: if you are operating the editor in batch mode, be sure to distinguish the delimiter separating options from the batch mode delimiter.

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

• 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

• assign@var=pos(#1,#2)
  Assigns variable var to one element read from site positions. #1 must be between 1 and 3, #2 between 1 and nbas.
  var can be used in other instructions that read expressions, e.g. ~assign@z=pos(3,1)~addpos@dx=0,0,-z subtracts pos(3,1) from pos(3,:).

• file@sitefn[@options]
  read site file sitefn and insert contents into the existing lattice. In the description below  P ,  Pⁱ , and  P^s  refer the lattice vectors of the prior, insertion, and and final lattices, respectively.
  1. By default, sitefn refers to sitefn.ext. If that file is not present sitefn should refer to the full file name.
  2. The first two lattice vectors  Pⁱ(1)  and  Pⁱ(2)  (specifying the basal plane of the superlattice) must match the existing structure,  P(1)  and  P(2) .
  3. In default mode, the new lattice is “tacked on” to the existing one:
     
     • sites in the insertion lattice are translated by  P(3), or dpos+P3 if dpos is supplied.
     • P(3)  is updated so that  P^s(3)  = P(3) + Pⁱ(3).
  4. In insert mode, the new lattice is “inserted” inside the existing one:
     
     • sites in the insertion lattice are translated by dpos only
     • P(3)  is updated so that  P^s(3)  = P(3) + Pⁱ(3).

  Options acting on the insertion lattice:

  • @scale=#      scale the insertion lattice constant by  #.
  • @scale3=#      scale insertion vector  Pⁱ(3) by  #. Thus @scale3=0 causes  P(3)  to stay fixed.
  • @stretch=#      scale insertion vector  Pⁱ(3) by  #, and also shear insertion basis vectors.
  • @p3=#1,#2,#3    assigns insertion vector  Pⁱ(3) to #1,#2,#3
  • @dpos=#1,#2,#3    shift the insertion basis by (#1,#2,#3), expressed in Cartesian coordinates.
               (Note: in default mode, true shift is dpos+P3).
  • @dup=#       repeat insertion  #  times.
  • @rsasa[options]   read ASA sphere conditions for sites being inserted (see --rsasa below).
  • @targ=tlst      Cull a subset of sites from sitefn. as given by given by an integer list tlst of site indices.

  Options acting on the host:

  • @insert=#      insert new sites before site  #. Site indices  #…last are incremented
  • @xinsert=#     same as insert, but also shift sites  #…last by  Pⁱ(3).

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 between the 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.

• sadd[@scl0=#[,#2]][@scl=#[,#2]][@shorten][@addp]@fn=fnam
  Information (lattice and and site positions) is read from reference site file fnam and added to the existing structure. A check is made that site file fnam has the same number of atoms and the same species. The file data is added, with the following modifications before the addition.

  • @scl0=#[,#2] scales the existing positions and lattice vectors by  #. If  #2  is present, site positions are scaled by  #, and lattice vectors are scaled by  #2.
  • @scl=#[,#2] scales the positions and lattice vectors read from reference file fnam by  #. If  #2  is present, site positions are scaled by  #, and lattice vectors are scaled by  #2.
  • @shorten will add lattice translation vectors to position vectors, if a position vector (in units of its own lattice vectors) becomes closer to the reference positions vectors (in units of the reference lattice vectors).
    In this mode, @scl0 and @scl are not used, and the reference information is used only to “shorten” the position vectors.
  • @addp is similar to @shorten, except that @scl0 and @scl are active, and a linear combination of the original and reference vectors is taken.
    Example : sadd@addp@scl0=.9@scl=.1@fn=site.tnsem

• align@fn=ref-fnam[@mergep][@merges][@reforder]
  Align reference site file to existing site data and optionally merge reference position or species data into it. It constructs a list of both site data sorted by positions and aligns the jointly sorted list.
  Options:
  • @mergep   merges reference site positions into site data
  • @merges   merges reference species positions into site data
  • @reforder   reorders sites in reference order
    Example : align@mergep@fn=site.ref@reforder

• pad@#1,#2,#3
  Adds (#1,#2,#3) to P(3), keeping site positions unchanged.

• p3@#1,#2,#3
  Assigns (#1,#2,#3) to P(3), keeping site positions unchanged.

• sort@targ=lst  |  sort[@targ=lst]@expr1[@expr2][@expr3]
  Reorder sites. You can do this by:
  • Specifying the permutation directly (sort@targ=lst).
    In this mode lst must consist of an integer list consisting of the nbas sites (nbas=size of basis), specifying order.

  Example : Move sites 19,20 to sites 1,2 for a 34-atom unit cell : sort@targ=19,20,1:18,21:34

  • By sorting them with up to three algebraic expressions of site-related parameters (optional second and third expressions have lower precedence).
    In this mode you can optionally sort on a subset of sites. Select the subset with @targ=lst.
    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\

  Example 1 : order sites by distance from the plane normal to p1×p2 :   sort@h3
  Example 2 : order sites 1-20 by decreasing species index : sort@targ=1:20@x3@-is

• list@expr1[@expr2][@expr3]
  list sites for which expr1 evaluates to true. expr1 like that for sort, except it evaluates to logical.

• 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,#3  uniform dpos for all sites, in Cartesian coordinates
  2. @dp=#1,#2,#3  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.
     Options:
  • @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 1^st 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 .

• cmppos[@options]@fn=file
  Read positions from file, and display shifts relative to current positions.
  Options:
  • @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
  • @wdx~options  similar to wdx but you can supply some optional arguments:
                    @wdx!mode=1!fn=nwfile  causes this file to be written in sparse mode, to file nwfile.ext.

• rmsite@targ=list  |  rmsite@incl@expr  |  rmsite@excl@expr
  Removes a list of sites from the structure. List is specified by one of the following:
  • targ specifies an integer list of indices to sites.
  • incl@expr keeps only sites for which expr evaluates to true.
    expr is a logical expression consisting of the same variables used in the sort instruction explained above, for example @incl@z==0&x3<1.4.
  • excl@expr keeps only sites for which expr evaluates to false.
    Example: see this tutorial.

• ring@off  |  roll@off
  Treats the site list as a ring and rotates the list by off registers. ring and roll do the same thing.
  Example: ring@off=10 shifts sites 1:nbas-10 to 11:nbas and nbas-9:nbas to 1:10.

• shorten  |  shorten@options
  Shifts site positions by addition of lattice translation vectors (one condition each for P₁ P₂, P₂, corresponding to #1,#2,#3 below).
  Without options, shorten is equivalent to shorten@mode=2,2,2
  Options:
  • @targ=lst    Restrict the operation to subset of target sites given by integer list ilst. Without this modifier the instruction applies to all sites.
  • @mode=#1,#2,#3    Specifies how to shorten. The is one condition for each axis:
    Use #=0 to suppress shortening, #=1 to place in first quadrant, #=2 to minimise length.
  • @quad1    is shortand for shorten@mode=1,1,1.

• shorp3
  shortens third lattice vector P₃ by adding integer multiples of P₁ and P₂ to it.

• 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.
  Options:
  • @fn=filnam  Read information from file filnam (you can supply a name without the extension, or the full name).
  • @ib=n@src=site-list  imports ASA moments P, Q for sites in site-list contained in filnam, and copies them into sites ib,ib+1,….
    The number of sites copied is the size of site-list, which is an integer list.
  • @rdim[,tag,tag,…] Also replace the species corresponding to sites read species data with file values. Optional tags allow you to specify which values to replace.
    It operates in the same way as the rdim option in the restart file editor, which see.

• 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=#  |  setpl@mergeu=#1,#2  |  setpl@merged=#1,#2
  Assigns principal layer (PL) indices for lmpg. PLs are constructed so that any site connects only to its own PL, or to an adjacent PL.
  Note: this switch works only if PGF_MODE is nonzero.
  
  • setpl using range:
    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.
    Range is given either in atomic units (range=#) or in multiples of the lattice constant (rangea=#)
    Options:
    • @withinit  tells the editor that trial indices for left- and right- PL are already supplied (see initpl).
             Otherwise the editor will try to identify them from the size of PLATL and PLATR.
             Note: setpl may alter the trial L- and R- specifications.
    • @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 1^st 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.
    • @unsort   restores the site permutation caused by sort after PL are assigned
  • setpl using merge:
    mergeu=list  Assigns the same PL index to sites in list as the PL belonging to the first site in the list. list is an integer list of sites.
    merged=list  Assigns the same PL index to sites in list as the PL belonging to the last site in the list.

  Example: see this tutorial.

• omax=#1[,#2,#3]
  Override contents of SPEC_OMAX1, which sets maximum sphere overlaps to  #1  when the sphere resizer is invoked (see resize below).
  Optional #2 and #3 concern A-E and E-E overlaps, respectively where A are true atoms and E are empty spheres. #2 is copied from #1 if not present; #3 is copied from #2.

• resize@options  |  findes@options
  Resize spheres, or find new empty spheres (E sites, atomic number 0) to improve lattice packing. The algorithm proceeds as follows:
  1. Selected species (see spec below) are resized to be as large as possible consistent with size constraints specified by --omax), or until sum-of-sphere volumes = target volume.
     By default the target volume is the unit cell volume (required by the ASA).
  2. (findes only) 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 (specified --omax), or until until the space filling constraint is satisfied.
  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 dup=# and mino are both present, steps (3,5) are repeated  # times.

  Similar functionality is available in lmchk and blm.
  Options:

  • @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 :     Minimise sphere overlaps after new spheres have been found.
  • @omaxi=#1[,#2,#3] :
           When finding empty spheres, temporarily resize spheres to specs #1[,#2,#3] (meaning is same as --omax= above).
           After they 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.
  • @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.
  • @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 x₁, x₂, x₃ (Cartesian coordinates, in units of the lattice constant) or p₁, p₂, p₃ (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] :  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.
  • @dup=# :    (when omin is turned on) duplicate the (resize, omin) sequence # times, to iteratively improve the sphere packing.

  Example: see this tutorial.

• 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.

• wspec[@options]
  Writes a template SPEC category to file spec. It performs the same function as the --wspec switch as an optional argument to lmchk. See command line argument documentation to lmchk for available options.

• 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

• batch=fn
  similar to batch mode, but read editor instructions from file fn. Separate instructions by newlines.

• q  |  a
  quit editor and stop

Other resources