# 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 file*sitefn*and inserts basis vectors into the existing lattice, as described below.

**P**,**P**, and^{i}**P**refer the lattice vectors of the existing, insertion, and super lattices, respectively.^{s}- No extension is added to
*sitefn*; supply the full file name. - The first two lattice vectors
**P**and^{i}(1)**P**(specifying the basal plane of the superlattice) must match the existing structure,^{i}(2)**P(1)**and**P(2)**. - The superlattice
**P**is constructed from^{s}**P(3)**+**P**.^{i}(3) - 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.

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

- No extension is added to

**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**

- By sorting them with up to three algebraic expressions of site-related parameters (optional second and third expressions have lower precedence).

**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:**@dx=#1,#2,#2**uniform**dpos**for all sites, in Cartesian coordinates**@dp=#1,#2,#2**uniform**dpos**for all sites, in fractional multiples of lattice vectors .**@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*.

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

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

**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=**: names the file (default name is*file**sites.ext*)**@short**: write file in short format**@quad1**: translate basis to first quadrant before writing

**wpos[@fn=nwfile]**

writes current positions to positions file*nwfile.ext*. If not specified,*nwfile.ext*is*pos.ext*

**q**

quit editor and stop