# WFS2LDOS: A program to simulate STM images and STS spectra¶

author

Pablo Ordejón, Nicolás Lorente, Alberto García

## INTRODUCTION¶

The program WFS2LDOS calculates information for STM images or STS analysis using wavefunctions and other information generated by Siesta. It is included among the utilities distributed with Siesta and it shares several of its basis routines. WFS2LDOS was written using basic routines from Siesta and from Denchar.

The code calculates the charge density (actually, the local density of states (LDOS), which is the charge density generated by wavefunctions in a given energy window) of the surface on a grid in real space, defined by the user. The STM images in the Tersoff-Hamann approximation correspond to maps of the calculated LDOS. The results are printed in the grid-file format used by Siesta, a binary file with the same format as the RHO, LDOS, etc. files of Siesta. The program streams through the wave-function file, without the need to keep all the wavefunctions in memory.

The grid in this file is not the one used in the Siesta calculation, but the one defined by the user in the WFS2LDOS input file (see below). This file can be visualized by means of the Plrho code (in Util), or by the WSxM freeware from WSxM Solutions (a powerful Windows application for data acquisition and processing in scanning probe microscopy, which can be freely downloaded from http://www.wsxmsolutions.com/. It might be possible to make it run on MacOS through the Wine emulator). It can also be converted to a Gaussian Cube format file by the use of the ’g2c_ng’ program in Util/Grid. Files in Cube format can be visualized by means of standard programs such as Vesta, Moldel and Molekel.

2D sections of the information contained in the file can be obtained with the ’plstm’ code. This also offers the possibility of obtaining spin-projected information, even for non-collinear cases.

In its simplest operation, WFS2LDOS uses directly the wavefunctions generated by Siesta for the generation of the LDOS used in the simulation of the STM images. In the Tersoff-Hamann approximation, the STM image corresponds to the value of the “charge density” (LDOS) (within the energy window defined by the tip-sample potential) at the position of the tip.

However, for realistic experimental conditions the tip is relatively far from the surface. Therefore, the accuracy of the Siesta calculation is not sufficiently good, becasue the basis set is short-ranged, and also because of other issues common to other approaches like plane waves (the value of the charge at these distances is so small that it does not influence the total energy, which is the quantity minimized in DFT, and therefore the values obtained are not accurate).

To improve the situation, this code can optionally compute the values of the wavefunctions generated by Siesta on a reference plane (defined by the user) at a distance sufficiently close to the surface so that the charge density is correctly represented, and then extrapolate the value of these wavefunctions into the vacuum. This is done assuming that the potential is already flat at the reference plane, and using the analytical expressions for the propagation of the solutions of the Schroedinger equation into vacuum. Therefore, the reference plane must be sufficiently close to the surface so that the charge density is large and well described by Siesta, but sufficiently far so that the constant potential approximation is approximately satisfied. In practice, one might need to extrapolate from a plane that is not really in the completely flat region, since otherwise the wavefunctions would be too small (or zero).

WFS2LDOS needs to perform some Fast Fourier Transforms to extrapolate the value of the wavefunctions into vacuum. Currently, routines from the FFTW package are called for this. If the FFTW suite is not installed in your machines, you will have to download it (available at http://www.fftw.org under the GNU General Public License).

Limitations: WFS2LDOS works only for monoclinic cells. The third lattice vector must be in the $$z$$ direction and be perpendicular to the other two lattice vectors.

## HOW TO COMPILE AND RUN THE PROGRAM¶

In this section we give all the steps required to install and run the program. We assume that you use UNIX, and that you have not moved the source of WFS2LDOS from $$\sim$$/siesta/Util/STM/ol-stm/Src.

### Compilation¶

• Change to the directory where the sources of WFS2LDOS are:

# cd \sim/siesta/Util/STM/ol-stm/Src

• Edit Makefile to add the correct references to the installed FFTW library. Alternatively, you might have them in your top-level arch.make file.

• Make the executable: # make stm or

# make OBJDIR=YourMainBuildDir stm if you have compiled Siesta in a directory different from Obj.

• The program should compile and an executable file called stm should be created.

### Running the code¶

WFS2LDOS needs some information that will be supplied by Siesta. The first thing we must do is to run Siesta for the system we are interested in, setting up variable WriteDenchar to true. In this way Siesta will generate two files called SystemLabel.PLD and SystemLabel.DIM where information needed to plot the charge density and/or wavefunctions in real space is dumped. You also need to have the files which contain the information about the basis set for each species in your system: ChemicalSpecies.ion (one for each chemical species), which are also generated by Siesta. You will also need the file containing the wavefunction coefficients SystemLabel.WFSX. A wavefunction file is obtained in the Siesta run by defining the wave functions to be plotted with the WaveFuncKPoints descriptor, or by using the COOP.Write T fdf option (in this case the wavefunctions at all k-points used to sample the BZ during self-consistency are included). Finally, if the code needs to project wavefunctions using the reference plane (i.e. STM.MaxZ is bigger than STM.RefZ), you need the file containing the Hartree potential on the grid Systemlabel.VH (printed by Siesta using the SaveElectrostaticPotential descriptor) in order to define the vacuum potential. These files need to be present in the directory where WFS2LDOS will run.

You need to link the SystemLabel.selected.WFSX file (or the SystemLabel.fullBZ.WFSX file) produced by Siesta to SystemLabel.WFSX before executing the program. The “selected” qualifier is used in connection with the WaveFuncKPoints option, and “fullBZ” when the COOP.Write T option is selected.

In principle you need the whole BZ’s worth of wavefunctions (in the appropriate energy window), but restricted sets of k-points might be used for testing.

You also need to create an input file for WFS2LDOS (let’s call it stm.fdf), following the instructions given in Section 3. Then, feed it to WFS2LDOS as standard input:

# wfs2ldos < stm.fdf

## INPUT DATA FILE¶

The input data file is written in an special format called FDF, developed by Alberto Garcı́a and José M. Soler (see Siesta USER’S GUIDE). It contains all the parameters needed to specify the details of the run and to define the plane or coordinates system. Here is a description of the variables that you can define in your Denchar input files, with their data types and default values.

### General descriptors¶

These options are common for STM and STS operation. The only difference is in the keyword specifying the number of energy samples (see below).

SystemLabel

(string): A single word (max. 20 characters without blanks) containing a nickname of the system, used to name output files. It must be the same that you use when you run Siesta!!

Default value: siesta

STM.label

(string): A single word (max. 20 characters without blanks) containing a special label for the STM run, to be pasted to the SystemLabel when creating files.

Default value: blank

NumberOfSpecies

(integer): Number of different atomic species in the simulation. Atoms of the same species, but with a different pseudopotential or basis set are counted as different species. Use the same value as in the Siesta run.

Default value: There is no default. You must supply this variable.

ChemicalSpeciesLabel

(data block): It specifies the different chemical species that are present, assigning them a number for further identification. Use the same as you did in Siesta.

Use: This block is mandatory.

Default: No default.

### Description of the 3D grid where the charge density is obtained.¶

STM.DensityUnits

(string): Character string to specify the units of the charge density in output. These can be expressed in three forms:

• Ele/Bohr**3 : Electrons/bohr**3

• Ele/Ang**3 : Electrons/angstrom**3

• Ele/UnitCell : Electrons/Unit Cell

Default value: Ele/bohr**3

STM.NumberPointsX

(integer): Number of subdivision of the grid in the direction of the first lattice vector. Together with STM.NumberPointsY and STM.NumberPointsZ it will define the number of points of the grid to plot the charge density.

Default value: 50

STM.NumberPointsY

(integer): Number of subdivision of the grid in the direction of the second lattice vector. Together with STM.NumberPointsX and STM.NumberPointsZ it will define the number of points of the grid to plot the charge density.

Default value: 50

STM.NumberPointsZ

(integer): Number of subdivision of the grid in the z-direction (which must be the direction of the third lattice vector). Together with STM.NumberPointsX and STM.NumberPointsY it defines the number of points of the grid to plot the the charge density.

Note that, for STS operation, the data file produced might be large if more than one plane is used. It is suggested to set this parameter to 1 in that case. Operation on a single plane is also fine for STM mode.

Default value: 50

STM.MinZ

(real length): Defines the minimum value of the z-component of the 3D grid.

Default value: None. Must be defined in input file.

STM.MaxZ

(real length): Defines the maximum value of the z-component of the 3D grid.

If a single plane is requested, STM.MaxZ is not used, and it is set implicitly to STM.MinZ.

Default value: None. Must be defined in input file.

STM.RefZ

(real length): Defines the z-component position of the reference plane from where the wavefunctions will be extrapolated into vacuum.

The LDOS values for planes below the reference level are obtained from the original wavefunctions. Those above the reference level are obtained from projected wavefunction values.

Default value: None. Must be defined in input file.

STM.VacZ

(real length): Defines the z-component position of the plane on which the zero of the Hartree potential in the vacuum region is taken. This should be a position at the center of the vacuum of the slab. You might want to check (better: plot) the V(z) values printed in the SystemLabel.v_ave_z file. Similar information can be obtained using the experimental v_info program in Util/Grid.

Default value: None. Must be defined in input file.

STM.NumberCellsX

(integer): Defines how many times the unit cell is repeated in the direction of the first lattice vector.

Default value: 1

STM.NumberCellsY

(integer): Defines how many times the unit cell is repeated in the direction of the second lattice vector.

Default value: 1

### Description of the energy window for STM/STS.¶

STM.Emin

(real energy): Lower value of the energy window.

Default value: -1.0 eV

STM.Emax

(real energy): Upper value of the energy window.

Default value: 1.0 eV

STS.NumberOfPoints

(integer): Number of energy points in the above energy window at which to sample the LDOS. If this value is not specified, or if it is 1, no STS calculation will be performed

Default value: 1 (no STS calculation)

(real energy): Standard width of the broadening function.

Default value: 0.2 eV

(string) Kind of broadening function. Not implemented yet. Currently only a gaussian function is offered.

Default value: (“gaussian”)

## OUTPUT FILES¶

In STM mode, the program produces a file which contains the value of the charge density (which is actually the “local density of states” integrated over the desired energy window), on the grid defined by the user. In STS mode, the file uses the “spin” dimension to represent the energy dimension.

*SystemLabel*.v_ave_z

: An ASCII file containing the V(z) profile of the electrostatic potential. Plotting the information in this file is useful to set appropriately STM.Vacz and STM.RefZ. Similar information can be obtained using the experimental v_info program in Util/Grid.

*SystemLabel*.STM.LDOS

: In STM mode, it contains the value of the LDOS (all relevant spin components) at the grid defined by the user, in Siesta grid format. Can be plotted using WSxM and further processed by the Util/STM/simple-stm/plstm program.

*SystemLabel*.STS

: In STS mode, it contains the value of the LDOS at the grid defined by the user, for all the energies sampled in the energy window, in Siesta grid format. It can be processed in several ways, but currently there is only a example in Util/STM/simple-stm/plsts. Only the “total charge” spin projection (as in the ’q’ option of ’plstm’) is stored.

*SystemLabel*.STS_AUX

: In STS mode, this ASCII auxiliary file contains the values of the energies used for sampling.

## EXAMPLES¶

In directory \sim/siesta/Util/STM/ol-stm/Examples you will find two examples: one for a “benzene molecule”, and another for a magnetic monolayer of Cr, with spin-orbit interaction.