%macroave.tex
%
%   Javier Junquera  Feb  05, 2005
%
%   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.2.1} }

\vspace{3cm}

{\Large {\it November 18, 2003} }

\vspace{3cm}

{\Large Javier Junquera}

\vspace{5pt}

{\it Departamento de Ciencias de la Tierra y F\'{\i}sica de
     la Materia Condensada \\
     Universidad de Cantabria, Santander, E-39005, Spain}

\vspace{2pt}
{\bf javier.junquera@unican.es }


\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}

\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}

Everything is automated within the Siesta distribution. 
Just go to Macroave/Src and type 'make'. Optionally, compile
the 'permute' program if needed.

\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}.

 {\bf NOTE}: If you have chosen {\tt x} as the direction perpendicular to
 the slab, instead of {\tt z}, you need to run the {\tt Src/permute}
 program to permute the axes.

 Execute macroave

 {\tt \$ $\sim$/Macroave/Src/macroave } 

 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 sistem

      {\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 orthorrombic unit cells. 
    \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}
