mirror of https://github.com/abinit/abinit.git
433 lines
13 KiB
TeX
433 lines
13 KiB
TeX
%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}
|