U s e r’ s G u i d e
S I E S T A 3.0-rc2
July 5, 2010
Emilio Artacho
University of Cambridge
Jos´e Mar´ıa Cela
Barcelona Supercomputing Center
Julian D. Gale
Curtin University of Technology, Perth
Alberto Garc´ıa
Institut de Ci`encia de Materials, CSIC, Barcelona
Javier Junquera
Universidad de Cantabria, Santander
Richard M. Martin
University of Illinois at Urbana-Champaign
Pablo Ordej´on
Centre de Investigaci´o en Nanoci`encia
i Nanotecnologia, (CSIC-ICN), Barcelona
Daniel S´anchez-Portal Unidad de F´ısica de Materiales,
Centro Mixto CSIC-UPV/EHU, San Sebasti´an
Jos´e M. Soler
Universidad Aut´onoma de Madrid
http://www.uam.es/siesta
Copyright c Fundaci´on General Universidad Aut´onoma de Madrid: E.Artacho, J.D.Gale,
A.Garc´ıa, J.Junquera, P.Ordej´on, D.S´anchez-Portal and J.M.Soler, 1996-2010
Contents
1
1 INTRODUCTION
This Reference Manual contains descriptions of all the input, output and execution features
of Siesta, but is not really a tutorial introduction to the program. The development team
is planning a documentation overhaul that will address this shortcoming.
In the meantime,
interested users can find tutorial material prepared for Siesta schools and workshops at the
project’s web page http://www.uam.es/siesta
Siesta (Spanish Initiative for Electronic Simulations with Thousands of Atoms) is both a
method and its computer program implementation, to perform electronic structure calculations
and ab initio molecular dynamics simulations of molecules and solids. Its main characteristics
are:
• It uses the standard Kohn-Sham self-consistent density functional method in the local
density (LDA-LSD) or generalized gradient (GGA) approximations.
• It uses norm-conserving pseudopotentials in their fully nonlocal (Kleinman-Bylander)
form.
• It uses atomic orbitals as a basis set, allowing unlimited multiple-zeta and angular mo-
menta, polarization and off-site orbitals. The radial shape of every orbital is numerical
and any shape can be used and provided by the user, with the only condition that it
has to be of finite support, i.e., it has to be strictly zero beyond a user-provided distance
from the corresponding nucleus. Finite-support basis sets are the key for calculating the
Hamiltonian and overlap matrices in O(N ) operations.
• Projects the electron wavefunctions and density onto a real-space grid in order to calculate
the Hartree and exchange-correlation potentials and their matrix elements.
• Besides the standard Rayleigh-Ritz eigenstate method, it allows the use of localized linear
combinations of the occupied orbitals (valence-bond or Wannier-like functions), making
the computer time and memory scale linearly with the number of atoms. Simulations with
several hundred atoms are feasible with modest workstations.
• It is written in Fortran 95 and memory is allocated dynamically.
• It may be compiled for serial or parallel execution (under MPI).
It routinely provides:
• Total and partial energies.
• Atomic forces.
• Stress tensor.
• Electric dipole moment.
• Atomic, orbital and bond populations (Mulliken).
• Electron density.
2
And also (though not all options are compatible):
• Geometry relaxation, fixed or variable cell.
• Constant-temperature molecular dynamics (Nose thermostat).
• Variable cell dynamics (Parrinello-Rahman).
• Spin polarized calculations (collinear or not).
• k-sampling of the Brillouin zone.
• Local and orbital-projected density of states.
• COOP and COHP curves for chemical bonding analysis.
• Dielectric polarization.
• Vibrations (phonons).
• Band structure.
• Ballistic electron transport (through TranSiesta)
Starting from version 3.0, Siesta includes the TranSiesta module. TranSiesta provides the
ability to model open-boundary systems where ballistic electron transport is taking place. Using
TranSiesta one can compute electronic transport properties, such as the zero bias conductance
and the I-V characteristic, of a nanoscale system in contact with two electrodes at different
electrochemical potentials. The method is based on using non equilibrium Green’s functions
(NEGF), that are constructed using the density functional theory Hamiltonian obtained from a
given electron density. A new density is computed using the NEGF formalism, which closes the
DFT-NEGF self consistent cycle.
For more details on the formalism, see the main TranSiesta reference cited below. A section has
been added to this User’s Guide, that describes the necessary steps involved in doing transport
calculations, together with the currently implemented input options.
References:
• “Unconstrained minimization approach for electronic computations that scales linearly
with system size” P. Ordej´on, D. A. Drabold, M. P. Grumbach and R. M. Martin, Phys.
Rev. B 48, 14646 (1993); “Linear system-size methods for electronic-structure calcula-
tions” Phys. Rev. B 51 1456 (1995), and references therein.
Description of the order-N eigensolvers implemented in this code.
• “Self-consistent order-N density-functional calculations for very large systems” P. Ordej´on,
E. Artacho and J. M. Soler, Phys. Rev. B 53, 10441, (1996).
Description of a previous version of this methodology.
3
• “Density functional method for very large systems with LCAO basis sets” D. S´anchez-
Portal, P. Ordej´on, E. Artacho and J. M. Soler, Int. J. Quantum Chem., 65, 453 (1997).
Description of the present method and code.
• “Linear-scaling ab-initio calculations for large and complex systems” E. Artacho, D.
S´anchez-Portal, P. Ordej´on, A. Garc´ıa and J. M. Soler, Phys. Stat. Sol. (b) 215, 809
(1999).
Description of the numerical atomic orbitals (NAOs) most commonly used in the code,
and brief review of applications as of March 1999.
• “Numerical atomic orbitals for linear-scaling calculations” J. Junquera, O. Paz, D.
S´anchez-Portal, and E. Artacho, Phys. Rev. B 64, 235111, (2001).
Improved, soft-confined NAOs.
• “The Siesta method for ab initio order-N materials simulation” J. M. Soler, E. Artacho,
J.D. Gale, A. Garc´ıa, J. Junquera, P. Ordej´on, and D. S´anchez-Portal, J. Phys.: Condens.
Matter 14, 2745-2779 (2002)
Extensive description of the Siesta method.
• “Computing the properties of materials from first principles with Siesta”, D. S´anchez-
Portal, P. Ordej´on, and E. Canadell, Structure and Bonding 113, 103-170 (2004).
Extensive review of applications as of summer 2003.
• “Density-functional method for nonequilibrium electron transport”, Mads Brandbyge,
Jose-Luis Mozos, Pablo Ordej´on, Jeremy Taylor, and Kurt Stokbro, Phys. Rev. B 65,
165401 (2002).
Description of the TranSiesta method.
For more information you can visit the web page http://www.uam.es/siesta.
2 COMPILATION
2.1 The building directory
Rather than using the top-level Src directory as building directory, the user has to use an ad-
hoc building directory (by default the top-level Obj directory, but it can be any (new) directory
in the top level). The building directory will hold the object files, module files, and libraries
resulting from the compilation of the sources in Src. The VPATH mechanism of modern make
programs is used. This scheme has many advantages. Among them:
• The Src directory is kept pristine.
• Many different object directories can be used concurrently to compile the program with
different compilers or optimization levels.
4
If you just want to compile the program, go to Obj and issue the command:
sh ../Src/obj_setup.sh
to populate this directory with the minimal scaffolding of makefiles, and then make sure that
you create or generate an appropriate arch.make file (see below, in Sect. ??). Then, type
make
The executable should work for any job. (This is not exactly true, since some of the parameters
in the atomic routines are still hardwired (see Src/atmparams.f), but those would seldom need
to be changed.)
To compile utility programs (those living in Util), you can just simply use the provided make-
files, typing “make” as appropriate.
2.1.1 Multiple-target compilation
The mechanism described here can be repeated in other directories at the same level as Obj,
In this way one can compile as many different versions of the Siesta
with different names.
executable as needed (for example, with different levels of optimization, serial, parallel, debug,
etc), by working in separate building directories.
Simply provide the appropriate arch.make, and issue the setup command above. To compile
utility programs, you need to use the form:
make OBJDIR=ObjName
where ObjName is the name of the object directory of your choice. Be sure to type make clean
before attempting to re-compile a utility program.
(The pristine Src directory should be kept ”clean”, without objects, or else the compilation in
the build directories will get confused)
2.2 The arch.make file
The compilation of the program is done using a Makefile that is provided with the code. This
Makefile will generate the executable for any of several architectures, with a minimum of tuning
required from the user and encapsulated in a separate file called arch.make.
You are strongly encouraged to look at Src/Sys/DOCUMENTED-TEMPLATE.make for information
about the fine points of the arch.make file. You can also get inspiration by looking at the actual
arch.make examples in the Src/Sys subdirectory. If you intend to create a parallel version of
Siesta, make sure you have all the extra support libraries (MPI, scalapack, blacs... (see
Sect. ??).
One important compilation option is -DGRID DP, which tells the compiler to use double pre-
cision arithmetic in grid-related arrays. Unless you find memory problems running siesta, we
5
If you use
strongly recommend it, and we will likely make it the default in future versions.
GRID DP, please note that it is advantageous to enable also PHI GRID SP, since the array
that stores orbital values on the grid can safely be kept in single precision, with significant
savings in memory and negligible numerical changes.
Optionally, the command ../Src/configure will start an automatic scan of your system and
try to build an arch.make for you. Please note that the configure script might need some help in
order to find your Fortran compiler, and that the created arch.make may not be optimal, mostly
in regard to compiler switches and preprocessor definitions, but the process should provide a
reasonable first version. Type ../Src/configure --help to see the flags understood by the
script, and take a look at the Src/Confs subdirectory for some examples of their explicit use.
3 EXECUTION OF THE PROGRAM
A fast way to test your installation of Siesta and get a feeling for the workings of the program
is implemented in directory Tests. In it you can find several subdirectories with pre-packaged
FDF files and pseudopotential references. Everything is automated: after compiling Siesta you
can just go into any subdirectory and type make. The program does its work in subdirectory
work, and there you can find all the resulting files. For convenience, the output file is copied to
the parent directory. A collection of reference output files can be found in Tests/Reference.
Please note that small numerical and formatting differences are to be expected, depending on
the compiler.
(For non-standard execution environments, including queuing systems, so can
have a look at the Scripts in Tests/Scripts, and see also Sect. ??.)
Other examples are provided in the Examples directory. This directory contains basically .fdf
files and the appropriate pseudopotential generation input files. Since at some point you will have
to generate your own pseudopotentials and run your own jobs, we describe here the whole process
by means of the simple example of the water-molecule. It is advisable to create independent
directories for each job, so that everything is clean and neat, and out of the siesta directory,
so that one can easily update version by replacing the whole siesta tree. Go to your favorite
working directory and:
$ mkdir h2o
$ cd h2o
$ cp path-to-package/Examples/H2O/h2o.fdf .
You need to make the siesta executable visible in your path. You can do it in many ways, but
a simple one is
ln -s path-to-package/Obj/siesta .
We need to generate the required pseudopotentials. (We are going to streamline this process for
this time, but you must realize that this is a tricky business that you must master before using
Siesta responsibly. Every pseudopotential must be thoroughly checked before use. Please refer
to the ATOM program manual in Pseudo/atom/Docs for details regarding what follows.)
$ cd path-to-package/Pseudo/atom
$ make
6
$ cd Tutorial/PS Generation/O
$ cat O.tm2.inp
This is the input file, for the oxygen pseudopotential, that we have prepared for you. It is in a
standard (but ancient and obscure) format that you will need to understand in the future:
------------------------------------------------------------
pg
Oxygen
tm2 2.0
n=O
1
2
2
3
4
c=ca
0.0
4
0
1
2
3
0.0
0.0
0.0
0.0
0.0
2.00
4.00
0.00
0.00
0.00
0.00
0.00
0.00
1.15
1.15
1.15
1.15
------------------------------------------------------------
To generate the pseudopotential do the following;
$ sh ../../Utils/pg.sh O.tm2.inp
Now there should be a new subdirectory called O.tm2 (O for oxygen) and O.tm2.vps (binary)
and O.tm2.psf (ASCII) files.
$ cp O.tm2.psf path-to-working-dir/h2o/O.psf
copies the generated pseudopotential file to your working directory.
(The unformatted and
ASCII files are functionally equivalent, but the latter is more transportable and easier to look
at, if you so desire.) The same could be repeated for the pseudopotential for H, but you may as
well copy H.psf from Examples/Vps/ to your h2o working directory.
Now you are ready to run the program:
./siesta < h2o.fdf | tee h2o.out
(If you are running the parallel version you should use some other invocation, such as mpirun
-np 2 siesta ..., but we cannot go into that here — see Sect. ??).
After a successful run of the program, you should have several files in your directory including
the following:
• fdf.log (contains all the data used, explicit or chosen by default)
• O.ion and H.ion (complete information about the basis and KB projectors)
• h2o.XV (contains positions and velocities)
• h2o.STRUCT OUT (contains the final cell vectors and positions in “crystallographic”
format)
• h2o.DM (contains the density matrix to allow a restart)
7