Macroave User Guide


November 18, 2003

Javier Junquera

Departamento de Ciencias de la Tierra y Fı́sica de la Materia Condensada Universidad de Cantabria, Santander, E-39005, Spain

Pablo Ordejón

Institut de Ciència de Materials de Barcelona - CSIC, Campus de la U.A.B., 08193 Bellaterra, Barcelona, Spain


The Macroave program implements the macroscopic average technique, introduced by A. Baldereschi and coworkers (A. Baldereschi, S. Baroni, and R. Resta, Phys. Rev. Lett. 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:

  • Band offsets and Work functions:
    L. Colombo, R. Resta and S. Baroni, Phys Rev B 44, 5572 (1991)
  • Effective charges:
    R. Martin and K. Kunc, Phys Rev B 24, 2081 (1981)
  • High-frequency dielectric constants:
    F. Bernardini and V. Fiorentini, Phys. Rev. B 58, 15292 (1998)

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:

  • 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).
    \[\overline{f} \left( z \right) = \frac{1}{S} \int_{S} f \left( \vec{r} \right) dx dy \label{eq:planar}\]

    where \(S\) is the surface of the unit cell perpendicular to the given direction.

  • Second: a final convolution of \(\overline{f} \left( z \right)\) with filter functions. We choose step functions, \(\Theta\), of length \(l\).

    \[\omega_{l} \left( z \right) = \frac{1}{l} \Theta\left( \frac{l}{2} - |z| \right) \label{eq:step}\]
    \[\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}\]

Currently, Macroave can handle directly the microscopic information provided by Siesta and Abinit, but it should be easily adapted to any other first-principle code.

Coded by J. Junquera and P. Ordejón, April 1999

Adapted for Abinit by J. Junquera, October 2002

This is a short description of the compilation procedures and of the datafile format for the Macroave code. This version is a very preliminary release of the code. Please report problems, bugs and suggestions to


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

Running the program

As was mentionned in the introduction (Section  1), 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 enables writing the corresponding magnitude to an output file. At the current time, Macroave is able to digest directly the output files supplied by Siesta and Abinit. The relevant input variables in these first-principles codes are:

  • Siesta

    • SaveRho

    • SaveDeltaRho

    • SaveElectrostaticPotential

    • SaveTotalPotential

    • SaveIonicCharge

    • SaveTotalCharge

    • LocalDensityOfStates

  • Abinit

    • prtpot

    • prtvha

    • prtvhxc

    • prtvxc

    • prtden

We refer the reader to the User’s Guide of Siesta or 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 \sim/rundir)

cd \sim/rundir

Edit the macroave’s input file (called and set up the right values for the different variables. This file will be fully explained in section  4.

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

Execute macroave

$ \sim/Macroave/Src/macroave

The output is dumped in files which will be described in Section  5.

Input data file

Apart from the information taken from the electronic-simulation code, Macroave requires only an input data file, named

This input file has eight lines:

first line

(string): Name of the first-principles code used to generate the microscopic magnitude, \(f \left( \vec{r} \right)\). It currently accepts only two options:

  • Siesta

  • Abinit

second line

(string): Microscopic magnitude whose macroscopic average will be calculated:

  • Potential

  • Charge

third line

(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 Siesta, only the SystemLabel is required (see Siesta User’s Guide).

fourth line

(integer): Number of convolutions with step functions required to perform the macroscopic average. It can take only two different values:

  • 1 (for surface-related problems).

  • 2 (for interface-related problems).

fifth line

(real): Length of the first step function used to perform the macroscopic average (see Eq.  [eq:step])

Units: bohrs

sixth line

(real): Length of the second step function used to perform the macroscopic average (see Eq.  [eq:step])

Units: bohrs

Use: Only use if the number of convolutions is equal to 2.

seventh line

(integer): Electronic charge of the system.

Units: electrons

Use: Only used if we are computing the macroscopic average of charge densities.

eigth line

(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:

  • Spline

  • Linear

Output files

Two output files are produced, containing the information about the planar (see Eq.  [eq:planar]) and the macroscopic average (see Eq.  [eq:macro]) of \(f \left( \vec{r} \right)\).

They contain, in two colums, the 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:


for the planar average.


  • electrons/bohr\(^3\) if \(f \left( \vec{r} \right)\) is a charge density.

  • eV if \(f \left( \vec{r} \right)\) is a potential.


for the macroscopic average.


  • electrons/bohr\(^3\) if \(f \left( \vec{r} \right)\) is a charge density.

  • eV if \(f \left( \vec{r} \right)\) is a potential.


In the directory \sim/Macroave/Examples you will find some examples of input files.

Known bugs and errors

  • The code only works for orthorrombic unit cells.

  • Spin polarization has not been implemented yet. The planar average, and the corresponding macroscopic average, are only implemented for the first component of RHO.