% Manual for the STM program
%
% To generate the printed version:
%
% latex stm
% latex stm
% [ dvips stm ] 
%
%   Pablo Ordejon and Nicolas Lorente
%   November 2004
%   Alberto Garcia, August 2009


\documentstyle[11pt]{article}

\tolerance 10000
\textheight 22cm
\textwidth 16cm
\oddsidemargin 1mm
\topmargin -15mm

\baselineskip=14pt
\parskip 5pt
\parindent 1em

\begin{document}

% TITLE PAGE --------------------------------------------------------------

\begin{titlepage}

\begin{center}

\vspace{1cm}

{\huge {\sc User's Guide}}

\vspace{4cm}

{\Huge {\bf {\sc STM} 1.0.1} }

\vspace{0.5 cm}

{\Large {\it - A program to simulate STM images -}}


{\Large {\it December 21, 2004}}

\vspace{3cm}

{\Large Pablo Ordej\'on}

\vspace{5pt}

{\it Institut de Ci\`encia de Materials de Barcelona - CSIC\\
Campus de la UAB, 08193 Bellaterra, Barcelona, Spain}

\vspace{2pt}
{\bf ordejon@icmab.es}

\vspace{1cm}

\vspace{3cm}
{\Large Nicolas Lorente}

\vspace{5pt}

{\it IRSAMC, 
Universit\'e Paul Sabatier \\
118 route de Narbonne
31062 Toulouse, cedex France
}

\vspace{2pt}
{\bf lorente@irsamc.ups-tlse.fr}

\vspace{7mm}
\end{center}

\end{titlepage}

% END TITLE PAGE --------------------------------------------------------------

\tableofcontents

\newpage



\section{INTRODUCTION}

The program {\sc STM} calculates STM images using the output
generated by {\sc Siesta}.
It is included among the utilities distributed with {\sc Siesta}
and it shares several of its basis routines. 
{\sc STM} was written using basic routines from 
{\sc Siesta} and from {\sc Denchar}.

The code calculates the charge density 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 charge density. 
The results are printed in two formats:

\begin{itemize} 

\item{{\sc Siesta} grid format:}
The charge density is printed into a binary file with the same
format as the RHO, LDOS, etc. files of {\sc Siesta}. The grid
in this file is {\bf not} the one used in the {\sc Siesta}
calculation, but the one defined by the user in the {\sc STM}
input file (see below).
This file can be visualized by means of the {\sc 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).


\item{Gaussian Cube:}
This can be visualized by means of standard programs
such as {\sc Vesta}, {\sc Moldel} and {\sc Molekel}. This is only possible
when the cell vectors are orthonormal (ie, for tetragonal systems).
Therefore, this file is only printed for tetragonal cells.

\end{itemize}

{\sc STM} does {\bf not} use directly the wavefunctions or charge density
generated by {\sc Siesta} for the simulation of the STM images. The
reason for this is that, in the Tersoff-Hamann approximation,
the STM image corresponds to the value of the charge density
(within the energy window defined by the tip-sample potential)
at the position of the tip. For realistic experimental conditions
the tip is relatively far from the surface. Therefore, the accuracy
of the {\sc Siesta} calculation is not sufficiently good, becasue
the basis set is short-ranged but 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).

Instead, this code uses the wavefunctions generated by {\sc Siesta}
and computed on a reference plane (defined by the user)
at a distance sufficiently close to the surface so that the
chare density is correctly represented, and {\em extrapolates}
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, {\bf the
reference plane must be sufficiently close to the surface
so that the charge density is large and well described by {\sc Siesta},
but sufficiently far so that the constant potential approximation
is approximately satisfied.}

{\sc STM} 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).

\noindent
{\bf Limitations:} {\sc STM} works only for monoclinic cells.
The third lattice vector {\bf must} be in the $z$ direction
and be perpendicular to the other two lattice vectors.

\section{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 {\sc STM} from $\sim$/siesta/Util/STM/ol-stm/Src.

\subsection{Compilation}

  \begin{itemize}

   \item Change to the directory where the sources of {\sc STM} are:

         {\tt \# cd $\sim$/siesta/Util/STM/ol-stm/Src}

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

   \item Make the executable:
         {\tt \# make stm} or
     
         {\tt \# make OBJDIR=YourMainBuildDir stm} if you have
         compiled Siesta in a directory different from Obj.

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

  \end{itemize}

\subsection{Running the code}

 {\sc STM} needs some information that will be supplied by {\sc Siesta}. 
 The first thing we must do is to run {\sc Siesta} for 
 the system we are interested in,
 setting up variable WriteDenchar to true. 
 In this way {\sc Siesta} will generate
 two files called {\it SystemLabel}.PLD and {\it 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: {\it ChemicalSpecies}.ion (one for each
 chemical species), which
 are also generated by  {\sc Siesta}.
 You will also need the file containing the
 wavefunction coefficients {\it SystemLabel}.WFSX. 
 A wavefunction file is obtained
 in the {\sc Siesta} run by defining the wave functions to be
 plotted with the {\bf WaveFuncKPoints} descriptor, or by using the
 {\bf 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, you need the file containing the Hartree potential on the grid 
 {\it Systemlabel}.VH (printed by {\sc Siesta} using the 
 {\bf SaveElectrostaticPotential} descriptor)
 in order to define the vacuum potential. 
 These files need to be present in the
 directory where you are running {\sc STM} (let's call it
 $\sim$/siesta/Util/STM/ol-stm/RUN).

 Go into the directory where {\sc STM} will run:

 {\tt \# cd $\sim$/siesta/Util/STM/ol-stm/RUN}

 Copy all the required files into this directory; if you
 have run {\sc Siesta} in directory $\sim$/siesta/RUN:

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.PLD .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.DIM .}

 {\tt \# cp $\sim$/siesta/RUN/*.ion .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.selected.WFSX .}

 or  {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.fullBZ.WFSX .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.VH .}

 You need to link the {\it SystemLabel}.selected.WFSX file (or the
 {\it SystemLabel}.fullBZ.WFSX file) to {\it SystemLabel}.WFSX before
 executing the program. The ``selected'' qualifier is used in
 connection with the {\bf WaveFuncKPoints} option, and ``fullBZ'' when
 the {\bf COOP.Write T} option is selected.
      
 Copy or link the executable file to the directory
 where you intend to run  {\sc STM}, and that
 contains the files described above:

 {\tt \# ln -s $\sim$/siesta/Util/STM/ol-stm/Src/stm . }

 Create an input file for {\sc STM}, {\it stm}.fdf, following the 
 instructions given in Section \ref{cap:input}. Then,
 feed it to  {\sc STM} as standard input:

 {\tt \# stm < {\it stm}.fdf } 

\section{INPUT DATA FILE}
\label{cap:input} 

The input data file is written in an special format called FDF, developed
by Alberto Garc\'{\i}a and Jos\'e M. Soler (see {\sc 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 
{\sc Denchar} input files,
with their data types and default values.

\vspace{5pt}
\subsection{General descriptors}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf SystemLabel}] ({\it string}): 
A {\bf single} word (max. 20 characters {\bf without blanks})
containing a nickname of the system, used to name output files. 
{\bf It must be the same that you use when you run {\sc Siesta}!!}

{\it Default value:} siesta

\item[{\bf STM.label}] ({\it string}): 
A {\bf single} word (max. 20 characters {\bf without blanks})
containing a special label for the STM run, to be pasted to the
SystemLabel when creating files.

{\it Default value:} blank

\item[{\bf NumberOfSpecies}] ({\it 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 {\sc Siesta} run.

{\it Default value:} There is no default. You must supply this variable.


\item[{\bf ChemicalSpeciesLabel}] ({\it data block}):
It specifies the different chemical species\index{species} that are present,
assigning them a number for further identification.
Use the same as you did in {\sc Siesta}.

{\it Use:} This block is mandatory.

{\it Default:} No default.
\end{description}


\vspace{5pt}
\subsection{Description of the 3D grid where the charge density is obtained.}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf STM.DensityUnits}] ({\it string}): 
Character string to specify the units of the charge density in output. 
These can be expressed in three forms:

\begin{itemize}
\item[-] Ele/Bohr**3      : Electrons/bohr**3
\item[-] Ele/Ang**3       : Electrons/angstrom**3
\item[-] Ele/UnitCell     : Electrons/Unit Cell 
\end{itemize}

{\it Default value:} Ele/bohr**3

\item[{\bf STM.NumberPointsX}] ({\it integer}):
 Number of subdivision of the grid in the direction of the 
 first lattice vector. Together
 with {\bf STM.NumberPointsY} and {\bf STM.NumberPointsZ}
 it will define the 
 number of points of the grid to plot the charge density.

{\it Default value:} 50

\item[{\bf STM.NumberPointsY}] ({\it integer}):
 Number of subdivision of the grid in the direction
 of the second lattice vector. Together
 with {\bf STM.NumberPointsX} and {\bf STM.NumberPointsZ}
 it will define the 
 number of points of the grid to plot the charge density.

{\it Default value:} 50

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

{\it Default value:} 50


\item[{\bf STM.MinZ}] ({\it real length}):
 Defines the minimum value of the z-component of the 3D grid.

{\it Default value:} None. Must be defined in input file. Must
be larger or equal to {\bf STM.RefZ} (see below).

\item[{\bf STM.MaxZ}] ({\it real length}):
 Defines the maximum value of the z-component of the 3D grid.

{\it Default value:} None. Must be defined in input file.

\item[{\bf STM.RefZ}] ({\it real length}):
 Defines the z-component position of the reference plane from
 where the wavefunctions will be extraolated into vacuum.

{\it Default value:} None. Must be defined in input file.

\item[{\bf STM.VacZ}] ({\it real length}):
 Defines the z-component position of the plane on which the
 cero of the Hartree potential in the vacuum region is taken.
 This should be a position at the center of the vacuum of the slab.

{\it Default value:} None. Must be defined in input file.

\item[{\bf STM.NumberCellsX}] ({\it integer}):
Defines how many times the unit cell is repeated
in the direction of the first lattice vector,
in the Gaussian cube format plot file.

{\it Default value:} 1

\item[{\bf STM.NumberCellsY}] ({\it integer}):
Defines how many times the unit cell is repeated
in the direction of the second lattice vector,
in the Gaussian cube format plot file.

{\it Default value:} 1

\end{description}

\vspace{5pt}
\subsection{Description of the energy window for the STM image.}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf STM.Emin}] ({\it real energy}): 
Lower value of the energy window.

{\it Default value:} -1.0 eV

\item[{\bf STM.Emax}] ({\it real energy}): 
Upper value of the energy window.

{\it Default value:} 1.0 eV

\end{description}



\section{OUTPUT FILES}
\label{cap:output} 

{\sc STM} produces two output files, both of which contain 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.  These files contain the same information, but
with different formats.

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.STM.cube}]:
Value of the charge density at the grid defined by the user,
in Gaussian Cube format. Can be plotted using {\sc Vesta}, {\sc Molden}
or {\sc Molekel}.

\item[{\bf {\it SystemLabel}.STM.siesta}]:
Value of the charge density at the grid defined by the user,
in {\sc Siesta} grid format. Can be plotted using WSxM (for this it
has to be renamed so that its extension is {\tt .LDOS} or {\tt .RHO}).

\end{description}



\section{EXAMPLES}

In directory {\tt $\sim$/siesta/Util/STM/ol-stm/Examples} you will
find a complete example for an H-terminated Si(001) surface.

\end{document}
