%macroave.tex % % Javier Junquera Jun 07, 2003 % % Manual for the Macroave program %\documentstyle[twocolumn,prb,aps]{revtex} %\documentstyle[prb,aps]{revtex} \documentstyle[11pt]{article} %\documentstyle{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 MACROAVE 1.1.0} } \vspace{3cm} {\Large {\it June 07, 2003} } \vspace{3cm} {\Large Javier Junquera} \vspace{5pt} {\it D\'epartement de Physique, Universit\'e de Li\`ege, B\^atiment B-5, B-4000 Sart-Tilman, Belgium} \vspace{7mm} {\Large Pablo Ordej\'on} \vspace{5pt} {\it Institut de Ci\`encia de Materials de Barcelona - CSIC, Campus de la U.A.B., 08193 Bellaterra, Barcelona, Spain} \vspace{3cm} {\bf javier.junquera@ulg.ac.be} \end{center} \end{titlepage} % END TITLE PAGE -------------------------------------------------------------- \tableofcontents \newpage \section{Introduction} \label{sec:intro} The {\sc Macroave} program implements the {\it macroscopic average technique}, introduced by A. Baldereschi and coworkers (A. Baldereschi, S. Baroni, and R. Resta, Phys. Rev. Lett. {\bf 61}, 734 (1988) ). This is an extremely powerful method that relates microscopic quantities, typical outputs of first-principles codes, with macroscopic magnitudes, needed to perform electrostatic analysis. Within this methodology, we will be able of washing out all the wiggles of the rapidly-varying functions of position (resembling the underlying atomic structure) of the microscopic quantities, blowing up only the macroscopic features. It is a basic tool to calculate some important magnitudes in surface or interface-related problems, such as: \begin{itemize} \item Band offsets and Work functions: \\ L. Colombo, R. Resta and S. Baroni, Phys Rev B {\bf 44}, 5572 (1991) \item Effective charges: \\ R. Martin and K. Kunc, Phys Rev B {\bf 24}, 2081 (1981) \item High-frequency dielectric constants: \\ F. Bernardini and V. Fiorentini, Phys. Rev. B {\bf 58}, 15292 (1998) \end{itemize} {\sc Macroave} reads the magnitude, $f \left( \vec{r} \right)$, whose macroscopic average will be calculated (typically, charge densities or potentials) at the points of a three-dimensional uniform real space grid, as it is dumped into output files by standard first-principle codes. Then it performs the macroscopic average in a two step process: \begin{itemize} \item First: a planar average of $f \left( \vec{r} \right)$ on planes parallel to the interface. \\ (To establish the notation, we will call the plane parallel to the surface or the interface the $(x,y)$ plane, whereas the perpendicular direction will be referred to as the $z$ axis). \begin{equation} \overline{f} \left( z \right) = \frac{1}{S} \int_{S} f \left( \vec{r} \right) dx dy \label{eq:planar} \end{equation} \noindent where $S$ is the surface of the unit cell perpendicular to the given direction. \item Second: a final convolution of $\overline{f} \left( z \right)$ with filter functions. We choose step functions, $\Theta$, of length $l$. \begin{equation} \omega_{l} \left( z \right) = \frac{1}{l} \Theta\left( \frac{l}{2} - |z| \right) \label{eq:step} \end{equation} \begin{equation} \overline{ \overline{f}} \left( z \right) = \int dz' \int dz'' \omega_{l_{1}} \left( z-z' \right) \omega_{l_{2}} \left( z'-z'' \right) \overline{f} \left( z'' \right) \label{eq:macro} \end{equation} \end{itemize} Currently, {\sc Macroave} can handle directly the microscopic information provided by {\sc Siesta} and {\sc Abinit}, but it should be easily adapted to any other first-principle code. Coded by J. Junquera and P. Ordej\'on, April 1999 Adapted for {\sc Abinit} by J. Junquera, October 2002 This is a short description of the compilation procedures and of the datafile format for the {\sc Macroave} code. This version is a very preliminary release of the code. Please report problems, bugs and suggestions to javier.junquera@ulg.ac.be \section{Compilation} \noindent In this section we give all the steps required to install the program. We assume that you use UNIX and you will install {\sc Macroave} in $\sim$/Macroave/Src, where $\sim$ indicates your home directory. The commands you must type are in {\tt typewriter} font, and {\tt \$} indicates the prompt. Uncompress and unpack the gzipped tar file macroave.tar.gz {\tt \$ gunzip macroave.tar.gz} {\tt \$ tar -xvf macroave.tar} Now, we suppose you have a fortran-90 compiler and you want to compile the source files, included in the directory {\tt Macroave/Src}. Go into this subdirectory {\tt \$ cd Macroave/Src} The compilation of the program is done using a Makefile that is provided with the code. This Makefile will generate the executable file in several architectures, with a minimum of tuning required from the user. The only variables you must set up (included in a file called arch.make) are: \begin{itemize} \item FC : location of the fortran-90 compiler. \item FFLAGS : flags to optimize the compilation in your platform. \end{itemize} Edit the arch.make file and set up the options that suit your platform. Then, you just need to run the `make' utility as usual, typing make in the source directory: {\tt \$ make} Since {\sc Macroave} is written in fortran-90 and the memory is allocated dynamically, the executable file, called macroave, should work for any job. \section{Running the program} As it was mentionned in the introduction (Section ~\ref{sec:intro}), {\sc Macroave} needs as input the microscopic magnitude, $f \left( \vec{r} \right)$, whose macroscopic average we want to calculate. $f \left( \vec{r} \right)$ will be, typically, a charge density or a given potential (electrostatic, exchange-correlation only, total,...). This information, that will be supplied by a first-principles electronic-simulation code, is usually stored at the points of a three-dimensional real-space grid. Obviously, the first thing we must do is to run the electronic-simulation program for the system we are interested in, setting up the variables that instruct to write the corresponding magnitude. At the current time, {\sc Macroave} is able to digest directly the output files supplied by {\sc Siesta} and {\sc Abinit}. The relevant input variables {\it in these first-principles codes} are: \begin{itemize} \item {\sc Siesta} \begin{itemize} \item SaveRho \item SaveDeltaRho \item SaveElectrostaticPotential \item SaveTotalPotential \item SaveIonicCharge \item SaveTotalCharge \item LocalDensityOfStates \end{itemize} \item {\sc Abinit} \begin{itemize} \item prtpot \item prtvha \item prtvhxc \item prtvxc \item prtden \end{itemize} \end{itemize} We refer the reader to the User's Guide of {\sc Siesta} or {\sc Abinit} to learn more about these different options. Once the simulation is finished, and the relevant output files written, then move to the directory where the job was run (let's call it {\tt $\sim$/rundir}) {\tt cd $\sim$/rundir} Edit the {\sc macroave}'s input file (called {\it macroave.in}) and set up the right values for the different variables. This file will be fully explained in section ~\ref{section:input}. Execute macroave.x {\tt \$ $\sim$/Macroave/Src/macroave.x } The output is dumped in files which will be described in Section ~\ref{section:output}. \section{Input data file} \label{section:input} Apart from the information taken from the electronic-simulation code, {\sc Macroave} requires only an input data file, named {\it macroave.in}. This input file has eigth lines: \begin{description} \itemsep 10pt \parsep 0pt \item[{\bf first line}] ({\it string}): Name of the first-principles code used to generate the microscopic magnitude, $f \left( \vec{r} \right)$. At present, it only accepts two options: \begin{itemize} \item Siesta \item Abinit \end{itemize} \item[{\bf second line}] ({\it string}): Microscopic magnitude whose macroscopic average will be calculated: \begin{itemize} \item Potential \item Charge \end{itemize} \item[{\bf third line}] ({\it string}): Name of the file (output of the first-principles code) where the magnitude $f \left( \vec{r} \right)$ is stored. In the case of {\sc Siesta}, only the {\bf SystemLabel} is required (see {\sc Siesta} User's Guide). \item[{\bf fourth line}] ({\it integer}): Number of convolutions with step functions required to perform the macroscopic average. It can take only two different values: \begin{itemize} \item 1 (for surface-related problems). \item 2 (for interface-related problems). \end{itemize} \item[{\bf fifth line}] ({\it real}): Length of the first step function used to perform the macroscopic average (see Eq. ~\ref{eq:step}) {\it Units:} bohrs \item[{\bf sixth line}] ({\it real}): Length of the second step function used to perform the macroscopic average (see Eq. ~\ref{eq:step}) {\it Units:} bohrs {\it Use:} Only use if the number of convolutions is equal to 2. \item[{\bf seventh line}] ({\it integer}): Electronic charge of the system {\it Units:} electrons {\it Use:} Only use if we are computing the macroscopic average of charge densities. \item[{\bf eigth line}] ({\it string}): Kind of interpolation to get $f \left( \vec{r} \right)$ at a fine FFT grid, starting from the grid used in the first-principles code. At the current time, it only accepts two different values \begin{itemize} \item Spline \item Linear \end{itemize} \end{description} %\vspace{5pt} %\subsection{\bf {\it SystemLabel}.ION} %This file contains information about the nuclei: their positions and %charges. % %The first line is the number of atoms you have in the system. % %Then you must have as much as lines as the number of atoms. Each line has %two numbers: the first one must be the z coordinate of the atom (we %suppose that the normal to the interface is the z-axis), and then %the charge of the nuclei. This charge is not the atomic number but the %difference of the atomic number and the core electrons. For example, for %Si it is 4. \section{Output files} \label{section:output} %Several output files are produced, with quantities related %with the averages of the charge densities and the electrostatic potentials %produced by them. %Each file is defined in the following paragraph. Two output files are produced, containing the information about the planar (see Eq. ~\ref{eq:planar}) and the macroscopic average (see Eq. ~\ref{eq:macro}) of $f \left( \vec{r} \right)$. Contains, in two colums, values of $z$ and the profile of the planar or macroscopic average. The name of these output files is the same as the one introduced in the third line of the input, plus an extension: \begin{description} \itemsep 10pt \parsep 0pt \item[.PAV] for the planar average. {\it Units:} \begin{itemize} \item electrons/bohr$^3$ if $f \left( \vec{r} \right)$ is a charge density. \item eV if $f \left( \vec{r} \right)$ is a potential. density. \end{itemize} \item[.MAV] for the macroscopic average. {\it Units:} \begin{itemize} \item electrons/bohr$^3$ if $f \left( \vec{r} \right)$ is a charge density. \item eV if $f \left( \vec{r} \right)$ is a potential. density. \end{itemize} \end{description} \section{Examples} In directory {\tt $\sim$/Macroave/Examples} you will find some examples of input files. \section{Known bugs and errors} \begin{itemize} \item The code only works for unit cells with a third axis which is perpendicular to the first two. \item Spin polarization not implemented yet. The planar average, and the corresponding macroscopic average are only implemented for the first component of array RHO. \end{itemize} \end{document}