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.

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), is 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 filesitefn 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.

No extension is added to sitefn; supply the full file name.

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

The superlattice Ps is constructed from P(3) + Pi(3) .

By default, the bottom plane of inserted lattice is offset to coincide with the top plane of the existing lattice. Options:

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 :

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:

@fn=filnamdpos 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 1st quadrant, #=2 minimizes distance to origin

@targ=tlst Restrict the operation to subset of target sites given by integer listtlst.

@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 listslst.

@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. Options:

@fn=filename Read information from file filename (supply the full name; no extension is appended)

setpl[@options]@range=# Assigns 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 (specify # in atomic units). Principal layers are used by lmpg and are constructed so that any site connects only to its own PL, or to a nearest neighbor. This switch works only if PGF_MODE is nonzero. Options:

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

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.