U s e r’ s Guide

SIESTA 4.1-b4

November 07, 2018

http://www.uam.es/siesta

SIESTA Steering Committee:

Emilio Artacho CIC-Nanogune and University of Cambridge
José María Cela Barcelona Supercomputing Center
Julian D. Gale Curtin University of Technology, Perth
Alberto García Institut de Ciència de Materials, CSIC, Barcelona
Javier Junquera Universidad de Cantabria, Santander
Richard M. Martin University of Illinois at Urbana-Champaign
Pablo Ordejón Centre de Investigació en Nanociència
i Nanotecnologia, (CSIC-ICN), Barcelona
Nick Rübner Papior Technical University of Denmark
Daniel Sánchez-Portal Unidad de Física de Materiales,
Centro Mixto CSIC-UPV/EHU, San Sebastián
José M. Soler Universidad Autónoma de Madrid

SIESTA is Copyright © 1996-2018 by The Siesta Group

2
Contributors to SIESTA Contents

The SIESTA project was initiated by Pablo Ordejon (then at the Univ. Contributors to SIESTA 1
de Oviedo), and Jose M. Soler and Emilio Artacho (Univ. Autonoma de
Madrid, UAM). The development team was then joined by Alberto Garcia 1 INTRODUCTION 4
(then at Univ. del Pais Vasco, Bilbao), Daniel Sanchez-Portal (UAM),
and Javier Junquera (Univ. de Oviedo and later UAM), and sometime 2 COMPILATION 6
later by Julian Gale (then at Imperial College, London). In 2007 Jose M.
Cela (Barcelona Supercomputing Center, BSC) became a core developer 2.1 The build directory . . . . . . . . . . . . . . . . . . . . . . 6
and member of the Steering Committee. 2.1.1 Multiple-target compilation . . . . . . . . . . . . . 7
The original TranSIESTA module was developed by Pablo Ordejon and 2.2 The arch.make file . . . . . . . . . . . . . . . . . . . . . . 7
Jose L. Mozos (then at ICMAB-CSIC), and Mads Brandbyge, Kurt Stok-
2.3 Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
bro, and Jeremy Taylor (Technical Univ. of Denmark).
2.3.1 MPI . . . . . . . . . . . . . . . . . . . . . . . . . . 7
The current TranSIESTA module within SIESTA is developed by Nick
R. Papior and Mads Brandbyge. Nick R. Papior became a core developer 2.3.2 OpenMP . . . . . . . . . . . . . . . . . . . . . . . 7
and member of the Steering Committee in 2015. 2.4 Library dependencies . . . . . . . . . . . . . . . . . . . . . 8
Other contributors (we apologize for any omissions):
Eduardo Anglada, Thomas Archer, Luis C. Balbas, Xavier Blase, Ramon 3 EXECUTION OF THE PROGRAM 11
Cuadrado, Michele Ceriotti, Fabiano Corsetti, Raul de la Cruz, Gabriel 3.1 Specific execution options . . . . . . . . . . . . . . . . . . 12
Fabricius, Marivi Fernandez-Serra, Jaime Ferrer, Chu-Chun Fu, Sandra
Garcia, Victor M. Garcia-Suarez, Rogeli Grima, Rainer Hoft, Georg Huhs, 4 THE FLEXIBLE DATA FORMAT (FDF) 13
Jorge Kohanoff, Richard Korytar, In-Ho Lee, Lin Lin, Nicolas Lorente,
Miquel Llunell, Eduardo Machado, Maider Machado, Jose Luis Mar- 5 PROGRAM OUTPUT 14
tins, Volodymyr Maslyuk, Juana Moreno, Frederico Dutilh Novaes, Mi-
cael Oliveira, Magnus Paulsson, Oscar Paz, Andrei Postnikov, Tristana 5.1 Standard output . . . . . . . . . . . . . . . . . . . . . . . 14
Sondon, Andrew Walker, Andrew Walkingshaw, Toby White, Francois 5.2 Output to dedicated files . . . . . . . . . . . . . . . . . . . 14
Willaime, Chao Yang.
O.F. Sankey, D.J. Niklewski and D.A. Drabold made the FIREBALL code 6 DETAILED DESCRIPTION OF PROGRAM OPTIONS 14
available to P. Ordejon. Although we no longer use the routines in that 6.1 General system descriptors . . . . . . . . . . . . . . . . . 15
code, it was essential in the initial development of SIESTA, which still
uses many of the algorithms developed by them. 6.2 Pseudopotentials . . . . . . . . . . . . . . . . . . . . . . . 16
6.3 Basis set and KB projectors . . . . . . . . . . . . . . . . . 16
6.3.1 Overview of atomic-orbital bases implemented in
SIESTA . . . . . . . . . . . . . . . . . . . . . . . . 16
6.3.2 Type of basis sets . . . . . . . . . . . . . . . . . . 19

1
 6.3.3 Size of the basis set . . . . . . . . . . . . . . . . . 19 6.9.3 Mixing of the Charge Density . . . . . . . . . . . . 42
6.3.4 Range of the orbitals . . . . . . . . . . . . . . . . . 20 6.9.4 Initialization of the density-matrix . . . . . . . . . 43
6.3.5 Generation of multiple-zeta orbitals . . . . . . . . 20 6.9.5 Initialization of the SCF cycle with charge densities 45
6.3.6 Soft-confinement options . . . . . . . . . . . . . . . 21 6.9.6 Output of density matrix and Hamiltonian . . . . 45
6.3.7 Kleinman-Bylander projectors . . . . . . . . . . . . 21 6.9.7 Convergence criteria . . . . . . . . . . . . . . . . . 47
6.3.8 The PAO.Basis block . . . . . . . . . . . . . . . . 22 6.10 The real-space grid and the eggbox-effect . . . . . . . . . 48
6.3.9 Filtering . . . . . . . . . . . . . . . . . . . . . . . . 24 6.11 Matrix elements of the Hamiltonian and overlap . . . . . 50
6.3.10 Saving and reading basis-set information . . . . . . 25 6.11.1 The auxiliary supercell . . . . . . . . . . . . . . . . 51
6.3.11 Tools to inspect the orbitals and KB projectors . . 25 6.12 Calculation of the electronic structure . . . . . . . . . . . 51
6.3.12 Basis optimization . . . . . . . . . . . . . . . . . . 25 6.12.1 Diagonalization options . . . . . . . . . . . . . . . 52
6.3.13 Low-level options regarding the radial grid . . . . 26 6.12.2 Output of eigenvalues and wavefunctions . . . . . 55
6.4 Structural information . . . . . . . . . . . . . . . . . . . . 26 6.12.3 Occupation of electronic states and Fermi level . . 55
6.4.1 Traditional structure input in the fdf file . . . . . . 27 6.12.4 Orbital minimization method (OMM) . . . . . . . 56
6.4.2 Z-matrix format and constraints . . . . . . . . . . 28 6.12.5 Order(N) calculations . . . . . . . . . . . . . . . . 57
6.4.3 Output of structural information . . . . . . . . . . 30 6.13 The PEXSI solver . . . . . . . . . . . . . . . . . . . . . . 59
6.4.4 Input of structural information from external files 32 6.13.1 Pole handling . . . . . . . . . . . . . . . . . . . . . 59
6.4.5 Input from a FIFO file . . . . . . . . . . . . . . . . 32 6.13.2 Parallel environment and control options . . . . . 59
6.4.6 Precedence issues in structural input . . . . . . . . 32 6.13.3 Electron tolerance and the PEXSI solver . . . . . . 60
6.4.7 Interatomic distances . . . . . . . . . . . . . . . . 32 6.13.4 Inertia-counting . . . . . . . . . . . . . . . . . . . 61
6.5 k-point sampling . . . . . . . . . . . . . . . . . . . . . . . 33 6.13.5 Re-use of µ information accross iterations . . . . . 62
6.5.1 Output of k-point information . . . . . . . . . . . 34 6.13.6 Calculation of the density of states by inertia-counting 63
6.6 Exchange-correlation functionals . . . . . . . . . . . . . . 34 6.13.7 Calculation of the LDOS by selected-inversion . . 63
6.7 Spin polarization . . . . . . . . . . . . . . . . . . . . . . . 35 6.14 Band-structure analysis . . . . . . . . . . . . . . . . . . . 63
6.8 Spin–Orbit coupling . . . . . . . . . . . . . . . . . . . . . 36 6.14.1 Format of the .bands file . . . . . . . . . . . . . . . 64
6.9 The self-consistent-field loop . . . . . . . . . . . . . . . . . 37 6.14.2 Output of wavefunctions associated to bands . . . 65
6.9.1 Harris functional . . . . . . . . . . . . . . . . . . . 38 6.15 Output of selected wavefunctions . . . . . . . . . . . . . . 65
6.9.2 Mixing options . . . . . . . . . . . . . . . . . . . . 38 6.16 Densities of states . . . . . . . . . . . . . . . . . . . . . . 66

2
 6.16.1 Total density of states . . . . . . . . . . . . . . . . 66 7.2.3 FIRE relaxation . . . . . . . . . . . . . . . . . . . 83
6.16.2 Partial (projected) density of states . . . . . . . . 66 7.3 Target stress options . . . . . . . . . . . . . . . . . . . . . 84
6.16.3 Local density of states . . . . . . . . . . . . . . . . 67 7.4 Molecular dynamics . . . . . . . . . . . . . . . . . . . . . 84
6.17 Options for chemical analysis . . . . . . . . . . . . . . . . 67 7.5 Output options for dynamics . . . . . . . . . . . . . . . . 85
6.17.1 Mulliken charges and overlap populations . . . . . 67 7.6 Restarting geometry optimizations and MD runs . . . . . 86
6.17.2 Voronoi and Hirshfeld atomic population analysis . 67 7.7 Use of general constraints . . . . . . . . . . . . . . . . . . 86
6.17.3 Crystal-Orbital overlap and hamilton populations 7.8 Phonon calculations . . . . . . . . . . . . . . . . . . . . . 88
(COOP/COHP) . . . . . . . . . . . . . . . . . . . 68
6.18 Optical properties . . . . . . . . . . . . . . . . . . . . . . 69 8 LDA+U 89
6.19 Macroscopic polarization . . . . . . . . . . . . . . . . . . . 69
9 External control of SIESTA 90
6.20 Maximally Localized Wannier Functions . . . . . . . . . . 71
9.1 Examples of Lua programs . . . . . . . . . . . . . . . . . 92
6.21 Systems with net charge or dipole, and electric fields . . . 72
9.2 External MD/relaxation methods . . . . . . . . . . . . . . 92
6.22 Output of charge densities and potentials on the grid . . . 75
6.23 Auxiliary Force field . . . . . . . . . . . . . . . . . . . . . 77 10 TRANSIESTA 93
6.24 Parallel options . . . . . . . . . . . . . . . . . . . . . . . . 77 10.1 Source code structure . . . . . . . . . . . . . . . . . . . . 93
6.24.1 Parallel decompositions for O(N) . . . . . . . . . . 78 10.2 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.25 Efficiency options . . . . . . . . . . . . . . . . . . . . . . . 78 10.3 Brief description . . . . . . . . . . . . . . . . . . . . . . . 93
6.26 Memory, CPU-time, and Wall time accounting options . . 78 10.4 Electrodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.27 The catch-all option UseSaveData . . . . . . . . . . . . . 79 10.4.1 Matching coordinates . . . . . . . . . . . . . . . . 95
6.28 Output of information for Denchar . . . . . . . . . . . . . 79 10.4.2 Principal layer interactions . . . . . . . . . . . . . 96
6.29 NetCDF (CDF4) output file . . . . . . . . . . . . . . . . . 80 10.5 TranSIESTA Options . . . . . . . . . . . . . . . . . . . 96
10.5.1 Quick and dirty . . . . . . . . . . . . . . . . . . . . 96
7 STRUCTURAL RELAXATION, PHONONS, AND
MOLECULAR DYNAMICS 80 10.5.2 General options . . . . . . . . . . . . . . . . . . . . 97

7.1 Compatibility with pre-v4 versions . . . . . . . . . . . . . 81 10.5.3 Algorithm specific options . . . . . . . . . . . . . . 99

7.2 Structural relaxation . . . . . . . . . . . . . . . . . . . . . 82 10.5.4 Poisson solution for fixed boundary conditions . . 101

7.2.1 Conjugate-gradients optimization . . . . . . . . . . 83 10.5.5 Electrode description options . . . . . . . . . . . . 102

7.2.2 Broyden optimization . . . . . . . . . . . . . . . . 83 10.5.6 Chemical potentials . . . . . . . . . . . . . . . . . 104

10.5.7 Complex contour integration options . . . . . . . . 105

3
 10.5.8 Bias contour integration options . . . . . . . . . . 107 1 INTRODUCTION
10.6 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
This Reference Manual contains descriptions of all the input, output and
10.7 Utilities for analysis: TBtrans . . . . . . . . . . . . . . . 108
execution features of SIESTA, but is not really a tutorial introduction
to the program. Interested users can find tutorial material prepared for
11 ANALYSIS TOOLS 108 SIESTA schools and workshops at the project’s web page http://www.
uam.es/siesta.
12 SCRIPTING 108
NOTE: See the description of changes in the logic of the SCF
loop
13 PROBLEM HANDLING 108
SIESTA (Spanish Initiative for Electronic Simulations with Thousands
13.1 Error and warning messages . . . . . . . . . . . . . . . . . 108 of Atoms) is both a method and its computer program implementation, to
perform electronic structure calculations and ab initio molecular dynamics
14 REPORTING BUGS 109 simulations of molecules and solids. Its main characteristics are:

15 ACKNOWLEDGMENTS 109 • It uses the standard Kohn-Sham selfconsistent density functional

method in the local density (LDA-LSD) and generalized gradient
16 APPENDIX: Physical unit names recognized by FDF 110 (GGA) approximations, as well as in a non local functional that
includes van der Waals interactions (VDW-DF).
17 APPENDIX: XML Output 111 • It uses norm-conserving pseudopotentials in their fully nonlocal
17.1 Controlling XML output . . . . . . . . . . . . . . . . . . . 111 (Kleinman-Bylander) form.
17.2 Converting XML to XHTML . . . . . . . . . . . . . . . . 111 • It uses atomic orbitals as a basis set, allowing unlimited multiple-
zeta and angular momenta, polarization and off-site orbitals. The
18 APPENDIX: Selection of precision for storage 112 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
19 APPENDIX: Data structures and reference counting 113 finite support, i.e., it has to be strictly zero beyond a user-provided
distance from the corresponding nucleus. Finite-support basis sets
Bibliography 114 are the key for calculating the Hamiltonian and overlap matrices in
O(N ) operations.
Index 116 • Projects the electron wavefunctions and density onto a real-space
grid in order to calculate the Hartree and exchange-correlation po-
tentials 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

4
 memory scale linearly with the number of atoms. Simulations with • Ballistic electron transport under non-equilibrium (through Tran-
several hundred atoms are feasible with modest workstations. SIESTA)

• It is written in Fortran 95 and memory is allocated dynamically. Starting from version 3.0, SIESTA includes the TranSIESTA mod-
• It may be compiled for serial or parallel execution (under MPI). ule. TranSIESTA provides the ability to model open-boundary systems
where ballistic electron transport is taking place. Using TranSIESTA
It routinely provides: one can compute electronic transport properties, such as the zero bias
conductance and the I-V characteristic, of a nanoscale system in contact
• Total and partial energies. with two electrodes at different electrochemical potentials. The method is
based on using non equilibrium Greens functions (NEGF), that are con-
• Atomic forces. structed using the density functional theory Hamiltonian obtained from
a given electron density. A new density is computed using the NEGF
• Stress tensor. formalism, which closes the DFT-NEGF self consistent cycle.
• Electric dipole moment. Starting from version 4.1, TranSIESTA is an intrinsic part of the
SIESTA code. I.e. a separate executable is not necessary anymore. See
• Atomic, orbital and bond populations (Mulliken). Sec. 10 for details.
• Electron density. 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
And also (though not all options are compatible): the necessary steps involved in doing transport calculations, together with
the currently implemented input options.
• Geometry relaxation, fixed or variable cell.

• Constant-temperature molecular dynamics (Nose thermostat). References:

• Variable cell dynamics (Parrinello-Rahman). • “Unconstrained minimization approach for electronic computations
• Spin polarized calculations (colinear or not). that scales linearly with system size” P. Ordejón, D. A. Drabold, M.
P. Grumbach and R. M. Martin, Phys. Rev. B 48, 14646 (1993);
• k-sampling of the Brillouin zone. “Linear system-size methods for electronic-structure calculations”
Phys. Rev. B 51 1456 (1995), and references therein.
• Local and orbital-projected density of states.
Description of the order-N eigensolvers implemented in this code.
• COOP and COHP curves for chemical bonding analysis.
• “Self-consistent order-N density-functional calculations for very
• Dielectric polarization. large systems” P. Ordejón, E. Artacho and J. M. Soler, Phys. Rev.
B 53, 10441, (1996).
• Vibrations (phonons).
Description of a previous version of this methodology.
• Band structure.
• “Density functional method for very large systems with LCAO basis

5
 sets” D. Sánchez-Portal, P. Ordejón, E. Artacho and J. M. Soler, Int. For more information you can visit the web page http://www.uam.es/
J. Quantum Chem., 65, 453 (1997). siesta.
Description of the present method and code.

• “Linear-scaling ab-initio calculations for large and complex systems” 2 COMPILATION

E. Artacho, D. Sánchez-Portal, P. Ordejón, A. García and J. M.
Soler, Phys. Stat. Sol. (b) 215, 809 (1999). 2.1 The build directory
Description of the numerical atomic orbitals (NAOs) most com-
monly used in the code, and brief review of applications as of March Rather than using the top-level Src directory as building directory, the
1999. 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 build-
• “Numerical atomic orbitals for linear-scaling calculations” J. Jun- ing directory will hold the object files, module files, and libraries resulting
quera, O. Paz, D. Sánchez-Portal, and E. Artacho, Phys. Rev. B from the compilation of the sources in Src. The VPATH mechanism of mod-
64, 235111, (2001). ern make programs is used. This scheme has many advantages. Among
Improved, soft-confined NAOs. them:

• “The SIESTA method for ab initio order-N materials simulation” J. • The Src directory is kept pristine.
M. Soler, E. Artacho, J.D. Gale, A. García, J. Junquera, P. Ordejón,
and D. Sánchez-Portal, J. Phys.: Condens. Matter 14, 2745-2779 • Many different object directories can be used concurrently to com-
(2002) pile the program with different compilers or optimization levels.
Extensive description of the SIESTA method.
If you just want to compile the program, go to Obj and issue the command:
• “Computing the properties of materials from first principles with
SIESTA”, D. Sánchez-Portal, P. Ordejón, and E. Canadell, Struc- sh ../Src/obj_setup.sh
ture and Bonding 113, 103-170 (2004).
Extensive review of applications as of summer 2003. to populate this directory with the minimal scaffolding of makefiles, and
then make sure that you create or generate an appropriate arch.make file
• “Improvements on non-equilibrium and transport Green function (see below, in Sec. 2.2). Then, type
techniques: The next-generation TranSIESTA”, Nick Papior, Nico-
las Lorente, Thomas Frederiksen, Alberto GarcÃŋa and Mads make
Brandbyge, Computer Physics Communications, 212, 8–24 (2017).
Description of the TranSIESTA method. 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
• “Density-functional method for nonequilibrium electron transport”, Src/atmparams.f), but those would seldom need to be changed.)
Mads Brandbyge, Jose-Luis Mozos, Pablo Ordejón, Jeremy Taylor,
To compile utility programs (those living in Util), you can just simply
and Kurt Stokbro, Phys. Rev. B 65, 165401 (2002).
use the provided makefiles, typing “make” as appropriate.
Description of the original TranSIESTA method (prior to 4.1).

6
2.1.1 Multiple-target compilation with moderate number of cores. If one requires eXa-scale parallelism
SIESTA provides hybrid parallelism using both MPI and OpenMP.
The mechanism described here can be repeated in other directories at the
same level as Obj, with different names. In this way one can compile as
2.3.1 MPI
many different versions of the SIESTA executable as needed (for exam-
ple, with different levels of optimization, serial, parallel, debug, etc), by
MPI is a message-passing interface which enables communication between
working in separate building directories.
equivalently executed binaries. This library will thus duplicate all non-
Simply provide the appropriate arch.make, and issue the setup command distributed data such as local variables etc.
above. To compile utility programs, you need to use the form:
To enable MPI in SIESTA the compilation options are required to be
make OBJDIR=ObjName changed accordingly, here is the most basic changes to the arch.make for
standard binary names
where ObjName is the name of the object directory of your choice. Be sure
CC = mpicc
to type make clean before attempting to re-compile a utility program.
FC = mpifort # or mpif90
(The pristine Src directory should be kept “clean”, without objects, or MPI_INTERFACE = libmpi_f90.a
else the compilation in the build directories will get confused) MPI_INCLUDE = .
FPPFLAGS += -DMPI

2.2 The arch.make file Subsequently one may run SIESTA using the mpirun/mpiexec com-
mands:
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 mpirun -np <> siesta RUN.fdf
several architectures, with a minimum of tuning required from the user
and encapsulated in a separate file called arch.make. where <> is the number of cores used.
You are strongly encouraged to look at Obj/DOCUMENTED-TEMPLATE.make
for information about the fine points of the arch.make file. There are two 2.3.2 OpenMP
sample make files for compilation of SIESTA with gfortran and ifort
named Obj/gfortran.make and Obj/intel.make, respectively. Please OpenMP is shared memory parallelism. It typically does not infer any
use those as guidelines for creating the final arch.make. memory overhead and may be used if memory is scarce and the regular
Note that Intel compilers default to high optimizations which tends to MPI compilation is crashing due to insufficient memory.
break SIESTA. We advice to use -fp-model source flag and not compile To enable OpenMP, simply add this to your arch.make
with higher optimizations than -O2.
# For GNU compiler
FFLAGS += -fopenmp
2.3 Parallel LIBS += -fopenmp
# or, for Intel compiler < 16
To achieve a parallel build of SIESTA one should first determine which FFLAGS += -openmp
type of parallelism one requires. It is advised to use MPI for calculations LIBS += -openmp

7
 # or, for Intel compiler >= 16 -x OMP_NUM_THREADS=2 \
FFLAGS += -qopenmp -x OMP_PROC_BIND=true siesta RUN.fdf
LIBS += -qopenmp
If using only 1 thread per MPI core it is advised to compile SIESTA
The above will yield the most basic parallelism using OpenMP. However, without OpenMP. As such it may be advantageous to compile SIESTA
the BLAS/LAPACK libraries which is the most time-consuming part of in 3 variants; OpenMP-only (small systems), MPI-only (medium to large
SIESTA also requires to be threaded, please see Sec. 2.4 for correct link- systems) and MPI+OpenMP (large> systems).
ing.
The variable OMP_PROC_BIND may heavily influence the performance of
Subsequently one may run SIESTA using OpenMP through the en- the executable! Please perform tests for the architecture used.
vironment variable OMP_NUM_THREADS which determine the number of
threads/cores used in the execution.
2.4 Library dependencies
OMP_NUM_THREADS=<> siesta RUN.fdf
# or (bash) SIESTA makes use of several libraries. Here we list a set of libraries and
export OMP_NUM_THREADS=<> how each of them may be added to the compilation step (arch.make).
siesta RUN.fdf SIESTA is distributed with scripts that install the most useful libraries.
# or (csh)
These installation scripts may be located in the Docs/ folder with names:
setenv OMP_NUM_THREADS <>
siesta RUN.fdf install_*.bash. Currently SIESTA is shipped with these installation
scripts:
where <> is the number of threads/cores used.
• install_netcdf4.bash; installs NetCDF with full CDF4 support.
If SIESTA is also compiled using MPI it is more difficult to obtain a Thus it installs zlib, hdf5 and NetCDF C and Fortran.
good performance. Please refer to your local cluster how to correctly call
MPI with hybrid parallelism. An example for running SIESTA with good • install_flook.bash; installs flook which enables interaction with
performance using OpenMPI > 1.8.2 and OpenMP on a machine with 2 Lua and SIESTA.
sockets and 8 cores per socket, one may do:
Note that these scripts are guidance scripts and users are encouraged
# MPI = 2 cores, OpenMP = 8 threads per core (total=16) to check the mailing list for or seek help there in non-standard. The
mpirun --map-by ppr:1:socket:pe=8 \ installation scripts finishes by telling what to add to the arch.make file
-x OMP_NUM_THREADS=8 \ to correctly link the just installed libraries.
-x OMP_PROC_BIND=true siesta RUN.fdf

# MPI = 4 cores, OpenMP = 4 threads per core (total=16) BLAS it is recommended to use a high-performance library (OpenBLAS
mpirun --map-by ppr:2:socket:pe=4 \ or MKL library from Intel)
-x OMP_NUM_THREADS=4 \
-x OMP_PROC_BIND=true siesta RUN.fdf • If you use your *nix distribution package manager to install
BLAS you are bound to have a poor performance. Please try
# MPI = 8 cores, OpenMP = 2 threads per core (total=16)
and use performance libraries, whenever possible!
mpirun --map-by ppr:4:socket:pe=2 \

8
 • If you do not have the BLAS library you may use the # OpenBLAS (OpenBLAS will default to build in LAPACK 3.6)
BLAS library shipped with SIESTA. To do so simply add LIBS += -L/opt/openblas/lib -lopenblasp
libsiestaBLAS.a to the COMP_LIBS variable. # or for MKL
LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_lapack95_lp64
To add BLAS to the arch.make file you need to add the required -lmkl_<>_thread ...
linker flags to the LIBS variable in the arch.make file. where <> is the compiler used (intel or gnu).
Example variables
ScaLAPACK Only required for MPI compilation.
# OpenBLAS:
Here one may be sufficient to rely on the NetLIB2 version of ScaLA-
LIBS += -L/opt/openblas/lib -lopenblas
# or for MKL PACK.
LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_blas95_lp64 ... Example variables

To use the threaded (OpenMP) libraries, change the above linking # ScaLAPACK
to LIBS += -L/opt/scalapack/lib -lscalapack
# or for MKL
# OpenBLAS: LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_scalapack_lp64
LIBS += -L/opt/openblas/lib -lopenblasp -lmkl_blacs_<>_lp64 ...
# or for MKL
LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_blas95_lp64 where <> refers to the MPI version used, (intelmpi, openmpi,
-lmkl_<>_thread ... sgimpt).
where <> is the compiler used (intel or gnu).
Additionally SIESTA may be compiled with support for several other
LAPACK it is recommended to use a high-performance library (Open- libraries
BLAS1 or MKL library from Intel)
If you do not have the LAPACK library you may use the fdict This library is shipped with SIESTA and its linking may be enabled
LAPACK library shipped with SIESTA. To do so simply add by
libsiestaLAPACK.a to the COMP_LIBS variable. COMP_LIBS += libfdict.a
Example variables
NetCDF It is adviced to compile NetCDF in CDF4 compliant mode
# OpenBLAS (OpenBLAS will default to build in LAPACK 3.6) (thus also linking with HDF5) as this enables more advanced IO. If
LIBS += -L/opt/openblas/lib -lopenblas you only link against a CDF3 compliant library you will not get the
# or for MKL complete feature set of SIESTA.
LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_lapack95_lp64 ...
3 If the CDF3 compliant library is present one may add this to your
To use the threaded (OpenMP) libraries, change the above linking
arch.make:
to
LIBS += -L/opt/netcdf/lib -lnetcdff -lnetcdf
1
OpenBLAS enables the inclusion of the LAPACK routines. This is advised. FPPFLAGS += -DCDF
2
ScaLAPACKs performance is mainly governed by BLAS and LAPACK.

9
 4 If the CDF4 compliant library is present the HDF5 libraries are LIBS += -L/opt/mumps/lib -lzmumps -lmumps_common <>
also required at link time: FPPFLAGS += -DSIESTA__MUMPS
LIBS += -L/opt/netcdf/lib -lnetcdff -lnetcdf \
where <> are any libraries that MUMPS depend on.
-lhdf5_fortran -lhdf5 -lz
PEXSI The PEXSI library may be used with SIESTA for exa-scale
ncdf This library is shipped with SIESTA and its linking is required calculations, see Sec. 6.13. Currently the interface is implemented
to take advantage of the CDF4 library functionalities. To use this (tested) as in PEXSI version 0.8.0, 0.9.0 and 0.9.2. If newer versions
library, ensure that you can compile SIESTA with CDF4 support. retain the same interface they may also be used.
Then proceed by adding the following to your arch.make
To successfully compile SIESTA with PEXSI support one require
COMP_LIBS += libncdf.a libfdict.a the PEXSI fortran interface. When installing PEXSI copy the
FPPFLAGS += -DNCDF -DNCDF_4 f_interface.f90 file to the include directory of PEXSI such that
the module may be found3 when compiling SIESTA.
If the NetCDF library is compiled with parallel support one may
take advantage of parallel IO by adding this to the arch.make Add these flags to your arch.make file to enable PEXSI

FPPFLAGS += -DNCDF_PARALLEL INCFLAGS += -I/opt/pexsi/include

LIBS += -L/opt/pexsi/lib -lpexsi_linux <>
To easily install NetCDF please see the installation file: FPPFLAGS += -DSIESTA__PEXSI
Docs/install_netcdf4.bash.
where <> are any libraries that PEXSI depend on. If one experiences
Metis The Metis library may be used in the Order-N code. linker failures, one possible solution that may help is
Add these flags to your arch.make file to enable Metis LIBS += -lmpi_cxx -lstdc++
LIBS += -L/opt/metis/lib -lmetis which is due to PEXSI being a C++ library, and the Fortran com-
FPPFLAGS += -DSIESTA__METIS
piler is the linker. The exact library name for your MPI vendor may
vary.
ELPA The ELPA [1;7] library provides faster diagonalization routines.
Additionally the PEXSI linker step may have duplicate objects
The required version of ELPA must be 2017.05.003 or later. Add which can be circumvented by prefixing the PEXSI libraries with
these flags to your arch.make file to enable ELPA
LIBS += -Wl,--allow-multiple-definition -lpexsi_linux <>
LIBS += -L/opt/elpa/lib -lelpa <>
FPPFLAGS += -DSIESTA__ELPA -I/opt/elpa/include/elpa-<>/modules
flook SIESTA allows external control via the LUA scripting language.
Using this library one may do advanced MD simulations and much
where <> are any libraries that ELPA depend on.
more without changing any code in SIESTA.
NOTE: ELPA can only be used in the parallel version of SIESTA.
Add these flags to your arch.make file to enable flook
MUMPS The MUMPS library may currently be used with TranSI- 3
Optionally the file may be copied to the Obj directory where the compilation takes
ESTA. place.
Add these flags to your arch.make file to enable MUMPS

10
 LIBS += -L/opt/flook/lib -lflookall -ldl You need to make the siesta executable visible in your path. You can do
COMP_LIBS += libfdict.a it in many ways, but a simple one is
FPPFLAGS += -DSIESTA__FLOOK

See Tests/h2o_lua for an example on the LUA interface. $ ln -s path-to-package/Obj/siesta

To easily install flook please see the installation file:

Docs/install_flook.bash. 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.
3 EXECUTION OF THE PROGRAM Every pseudopotential must be thoroughly checked before use. Please
refer to the ATOM program manual for details regarding what follows.)
A fast way to test your installation of SIESTA and get a feeling for the NOTE: The ATOM program is no longer bundled with SIESTA, but
workings of the program is implemented in directory Tests. In it you can academic users can dowload it from the SIESTA webpage at www.icmab.
find several subdirectories with pre-packaged fdf files and pseudopoten- es/siesta.
tial references. Everything is automated: after compiling SIESTA you $ cd path/to/atom/package/
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. (Compile the program following the instructions)
For convenience, the output file is copied to the parent directory. A col- $ cd Tutorial/PS_Generation/O
lection of reference output files can be found in Tests/Reference. Please $ cat O.tm2.inp
note that small numerical and formatting differences are to be expected,
depending on the compiler. (For non-standard execution environments, This is the input file, for the oxygen pseudopotential, that we have pre-
including queuing systems, have a look at the Scripts in Tests/Scripts, pared for you. It is in a standard (but ancient and obscure) format that
and see also Sec. 2.3.) you will need to understand in the future:
Other examples are provided in the Examples directory. This directory
------------------------------------------------------------
contains basically .fdf files and the appropriate pseudopotential genera-
pg Oxygen
tion input files. Since at some point you will have to generate your own
tm2 2.0
pseudopotentials and run your own jobs, we describe here the whole pro-
n=O c=ca
cess by means of the simple example of the water-molecule. It is advisable
0.0 0.0 0.0 0.0 0.0 0.0
to create independent directories for each job, so that everything is clean
1 4
and neat, and out of the SIESTA directory, so that one can easily update
2 0 2.00 0.00
version by replacing the whole SIESTA tree. Go to your favorite working
2 1 4.00 0.00
directory and:
3 2 0.00 0.00
4 3 0.00 0.00
$ mkdir h2o 1.15 1.15 1.15 1.15
$ cd h2o
------------------------------------------------------------
$ cp path-to-package/Examples/H2O/h2o.fdf

To generate the pseudopotential do the following;

11
$ sh ../../Utils/pg.sh O.tm2.inp The prefix h2o of all these files is the SystemLabel specified in the input
Now there should be a new subdirectory called O.tm2 (O for oxygen) and h2o.fdf file (see fdf section below). The standard output of the program,
O.tm2.vps (binary) and O.tm2.psf (ASCII) files. that you have already seen passing on the screen, was copied to file h2o.out
by the tee command. Have a look at it and refer to the output-explanation
$ cp O.tm2.psf path-to-working-dir/h2o/O.psf section if necessary. You may also want to look at the fdf.log file to see
copies the generated pseudopotential file to your working directory. (The all the default values that siesta has chosen for you, before studying the
unformatted and ASCII files are functionally equivalent, but the latter input-explanation section and start changing them.
is more transportable and easier to look at, if you so desire.) The same Now look at the other data files in Examples (all with an .fdf suffix) choose
could be repeated for the pseudopotential for H, but you may as well copy one and repeat the process for it.
H.psf from Examples/Vps/ to your h2o working directory.
Now you are ready to run the program:
3.1 Specific execution options
./siesta < h2o.fdf | tee h2o.out
SIESTA may be executed in different forms. The basic execution form is
(If you are running the parallel version you should use some other invo-
cation, such as mpirun -np 2 siesta ..., but we cannot go into that
siesta < RUN.fdf > RUN.out
here — see Sec. 2.3).
After a successful run of the program, you should have several files in your which uses a pipe statement. Since 4.1 SIESTA does not require one to
directory including the following: pipe in the input file and the input file may instead be specified on the
command line.
• fdf.log (contains all the data used, explicit or chosen by default)
siesta RUN.fdf > RUN.out
• O.ion and H.ion (complete information about the basis and KB
projectors) This allows for SIESTA to accept special flags described in what follows.
• h2o.XV (contains positions and velocities) Each flag may be quoted if it contains spaces, or one may substitute spaces
by .
• h2o.STRUCT_OUT (contains the final cell vectors and positions in
“crystallographic” format) -h print a help instruction and quit
• h2o.DM (contains the density matrix to allow a restart) -L Override, temporarily, the SystemLabel flag.
siesta -L Hello.
• h2o.ANI (contains the coordinates of every MD step, in this case
only one) -out|-o Specify the output file (instead of printing to the terminal).
siesta -out RUN.out.
• h2o.FA (contains the forces on the atoms)
-electrode|-elec depends on: TS.HS.Save, TS.DE.Save
• h2o.EIG (contains the eigenvalues of the Kohn-Sham Hamiltonian) denote this as an electrode cal-
culation which forces the SystemLabel.TSHS and SystemLabel.TSDE
• h2o.xml (XML marked-up output) files to be saved.

12
-V depends on: TS.Voltage • You may ‘include’ other fdf files and redirect the search for a par-
specify the bias for the current TranSIESTA run. ticular data label to another file. If a data label appears more than
siesta -V 0.25:eV or siesta -V "0.25 eV" which sets the applied once, its first appearance is used.
bias to 0.25 eV. • If the same label is specified twice, the first one takes precedence.

• If a label is misspelled it will not be recognized (there is no internal

4 THE FLEXIBLE DATA FORMAT (FDF) list of “accepted” tags in the program). You can check the actual
value used by siesta by looking for the label in the output fdf.log
The main input file, which is read as the standard input (unit 5), contains file.
all the physical data of the system and the parameters of the simulation
to be performed. This file is written in a special format called FDF, These are some examples:
developed by Alberto García and José M. Soler. This format allows data
to be given in any order, or to be omitted in favor of default values. Refer
SystemName Water molecule # This is a comment
to documentation in ∼/siesta/Src/fdf for details. Here we offer a glimpse
SystemLabel h2o
of it through the following rules:
SpinPolarized yes
SaveRho
• The fdf syntax is a ’data label’ followed by its value. Values that NumberOfAtoms 64
are not specified in the datafile are assigned a default value. LatticeConstant 5.42 Ang
%block LatticeVectors
• fdf labels are case insensitive, and characters - _ . in a data label
1.000 0.000 0.000
are ignored. Thus, LatticeConstant and lattice_constant represent
0.000 1.000 0.000
the same label.
0.000 0.000 1.000
• All text following the # character is taken as comment. %endblock LatticeVectors
KgridCutoff < BZ_sampling.fdf
• Logical values can be specified as T, true, .true., yes, F, false, .false.,
no. Blank is also equivalent to true. # Reading the coordinates from a file
%block AtomicCoordinatesAndAtomicSpecies < coordinates.da
• Character strings should not be in apostrophes.

• Real values which represent a physical magnitude must be fol- # Even reading more FDF information from somewhere else
lowed by its units. Look at function fdf_convfac in file %include mydefaults.fdf
∼/siesta/Src/fdf/fdf.f for the units that are currently supported.
It is important to include a decimal point in a real number to dis- The file fdf.log contains all the parameters used by SIESTA in a given
tinguish it from an integer, in order to prevent ambiguities when run, both those specified in the input fdf file and those taken by default.
mixing the types on the same input line. They are written in fdf format, so that you may reuse them as input
directly. Input data blocks are copied to the fdf.log file only if you specify
• Complex data structures are called blocks and are placed between
the dump option for them.
‘%block label’ and a ‘%endblock label’ (without the quotes).

13
5 PROGRAM OUTPUT writes the information in other files (see Output Files) in addition to
the standard output, and these can be cumulative or not.
5.1 Standard output Setting LongOutput to true changes the default of some options,
obtaining more information in the output (verbose). In particular, it
SIESTA writes a log of its workings to standard output (unit 6), which redefines the defaults for the following:
is usually redirected to an “output file”.
• WriteKpoints
A brief description follows. See the example cases in the siesta/Tests
• WriteKbands
directory for illustration.
• WriteCoorStep
The program starts writing the version of the code which is used. Then,
the input fdf file is dumped into the output file as is (except for empty • WriteForces
lines). The program does part of the reading and digesting of the data • WriteEigenvalues
at the beginning within the redata subroutine. It prints some of the • WriteWaveFunctions
information it digests. It is important to note that it is only part of it,
• WriteMullikenPop(it sets it to 1)
some other information being accessed by the different subroutines when
they need it during the run (in the spirit of fdf input). A complete list The specific changing of any of these options has precedence.
of the input used by the code can be found at the end in the file fdf.log,
including defaults used by the code in the run.
5.2 Output to dedicated files
After that, the program reads the pseudopotentials, factorizes them into
Kleinman-Bylander form, and generates (or reads) the atomic basis set SIESTA can produce a wealth of information in dedicated files, with
to be used in the simulation. These stages are documented in the output specific formats, that can be used for further analysis. See the appropriate
file. sections, and the appendix on file formats. Please take into account the
The simulation begins after that, the output showing information of the behavior of LongOutput, as in the current implementation might silently
MD (or CG) steps and the SCF cycles within. Basic descriptions of the activate output to the main .out file at the expense of auxiliary files.
process and results are presented. The user has the option to customize it,
however, by defining different options that control the printing of informa-
tions like coordinates, forces, ~k points, etc. The options are discussed in 6 DETAILED DESCRIPTION OF PROGRAM
the appropriate sections, but take into account the behavior of the legacy OPTIONS
LongOutput option, as in the current implementation might silently
activate output to the main .out file at the expense of auxiliary files. Here follows a description of the variables that you can define in your
SIESTA input file, with their data types and default values. For historical
LongOutput false (logical)
reasons the names of the tags do not have an uniform structure, and can
SIESTA can write to standard output different data sets depending be confusing at times.
on the values for output options described below. By default SIESTA
will not write most of them. They can be large for large systems Almost all of the tags are optional: SIESTA will assign a default if a
(coordinates, eigenvalues, forces, etc.) and, if written to standard given tag is not found when needed (see fdf.log).
output, they accumulate for all the steps of the dynamics. SIESTA

14
6.1 General system descriptors For atomic numbers over 200 or below −200 you should read Syn-
theticAtoms.
SystemLabel siesta (string)
NOTE: This block is mandatory.
A single word (max. 20 characters without blanks) containing a nick-
name of the system, used to name output files. %block SyntheticAtoms 〈None〉 (block)
SystemName 〈None〉 (string) This block is an additional block to complement ChemicalSpecies-
Label for special atomic numbers.
A string of one or several words containing a descriptive name of the
system (max. 150 characters). Atomic numbers over 200 are used to represent synthetic atoms (cre-
ated for example as a “mixture” of two real ones for a “virtual
NumberOfSpecies 〈lines in ChemicalSpeciesLabel〉 (integer) crystal” (VCA) calculation). In this special case a new Synthet-
Number of different atomic species in the simulation. Atoms of the icAtoms block must be present to give SIESTA information about
same species, but with a different pseudopotential or basis set are the “ground state” of the synthetic atom.
counted as different species. %block ChemicalSpeciesLabel
NOTE: This is not required to be set. 1 201 ON-0.50000
%endblock ChemicalSpeciesLabel
NumberOfAtoms 〈lines in %block SyntheticAtoms
AtomicCoordinatesAndAtomicSpecies〉 (integer) 1 # Species index
Number of atoms in the simulation. 2 2 3 4 # n numbers for valence states with l=0,1
2.0 3.5 0.0 0.0 # occupations of valence states with l=0,1
NOTE: This is not required to be set. %endblock SyntheticAtoms
%block ChemicalSpeciesLabel 〈None〉 (block) Pseudopotentials for synthetic atoms can be created using the mixps
It specifies the different chemical species that are present, assigning and fractional programs in the Util/VCA directory.
them a number for further identification. SIESTA recognizes the Atomic numbers below −200 represent ghost synthetic atoms.
different atoms by the given atomic number.
%block AtomicMass 〈None〉 (block)
%block ChemicalSpecieslabel
1 6 C It allows the user to introduce the atomic masses of the different
2 14 Si species used in the calculation, useful for the dynamics with isotopes,
3 14 Si_surface for example. If a species index is not found within the block, the
%endblock ChemicalSpecieslabel natural mass for the corresponding atomic number is assumed. If
the block is absent all masses are the natural ones. One line per
The first number in a line is the species number, it is followed by
species with the species index (integer) and the desired mass (real).
the atomic number, and then by the desired label. This label will
The order is not important. If there is no integer and/or no real
be used to identify corresponding files, namely, pseudopotential file,
numbers within the line, the line is disregarded.
user basis file, basis output file, and local pseudopotential output file.
This construction allows you to have atoms of the same species but %block AtomicMass
3 21.5
with different basis or pseudopotential, for example.
1 3.2
Negative atomic numbers are used for ghost atoms (see PAO.Basis). %endblock AtomicMass

15
 The default atomic mass are the natural masses. For ghost atoms The user can feed into SIESTA the atomic basis set he/she choses by
(i.e. floating orbitals) the mass is 1030 a.u. means of radial tables (see User.Basis below), the only limitations being:
(i) the functions have to be atomic-like (radial functions mutiplied by
spherical harmonics), and (ii) they have to be of finite support, i.e., each
6.2 Pseudopotentials
orbital becomes strictly zero beyond some cutoff radius chosen by the
user.
SIESTA uses pseudopotentials to represent the electron-ion interac-
tion (as do most plane-wave codes and in contrast to so-called “all- Most users, however, do not have their own basis sets. For these users
electron” programs). In particular, the pseudopotentials are of the we have devised some schemes to generate basis sets within the program
“norm-conserving” kind, and can be generated by the Atom program, (see with a minimum input from the user. If nothing is specified in the input
Pseudo/README.ATOM). Remember that all pseudopotentials should file, Siesta generates a default basis set of a reasonable quality that might
be thoroughly tested before using them. We refer you to the standard constitute a good starting point. Of course, depending on the accuracy
literature on pseudopotentials and to the ATOM manual for more informa- required in the particular problem, the user has the degree of freedom to
tion. A number of other codes (such as APE) can generate pseudopotentials tune several parameters that can be important for quality and efficiency.
that SIESTA can use directly (typically in the .psf format). A description of these basis sets and some performance tests can be found
in the references quoted below.
The pseudopotentials will be read by SIESTA from different files, one for
each defined species (species defined either in block ChemicalSpecies- “Numerical atomic orbitals for linear-scaling calculations”, J. Junquera,
Label). The name of the files should be: O. Paz, D. Sánchez-Portal, and E. Artacho, Phys. Rev. B 64, 235111,
(2001)
Chemical_label.vps (unformatted) or Chemical_label.psf (ASCII)
An important point here is that the basis set selection is a variational
where Chemical_label corresponds to the label defined in the Chemical-
problem and, therefore, minimizing the energy with respect to any pa-
SpeciesLabel block.
rameters defining the basis is an “ab initio” way to define them.
We have also devised a quite simple and systematic way of generating
6.3 Basis set and KB projectors basis sets based on specifying only one main parameter (the energy shift)
besides the basis size. It does not offer the best NAO results one can
6.3.1 Overview of atomic-orbital bases implemented in
get for a given basis size but it has the important advantages mentioned
SIESTA
above. More about it in:
The main advantage of atomic orbitals is their efficiency (fewer orbitals “Linear-scaling ab-initio calculations for large and complex systems”, E.
needed per electron for similar precision) and their main disadvantage is Artacho, D. Sánchez-Portal, P. Ordejón, A. García and J. M. Soler, Phys.
the lack of systematics for optimal convergence, an issue that quantum Stat. Sol. (b) 215, 809 (1999).
chemists have been working on for many years. They have also clearly In addition to SIESTA we provide the program Gen-basis , which reads
shown that there is no limitation on precision intrinsic to LCAO. This SIESTA’s input and generates basis files for later use. Gen-basis can be
section provides some information about how basis sets can be generated found in Util/Gen-basis. It should be run from the Tutorials/Bases
for SIESTA. directory, using the gen-basis.sh script. It is limited to a single species.
It is important to stress at this point that neither the SIESTA method nor Of course, as it happens for the pseudopotential, it is the responsibility
the program are bound to the use of any particular kind of atomic orbitals. of the user to check that the physical results obtained are converged with

16
respect to the basis set used before starting any production run. We then proposed an extension of the split valence idea of Quantum
In the following we give some clues on the basics of the basis sets that Chemistry to strictly localized NAO which has become the standard and
SIESTA generates. The starting point is always the solution of Kohn- has been used quite successfully in many systems (see PAO.BasisType
Sham’s Hamiltonian for the isolated pseudo-atoms, solved in a radial grid, split below). It is based on the idea of suplementing the first ζ with,
with the same approximations as for the solid or molecule (the same instead of a gaussian, a numerical orbital that reproduces the tail of the
exchange-correlation functional and pseudopotential), plus some way of original PAO outside a matching radius rm , and continues smoothly to-
confinement (see below). We describe in the following three main features wards the origin as rl (a − br2 ), with a and b ensuring continuity and
of a basis set of atomic orbitals: size, range, and radial shape. differentiability at rm . Within exactly the same Hilbert space, the sec-
ond orbital can be chosen to be the difference between the smooth one
Size: number of orbitals per atom and the original PAO, which gives a basis orbital strictly confined within
Following the nomenclature of Quantum Chemistry, we establish a hierar- the matching radius rm (smaller than the original PAO!) continuously
chy of basis sets, from single-ζ to multiple-ζ with polarization and diffuse differentiable throughout.
orbitals, covering from quick calculations of low quality to high preci- Extra parameters have thus appeared: one rm per orbital to be doubled.
sion, as high as the finest obtained in Quantum Chemistry. A single-ζ The user can again introduce them by hand (see PAO.Basis below). Al-
(also called minimal) basis set (SZ in the following) has one single ra- ternatively, all the rm ’s can be defined at once by specifying the value of
dial function per angular momentum channel, and only for those angular the tail of the original PAO beyond rm , the so-called split norm. Vari-
momenta with substantial electronic population in the valence of the free ational optimization of this split norm performed on different systems
atom. It offers quick calculations and some insight on qualitative trends shows a very general and stable performance for values around 15% (ex-
in the chemical bonding and other properties. It remains too rigid, how- cept for the ∼ 50% for hydrogen). It generalizes to multiple-ζ trivially by
ever, for more quantitative calculations requiring both radial and angular adding an additional matching radius per new zeta.
flexibilization.
Note: What is actually used is the norm of the tail plus the norm of the
Starting by the radial flexibilization of SZ, a better basis is obtained by parabola-like inner function.
adding a second function per channel: double-ζ (DZ). In Quantum Chem-
istry, the split valence scheme is widely used: starting from the expansion Angular flexibility is obtained by adding shells of higher angular momen-
in Gaussians of one atomic orbital, the most contracted Gaussians are tum. Ways to generate these so-called polarization orbitals have been
used to define the first orbital of the double-ζ and the most extended described in the literature for Gaussians. For NAOs there are two ways
ones for the second. For strictly localized functions there was a first pro- for SIESTA and Gen-basis to generate them: (i) Use atomic PAO’s of
posal of using the excited states of the confined atoms, but it would work higher angular momentum with suitable confinement, and (ii) solve the
only for tight confinement (see PAO.BasisType nodes below). This con- pseudoatom in the presence of an electric field and obtain the l+1 orbitals
struction was proposed and tested in D. Sánchez-Portal et al., J. Phys.: from the perturbation of the l orbitals by the field.
Condens. Matter 8, 3859-3880 (1996). So-called diffuse orbitals, that might be important in the description of
We found that the basis set convergence is slow, requiring high levels of open systems such as surfaces, can be simply added by specifying extra
multiple-ζ to achieve what other schemes do at the double-ζ level. This “n” shells. [See S. Garcia-Gil, A. Garcia, N. Lorente, P. Ordejon, Phys.
scheme is related with the basis sets used in the OpenMX project [see T. Rev. B 79, 075441 (2009)]
Ozaki, Phys. Rev. B 67, 155108 (2003); T. Ozaki and H. Kino, Phys. Finally, the method allows the inclusion of off-site (ghost) orbitals (not
Rev. B 69, 195113 (2004)]. centered around any specific atom), useful for example in the calculation
of the counterpoise correction for basis-set superposition errors. Bessel

17
functions for any radius and any excitation level can also be added any- their extension being, besides problematic, of no practical use for the
where to the basis set. calculation in condensed systems: the electrons far away from the atom
Range: cutoff radii of orbitals. can be described by the basis functions of other atoms.

Strictly localized orbitals (zero beyond a cutoff radius) are used in order A traditional scheme to deal with this is one based on the radial scaling
to obtain sparse Hamiltonian and overlap matrices for linear scaling. One of the orbitals by suitable scale factors. In addition to very basic bonding
cutoff radius per angular momentum channel has to be given for each arguments, it is soundly based on restoring the virial’s theorem for finite
species. bases, in the case of Coulombic potentials (all-electron calculations). The
use of pseudopotentials limits its applicability, allowing only for extremely
A balanced and systematic starting point for defining all the different radii small deviations from unity (∼ 1%) in the scale factors obtained varia-
is achieved by giving one single parameter, the energy shift, i.e., the energy tionally (with the exception of hydrogen that can contract up to 25%).
increase experienced by the orbital when confined. Allowing for system This possiblity is available to the user.
and physical-quantity variablity, as a rule of thumb ∆EPAO ≈ 100 meV
gives typical precisions within the accuracy of current GGA functionals. Another way of dealing with the above problem and that of the kink
The user can, nevertheless, change the cutoff radii at will. at the same time is adding a soft confinement potential to the atomic
Hamiltonian used to generate the basis orbitals: it smoothens the kink and
Shape contracts the orbital as suited. Two additional parameters are introduced
Within the pseudopotential framework it is important to keep the con- for the purpose, which can be defined again variationally. The confining
sistency between the pseudopotential and the form of the pseudoatomic potential is flat (zero) in the core region, starts off at some internal radius
orbitals in the core region. The shape of the orbitals at larger radii de- ri with all derivatives continuous and diverges at rc ensuring the strict
pends on the cutoff radius (see above) and on the way the localization is localization there. It is
enforced. −
rc −ri
e r−ri
The first proposal (and quite a standard among SIESTA users) uses V (r) = Vo (1)
rc − r
an infinite square-well potential. It was originally proposed and has
been widely and successfully used by Otto Sankey and collaborators, and both ri and Vo can be given to SIESTA together with rc in the input
for minimal bases within the ab initio tight-binding scheme, using the (see PAO.Basis below). The kink is normally well smoothened with the
Fireball program, but also for more flexible bases using the methodology default values for soft confinement by default (PAO.SoftDefault true),
of SIESTA. This scheme has the disadavantage, however, of generating which are ri = 0.9rc and Vo = 40 Ry.
orbitals with a discontinuous derivative at rc . This discontinuity is more
When explicitly introducing orbitals in the basis that would be empty in
pronounced for smaller rc ’s and tends to disappear for long enough values
the atom (e.g. polarisation orbitals) these tend to be extremely extended
of this cutoff. It does remain, however, appreciable for sensible values of rc
if not completely unbound. The above procedure produces orbitals that
for those orbitals that would be very wide in the free atom. It is surprising
bulge as far away from the nucleus as possible, to plunge abruptly at rc .
how small an effect such a kink produces in the total energy of condensed
Soft confinement can be used to try to force a more reasonable shape,
systems. It is, on the other hand, a problem for forces and stresses, es-
but it is not ideal (for orbitals peaking in the right region the tails tend
pecially if they are calculated using a (coarse) finite three-dimensional
to be far too short). Charge confinement produces very good shapes for
grid.
empty orbitals. Essentially a Z/r potential is added to the soft confined
Another problem of this scheme is related to its defining the basis starting potential above. For flexibility the charge confinement option in SIESTA
from the free atoms. Free atoms can present extremely extended orbitals,

18
is defined as - Generalization of the PAO’s: uses the excited orbitals of the
Ze−λr finite-range pseudo-atomic problem, both for multiple-ζ and for
VQ (r) = √ (2)
r2 + δ 2 polarization [see Sánchez-Portal, Artacho, and Soler, JPCM 8,
where δ is there to avoid the singularity (default δ = 0.01 Bohr), and λ 3859 (1996)]. Adequate for short-range orbitals.
allows to screen the potential if longer tails are needed. The description - Multiple-ζ in the spirit of split valence, decomposing the orig-
on how to introduce this option can be found in the PAO.Basis entry inal PAO in several pieces of different range, either defining
below. more (and smaller) confining radii, or introducing Gaussians
Finally, the shape of an orbital is also changed by the ionic character of from known bases (Huzinaga’s book).
the atom. Orbitals in cations tend to shrink, and they swell in anions. All the remaining options give the same minimal basis. The different
Introducing a δQ in the basis-generating free-atom calculations gives or- options and their fdf descriptors are the following:
bitals better adapted to ionic situations in the condensed systems.
split Split-valence scheme for multiple-zeta. The split is based on
More information about basis sets can be found in the proposed literature. different radii.
2
There are quite a number of options for the input of the basis-set and KB splitgauss Same as split but using gaussian functions e−(x/αi ) . The
projector specification, and they are all optional! By default, SIESTA gaussian widths αi are read instead of the scale factors (see below).
will use a DZP basis set with appropriate choices for the determina- There is no cutting algorithm, so that a large enough rc should be
tion of the range, etc. Of course, the more you experiment with the defined for the gaussian to have decayed sufficiently.
different options, the better your basis set can get. To aid in this
nodes Generalized PAO’s.
process we offer an auxiliary program for optimization which can be
used in particular to obtain variationally optimal basis sets (within a nonodes The original PAO’s are used, multiple-zeta is generated by
chosen basis size). See Util/Optimizer for general information, and changing the scale-factors, instead of using the excited orbitals.
Util/Optimizer/Examples/Basis_Optim for an example. The directory filteret Use the filterets as a systematic basis set. The size of the
Tutorials/Bases in the main SIESTA distribution contains some tuto- basis set is controlled by the filter cut-off for the orbitals.
rial material for the generation of basis sets and KB projectors.
Note that, for the split and nodes cases the whole basis can be gen-
Finally, some optimized basis sets for particular elements are available at
erated by SIESTA with no further information required. SIESTA
the SIESTA web page. Again, it is the responsability of the users to test
will use default values as defined in the following (PAO.BasisSize,
the transferability of the basis set to their problem under consideration.
PAO.EnergyShift, and PAO.SplitNorm, see below).

6.3.2 Type of basis sets

6.3.3 Size of the basis set
PAO.BasisType split (string)
PAO.BasisSize DZP (string)
The kind of basis to be generated is chosen. All are based on finite-
It defines usual basis sizes. It has effect only if there is no block
range pseudo-atomic orbitals [PAO’s of Sankey and Niklewsky, PRB
PAO.Basis present.
40, 3979 (1989)]. The original PAO’s were described only for minimal
bases. SIESTA generates extended bases (multiple-ζ, polarization, SZ|minimal Use single-ζ basis.
and diffuse orbitals) applying different schemes of choice: DZ Double zeta basis, in the scheme defined by PAO.BasisType.

19
 SZP Single-zeta basis plus polarization orbitals. neato -x -Tpng siesta.ATOM.gv -o siesta_ATOM.png
DZP|standard Like DZ plus polarization orbitals. Polarization or- The resulting graph will list each atom as i(j) where i is the atomic
bitals are constructed from perturbation theory, and they are de- index and j is the number of other atoms it is connected to.
fined so they have the minimum angular momentum l such that
there are not occupied orbitals with the same l in the valence shell
6.3.5 Generation of multiple-zeta orbitals
of the ground-state atomic configuration. They polarize the corre-
sponding l − 1 shell. PAO.SplitNorm 0.15 (real)
NOTE: The ground-state atomic configuration used internally by A standard to define sensible default radii for the split-valence type
SIESTA is defined in the source file Src/periodic_table.f. For of basis. It gives the amount of norm that the second-ζ split-off piece
some elements (e.g., Pd), the configuration might not be the stan- has to carry. The split radius is defined accordingly. If multiple-ζ
dard one. is used, the corresponding radii are obtained by imposing smaller
fractions of the SplitNorm (1/2, 1/4 ...) value as norm carried by the
%block PAO.BasisSizes 〈None〉 (block) higher zetas. It only has an effect when the block PAO.Basis is not
Block which allows to specify a different value of the variable present or when the radii specified in that block are zero for zetas
PAO.BasisSize for each species. For example, higher than one.
%block PAO.BasisSizes
Si DZ PAO.SplitNormH 〈PAO.SplitNorm〉 (real)
H DZP This option is as per PAO.SplitNorm but allows a separate default
O SZP to be specified for hydrogen which typically needs larger values than
%endblock PAO.BasisSizes those for other elements.

PAO.NewSplitCode false (logical)

6.3.4 Range of the orbitals
Enables a new, simpler way to match the multiple-zeta radii.
PAO.EnergyShift 0.02 Ry (energy) If an old-style (tail+parabola) calculation is being done, perform a
A standard for orbital-confining cutoff radii. It is the excitation en- scan of the tail+parabola norm in the whole range of the 1st-zeta
ergy of the PAO’s due to the confinement to a finite-range. It offers orbital, and store that in a table. The construction of the 2nd-zeta
a general procedure for defining the confining radii of the original orbital involves simply scanning the table to find the appropriate
(first-zeta) PAO’s for all the species guaranteeing the compensation place. Due to the idiosyncracies of the old algorithm, the new one
of the basis. It only has an effect when the block PAO.Basis is not is not guaranteed to produce exactly the same results, as it might
present or when the radii specified in that block are zero for the first settle on a neighboring grid point for the matching.
zeta.
PAO.FixSplitTable false (logical)
Write.Graphviz none|atom|orbital|atom+orbital (string) After the scan of the allowable split-norm values, apply a damping
Write out the sparsity pattern after having determined the ba- function to the tail to make sure that the table goes to zero at the
sis size overlaps. This will generate SystemLabel.ATOM.gv or radius of the first-zeta orbital.
SystemLabel.ORB.gv which both may be converted to a graph using
Graphviz’s program neato: PAO.SplitTailNorm false (logical)

20
 Use the norm of the tail instead of the full tail+parabola norm. This If the multiple zetas are generated using filterets then any filterets
is the behavior described in the JPC paper. (But note that, for that have a coefficient less than this threshold within the original
numerical reasons, the square root of the tail norm is used in the PAO will be contracted together to form a single filteret. Increasing
algorithm.) This is the preferred mode of operation for automatic this value leads to a smaller basis set but allows the underlying basis
operation, as in non-supervised basis-optimization runs. to have a higher kinetic energy cut-off for filtering. It only has an
effect when the option PAO.BasisType is set to filteret.
As a summary of the above options:

• For complete backwards compatibility, do nothing. 6.3.6 Soft-confinement options

• To exercise the new code, set PAO.NewSplitCode. PAO.SoftDefault false (logical)

If set to true then this option causes soft confinement to be the default
• To maintain the old split-norm heuristic, but making sure form of potential during orbital generation. The default potential and
that the program finds a solution (even if not optimal, in inner radius are set by the commands given below.
the sense of producing a second-ζ rc very close to the first-
ζ one), set PAO.FixSplitTable (this will automatically set PAO.SoftInnerRadius 0.9 (real)
PAO.NewSplitCode). For default soft confinement, the inner radius is set at a fraction of
the outer confinement radius determined by the energy shift. This
• If the old heuristic is of no interest (for example, if only a option controls the fraction of the confinement radius to be used.
robust way of mapping split-norms to radii is needed), set
PAO.SplitTailNorm (this will set PAO.NewSplitCode auto- PAO.SoftPotential 40 Ry (energy)
matically). For default soft confinement, this option controls the value of the
potential used for all orbitals.
PAO.EnergyCutoff 20 Ry (energy)
NOTE: Soft-confinement options (inner radius, prefactor) have been
If the multiple zetas are generated using filterets then only the fil-
traditionally used to optimize the basis set, even though formally they
terets with an energy lower than this cutoff are included. Increasing
are just a technical necessity to soften the decay of the orbitals at rc.
this value leads to a richer basis set (provided the cutoff is raised
To achieve this, it might be enough to use the above global options.
above the energy of any filteret that was previously not included)
but a more expensive calculation. It only has an effect when the
option PAO.BasisType is set to filteret. 6.3.7 Kleinman-Bylander projectors

PAO.EnergyPolCutoff 20 Ry (energy) %block PS.lmax 〈None〉 (block)

If the multiple zetas are generated using filterets then only the fil- Block with the maximum angular momentum of the Kleinman-
terets with an energy lower than this cutoff are included for the po- Bylander projectors, lmxkb. This information is optional. If the
larisation functions. Increasing this value leads to a richer basis set block is absent, or for a species which is not mentioned inside it,
(provided the cutoff is raised above the energy of any filteret that was SIESTA will take lmxkb(is) = lmxo(is) + 1, where lmxo(is) is
previously not included) but a more expensive calculation. It only the maximum angular momentum of the basis orbitals of species is.
has an effect when the option PAO.BasisType is set to filteret. %block Ps.lmax
Al_adatom 3
PAO.ContractionCutoff 0|0 − 1 (real)

21
 H 1 From is = 1 to nspecies
O 2 read: label(is), l_shells(is)
%endblock Ps.lmax From lsh=1 to l_shells(is)
By default lmax is the maximum angular momentum plus one. read: l, nkbl(l,is)
read: {erefKB(izeta,il,is)}, from ikb = 1 to nkbl(l,is)
%block PS.KBprojectors 〈None〉 (block)
When a very high energy, higher that 1000 Ry, is specified, the default
This block provides information about the number of Kleinman- is taken instead. On the other hand, very low (negative) energies,
Bylander projectors per angular momentum, and for each species, lower than -1000 Ry, are used to indicate that the energy derivative
that will used in the calculation. This block is optional. If the block of the last state must be used. For example, in the example given
is absent, or for species not mentioned in it, only one projector will be above, two projectors will be used for the s pseudopotential of Si. One
used for each angular momentum. The projectors will be constructed generated using a reference energy of -0.5 Hartree, and the second one
using the eigenfunctions of the respective pseudopotentials. using the energy derivative of this state. For the p pseudopotential of
This block allows to specify the number of projector for each l, and Ga, three projectors will be used. The second one will be constructed
also the reference energies of the wavefunctions used to build them. from an automatically generated wavefunction with one node, and the
The specification of the reference energies is optional. If these en- other projectors from states at -1.0 and -6.0 Rydberg.
ergies are not given, the program will use the eigenfunctions with The analysis looking for possible ghost states is only performed when
an increasing number of nodes (if there is not bound state with the a single projector is used. Using several projectors some attention
corresponding number of nodes, the “eigenstates” are taken to be should be paid to the “KB cosine” (kbcos), given in the output of
just functions which are made zero at very long distance of the nu- the program. The KB cosine gives the value of the overlap between
cleus). The units for the energy can be optionally specified, if not, the reference state and the projector generated from it. If these
the program will assumed that are given in Rydbergs. The data pro- numbers are very small ( < 0.01, for example) for all the projectors
vided in this block must be consistent with those read from the block of some angular momentum, one can have problems related with the
PS.lmax. For example, presence of ghost states.
%block PS.KBprojectors The default is one KB projector from each angular momentum, con-
Si 3 structed from the nodeless eigenfunction.
2 1
-0.9 eV KB.New.Reference.Orbitals false (logical)
0 2 If true, the routine to generate KB projectors will use slightly differ-
-0.5 -1.0d4 Hartree ent parameters for the construction of the reference orbitals involved
1 2 (Rmax=60 Bohr both for integration and normalization).
Ga 1
1 3 6.3.8 The PAO.Basis block
-1.0 1.0d5 -6.0
%endblock PS.KBprojectors %block PAO.Basis 〈None〉 (block)
The reading is done this way (those variables in brackets are optional, Block with data to define explicitly the basis to be used. It al-
therefore they are only read if present): lows the definition by hand of all the parameters that are used
to construct the atomic basis. There is no need to enter infor-

22
mation for all the species present in the calculation. The basis And here is the variable description:
for the species not mentioned in this block will be generated auto-
- Label: Species label, this label determines the species index is
matically using the parameters PAO.BasisSize, PAO.BasisType,
according to the block ChemicalSpeciesLabel
PAO.EnergyShift, PAO.SplitNorm (or PAO.SplitNormH),
and the soft-confinement defaults, if used (see PAO.SoftDefault). - l_shells(is): Number of shells of orbitals with different an-
gular momentum for species is
Some parameters can be set to zero, or left out completely. In these
cases the values will be generated from the magnitudes defined above, - type(is): Optional input. Kind of basis set generation proce-
or from the appropriate default values. For example, the radii will dure for species is. Same options as PAO.BasisType
be obtained from PAO.EnergyShift or from PAO.SplitNorm if - ionic_charge(is): Optional input. Net charge of species is.
they are zero; the scale factors will be put to 1 if they are zero or not This is only used for basis set generation purposes. Default
given in the input. An example block for a two-species calculation value: 0.0 (neutral atom). Note that if the pseudopotential was
(H and O) is the following (opt means optional): generated in an ionic configuration, and no charge is specified
%block PAO.Basis # Define Basis set in PAO.Basis, the ionic charge setting will be that of pseudopo-
O 2 nodes 1.0 # Label, l_shells, type (opt), ionic_charge (opt)tential generation.
n=2 0 2 E 50.0 2.5 # n (opt if not using semicore levels),l,Nzeta,Softconf(opt)
- n: Principal quantum number of the shell. This is an optional
3.50 3.50 # rc(izeta=1,Nzeta)(Bohr) input for normal atoms, however it must be specified when there
0.95 1.00 # scaleFactor(izeta=1,Nzeta) (opt)
are semicore states (i.e. when states that usually are not con-
1 1 P 2 # l, Nzeta, PolOrb (opt), NzetaPol (opt)
3.50 # rc(izeta=1,Nzeta)(Bohr)
sidered to belong to the valence shell have been included in the
H 2 # Label, l_shells, type (opt), ionic_charge (opt)calculation)
0 2 S 0.2 # l, Nzeta, Per-shell split norm parameter - l: Angular momentum of basis orbitals of this shell
5.00 0.00 # rc(izeta=1,Nzeta)(Bohr)
- nzls(lsh,is): Number of “zetas” for this shell. For a filteret
1 1 Q 3. 0.2 # l, Nzeta, Charge conf (opt): Z and screening
5.00 # rc(izeta=1,Nzeta)(Bohr) basis this number is ignored since the number is controlled by
%endblock PAO.Basis the cutoff.
- PolOrb(l+1): Optional input. If set equal to P, a shell of po-
The reading is done this way (those variables in brackets are op-
larization functions (with angular momentum l + 1) will be con-
tional, therefore they are only read if present) (See the routines in
structed from the first-zeta orbital of angular momentum l. De-
Src/basis_specs.f for detailed information):
fault value: ’ ’ (blank = No polarization orbitals).
From js = 1 to nspecies
- NzetaPol(l+1): Optional input. Number of “zetas” for the po-
read: label(is), l_shells(is), { type(is) }, { ionic_charge(is) }
From lsh=1 to l_shells(is) larization shell (generated automatically in a split-valence fash-
read: ion). For a filteret basis this number is ignored since the number
{ n }, l(lsh), nzls(lsh,is), { PolOrb(l+1) }, { NzetaPol(l+1)is },
controlled by the cutoff. Only active if PolOrb = P. Default
{SplitNormfFlag(lsh,is)}, {SplitNormValue(lsh,is)} value: 1
{SoftConfFlag(lsh,is)}, {PrefactorSoft(lsh,is)}, {InnerRadSoft(lsh,is)},
- SplitNormFlag(lsh,is): Optional input. If set equal to S, the
{FilteretFlag(lsh,is)}, {FilteretCutoff(lsh,is)}
following number sets the split-norm parameter for that shell.
{ChargeConfFlag(lsh,is)}, {Z(lsh,is)}, {Screen(lsh,is)}, {delta(lsh,is}
read: rcls(izeta,lsh,is), from izeta = 1 to nzls(l,is) - SoftConfFlag(l,is): Optional input. If set equal to E, the soft
read: { contrf(izeta,il,is) }, from izeta = 1 to nzls(l,is)confinement potential proposed in equation (1) of the paper by

23
 J. Junquera et al., Phys. Rev. B 64, 235111 (2001), is used Note: The perturbative method has traditionally used the ’l’ com-
instead of the Sankey hard-well potential. ponent of the pseudopotential. It can be argued that it should use
- PrefactorSoft(l,is): Optional input. Prefactor of the soft the ’l+1’ component. By default, for backwards compatibility, the
confinement potential (V0 in the formula). Units in Ry. Default traditional method is used, but the alternative one can be activated
value: 0 Ry. by setting the logical PAO.OldStylePolOrbs variable to false.
- InnerRadSoft(l,is): Optional input. Inner radius where the There is a different possibility for generating polarization orbitals:
soft confinement potential starts off (ri in the formula). If neg- by introducing them explicitly in the PAO.Basis block. It has to be
ative, the inner radius will be computed as the given fraction of remembered, however, that they sometimes correspond to unbound
the PAO cutoff radius. Units in bohrs. Default value: 0 bohrs. states of the atom, their shape depending very much on the cutoff
radius, not converging by increasing it, similarly to the multiple-zeta
- FilteretFlag(l,is): Optional input. If set equal to F, then
orbitals generated with the nodes option. Using PAO.EnergyShift
an individual filter cut-off can be specified for the shell.
makes no sense, and a cut off radius different from zero must be
- FilteretCutoff(l,is): Optional input. Shell-specific value for explicitly given (the same cutoff radius as the orbitals they polarize
the filteret basis cutoff. Units in Ry. Default value: The same is usually a sensible choice).
as the value given by FilterCutoff . A species with atomic number = -100 will be considered by SIESTA
- ChargeConfFlag(lsh,is): Optional input. If set equal to Q, the as a constant-pseudopotential atom, i.e., the basis functions gener-
charge confinement potential in equation (2) above is added to ated will be spherical Bessel functions with the specified rc . In this
the confining potential. If present it requires at least one number case, rc has to be given, as EnergyShift will not calculate it.
after it (Z), but it can be followed by two or three numbers. Other negative atomic numbers will be interpreted by SIESTA as
- Z(lhs,is): Optional input, needed if Q is set. Z charge in ghosts of the corresponding positive value: the orbitals are generated
equation (2) above for charge confinement (units of e). and put in position as determined by the coordinates, but neither
- Screen(lhs,is): Optional input. Yukawa screening parameter pseudopotential nor electrons are considered for that ghost atom.
λ in equation (2) above for charge confinement (in Bohr−1 ). Useful for BSSE correction.
- delta(lhs,is): Optional input. Singularity regularisation pa- Use: This block is optional, except when Bessel functions or semicore
rameter δ in equation (2) above for charge confinement (in states are present.
Bohr). Default: Basis characteristics defined by global definitions given
above.
- rcls(izeta,l,is): Cutoff radius (Bohr) of each ’zeta’ for this
shell. For the second zeta onwards, if this value is negative, the
actual rc used will be the given fraction of the first zeta’s rc. 6.3.9 Filtering
- contrf(izeta,l,is): Optional input. Contraction factor of
each “zeta” for this shell. Default value: 1.0 FilterCutoff 0 eV (energy)
Kinetic energy cutoff of plane waves used to filter all the atomic ba-
Polarization orbitals are generated by solving the atomic problem in
sis functions, the pseudo-core densities for partial core corrections,
the presence of a polarizing electric field. The orbitals are generated
and the neutral-atom potentials. The basis functions (which must
applying perturbation theory to the first-zeta orbital of lower angular
be squared to obtain the valence density) are really filtered with a
momentum. They have the same cutoff radius as the orbitals from
cutoff reduced by an empirical factor 0.72 ' 0.5. The FilterCut-
which they are constructed.

24
 off should be similar or lower than the MeshCutoff to avoid the package.
eggbox effect on the atomic forces. However, one should not try to These files can be used to read back information into SIESTA.
converge MeshCutoff while simultaneously changing FilterCut-
off , since the latter in fact changes the used basis functions. Rather, User.Basis false (logical)
fix a sufficiently large FilterCutoff and converge only MeshCut- If true, the basis, KB projector, and other information is read from
off . If FilterCutoff is not explicitly set, its value is calculated from files Atomlabel.ion, where Atomlabel is the atomic species label spec-
FilterTol. ified in block ChemicalSpeciesLabel. These files can be generated
by a previous SIESTA run or (one by one) by the standalone pro-
FilterTol 0 eV (energy)
gram Gen-basis. No pseudopotential files are necessary.
Residual kinetic-energy leaked by filtering each basis function. While
FilterCutoff sets a common reciprocal-space cutoff for all the ba- User.Basis.NetCDF false (logical)
sis functions, FilterTol sets a specific cutoff for each basis function, If true, the basis, KB projector, and other information is read from
much as the PAO.EnergyShift sets their real-space cutoff. There- NetCDF files Atomlabel.ion.nc, where Atomlabel is the atomic la-
fore, it is reasonable to use similar values for both parameters. The bel specified in block ChemicalSpeciesLabel. These files can be
maximum cutoff required to meet the FilterTol, among all the ba- generated by a previous SIESTA run or by the standalone program
sis functions, is used (multiplied by the empirical factor 1/0.72 ' 2) Gen-basis. No pseudopotential files are necessary. NetCDF support
to filter the pseudo-core densities and the neutral-atom potentials. is needed. Note that ghost atoms cannot yet be adequately treated
FilterTol is ignored if FilterCutoff is present in the input file. If with this option.
neither FilterCutoff nor FilterTol are present, no filtering is per-
formed. See Soler and Anglada [13] , for details of the filtering proce-
dure. 6.3.11 Tools to inspect the orbitals and KB projectors
Warning: If the value of FilterCutoff is made too small (or Filter-
The program ioncat in Util/Gen-basis can be used to extract orbital,
Tol too large) some of the filtered basis orbitals may be meaningless,
KB projector, and other information contained in the .ion files. The
leading to incorrect results or even a program crash.
output can be easily plotted with a graphics program. If the option
To be implemented: If MeshCutoff is not present in the input file, WriteIonPlotFiles is enabled, SIESTA will generate and extra set of
it can be set using the maximum filtering cutoff used for the given files that can be plotted with the gnuplot scripts in Tutorials/Bases.
FilterTol (for the time being, you can use AtomSetupOnly true The stand-alone program gen-basis sets that option by default, and the
to stop the program after basis generation, look at the maximum script Tutorials/Bases/gen-basis.sh can be used to automate the pro-
filtering cutoff used, and set the mesh-cutoff manually in a later run.) cess. See also the NetCDF-based utilities in Util/PyAtom.

6.3.10 Saving and reading basis-set information 6.3.12 Basis optimization

SIESTA (and the standalone program Gen-basis) always generate the There are quite a number of options for the input of the basis-set and KB
files Atomlabel.ion, where Atomlabel is the atomic label specified in block projector specification, and they are all optional! By default, SIESTA
ChemicalSpeciesLabel. Optionally, if NetCDF support is compiled will use a DZP basis set with appropriate choices for the determina-
in, the programs generate NetCDF files Atomlabel.ion.nc (except for tion of the range, etc. Of course, the more you experiment with the
ghost atoms). See an Appendix for information on the optional NetCDF different options, the better your basis set can get. To aid in this

25
process we offer an auxiliary program for optimization which can be to Restricted.Radial.Grid false) is a closer mapping of any user-
used in particular to obtain variationally optimal basis sets (within a specified cutoff radii and of the radii implicitly resulting from other
chosen basis size). SeeÂăUtil/Optimizer for general information, and input parameters to the actual values used by the program. (The
Util/Optimizer/Examples/Basis_Optim for an example. small grid-point separation near r=0 is still needed to avoid instabil-
ities for s channels that occurred with the previous (reparametrized)
BasisPressure 0.2 GPa (pressure) default spacing of 0.005 bohr. This effect is not yet completely un-
SIESTA will compute and print the value of the “effective basis derstood. )
enthalpy” constructed by adding a term of the form pbasis Vorbs to the
total energy. Here pbasis is a fictitious basis pressure and Vorbs is the New.A.Parameter 0.001 (real)
volume of the system’s orbitals. This is a useful quantity for basis New setting for the pseudopotential grid’s a parameter
optimization (See Anglada et al.). The total basis enthalpy is also
written to the ASCII file BASIS_ENTHALPY. New.B.Parameter 0.01 (real)
New setting for the pseudopotential grid’s b parameter

6.3.13 Low-level options regarding the radial grid Rmax.Radial.Grid 50.0 (real)
New setting for the maximum value of the radial coordinate for inte-
For historical reasons, the basis-set and KB projector code in SIESTA gration of the atomic Schrodinger equation.
uses a logarithmic radial grid, which is taken from the pseudopotential If Reparametrize.Pseudos is false this will be the maximum ra-
file. Any “interesting” radii have to fall on a grid point, which introduces a dius in the pseudopotential file.
certain degree of coarseness that can limit the accuracy of the results and
the faithfulness of the mapping of input parameters to actual operating Restricted.Radial.Grid true (logical)
parameters. For example, the same orbital will be produced by a finite In normal operation of the basis-set and projector generation code
range of PAO.EnergyShift values, and any user-defined cutoffs will not the various cutoff radii are restricted to falling on an odd-numbered
be exactly reflected in the actual cutoffs. This is particularly trouble- grid point, shifting then accordingly. This restriction can be lifted
some for automatic optimization procedures (such as those implemented by setting this parameter to false.
in Util/Optimizer), as the engine might be confused by the extra level of
indirection. The following options can be used to fine-tune the mapping.
They are not enabled by default, as they change the numerical results 6.4 Structural information
apreciably (in effect, they lead to different basis orbitals and projectors).
There are many ways to give SIESTA structural information.
Reparametrize.Pseudos false (logical)
By changing the a and b parameters of the logarithmic grid, a new one • Directly from the fdf file in traditional format.
with a more adequate grid-point separation can be used for the gen- • Directly from the fdf file in the newer Z-Matrix format, using a
eration of basis sets and projectors. For example, by using a = 0.001 Zmatrix block.
and b = 0.01, the grid point separations at r = 0 and 10 bohrs are
0.00001 and 0.01 bohrs, respectively. More points are needed to reach • From an external data file
r’s of the order of a hundred bohrs, but the extra computational ef-
fort is negligible. The net effect of this option (notably when coupled Note that, regardless of the way in which the structure is described, the
ChemicalSpeciesLabel block is mandatory.

26
In the following sections we document the different structure input meth- This defaults to a square cell with side-lengths equal to LatticeCon-
ods, and provide a guide to their precedence. stant.
1.0 0.0 0.0
6.4.1 Traditional structure input in the fdf file 0.0 1.0 0.0
0.0 0.0 1.0
Firstly, the size of the cell itself should be specified, using some combi- If the LatticeConstant default is used, the default of LatticeVec-
nation of the options LatticeConstant, LatticeParameters, and Lat- tors is still diagonal but not necessarily cubic.
ticeVectors, and SuperCell. If nothing is specified, SIESTA will con-
struct a cubic cell in which the atoms will reside as a cluster. %block SuperCell 〈None〉 (block)
Secondly, the positions of the atoms within the cells must be specified, us- Integer 3x3 matrix defining a supercell in terms of the unit cell. Any
ing either the traditional SIESTA input format (a modified xyz format) values larger than 1 will expand the unitcell (plus atoms) along that
which must be described within a AtomicCoordinatesAndAtomic- lattice vector direction (if possible).
Species block. %block SuperCell
M(1,1) M(2,1) M(3,1)
LatticeConstant 〈None〉 (length) M(1,2) M(2,2) M(3,2)
Lattice constant. This is just to define the scale of the lattice vectors. M(1,3) M(2,3) M(3,3)
%endblock SuperCell
Default value: Minimum size to include the system (assumed to be a
molecule) without intercell interactions, plus 10%. and the supercell is defined as SuperCell(ix, i) = j CELL(ix, j) ∗
P

NOTE: A LatticeConstant value, even if redundant, might be M (j, i). Notice that the matrix indexes are inverted: each input line
needed for other options, such as the units of the k-points used for specifies one supercell vector.
band-structure calculations. This mis-feature will be corrected in Warning: SuperCell is disregarded if the geometry is read from the
future versions. XV file, which can happen inadvertently.
Use: The atomic positions must be given only for the unit cell, and
%block LatticeParameters 〈None〉 (block)
they are ’cloned’ automatically in the rest of the supercell. The
Crystallographic way of specifying the lattice vectors, by giving six
NumberOfAtoms given must also be that in a single unit cell.
real numbers: the three vector modules, a, b, and c, and the three
However, all values in the output are given for the entire supercell.
angles α (angle between ~b and ~c), β, and γ. The three modules are
In fact, CELL is immediately redefined as the whole supercell and the
in units of LatticeConstant, the three angles are in degrees.
program no longer knows the existence of an underlying unit cell.
This defaults to a square cell with side-lengths equal to LatticeCon- All other input (apart from NumberOfAtoms and atomic positions),
stant. including kgrid.MonkhorstPack must refer to the supercell (this is
1.0 1.0 1.0 90. 90. 90. a change over previous versions). Therefore, to avoid confusions, we
recommend to use SuperCell only to generate atomic positions, and
%block LatticeVectors 〈None〉 (block) then to copy them from the output to a new input file with all the
The cell vectors are read in units of the lattice constant defined above. atoms specified explicitly and with the supercell given as a normal
They are read as a matrix CELL(ixyz,ivector), each vector being unit cell.
one line.
AtomicCoordinatesFormat Bohr (string)

27
 Character string to specify the format of the atomic positions in NOTE: Zmatrix has precedence if specified.
input. These can be expressed in four forms:
Bohr|NotScaledCartesianBohr atomic positions are given di- 6.4.2 Z-matrix format and constraints
rectly in Bohr, in Cartesian coordinates
The advantage of the traditional format is that it is much easier to set up
Ang|NotScaledCartesianAng atomic positions are given directly
a system. However, when working on systems with constraints, there are
in Ångström, in Cartesian coordinates only a limited number of (very simple) constraints that may be expressed
ScaledCartesian atomic positions are given in Cartesian coordi- within this format, and recompilation is needed for each new constraint.
nates, in units of the lattice constant For any more involved set of constraints, a full Zmatrix formulation
Fractional|ScaledByLatticeVectors atomic positions are given re- should be used - this offers much more control, and may be specified fully
ferred to the lattice vectors at run time (thus not requiring recompilation) - but it is more work to
generate the input files for this form.
AtomCoorFormatOut 〈AtomicCoordinatesFormat〉 (string)
Character string to specify the format of the atomic positions in %block Zmatrix 〈None〉 (block)
output. This block provides a means for inputting the system geometry using
Same possibilities as for input AtomicCoordinatesFormat. a Z-matrix format, as well as controlling the optimization variables.
This is particularly useful when working with molecular systems or
%block AtomicCoordinatesOrigin 〈None〉 (block) restricted optimizations (such as locating transition states or rigid
Vector specifying a rigid shift to apply to the atomic coordinates, unit movements). The format also allows for hybrid use of Z-matrices
given in the same format and units as these. Notice that the atomic and Cartesian or fractional blocks, as is convenient for the study of
positions (shifted or not) need not be within the cell formed by Lat- a molecule on a surface. As is always the case for a Z-matrix, the
ticeVectors, since periodic boundary conditions are always assumed. responsibility falls to the user to chose a sensible relationship between
This defaults to the origo: the variables to avoid triads of atoms that become linear.
Below is an example of a Z-matrix input for a water molecule:
0.0 0.0 0.0
%block Zmatrix
%block AtomicCoordinatesAndAtomicSpecies 〈None〉 (block) molecule fractional
Block specifying the position and species of each atom. One line per 1 0 0 0 0.0 0.0 0.0 0 0 0
atom, the reading is done this way: 2 1 0 0 HO1 90.0 37.743919 1 0 0
2 1 2 0 HO2 HOH 90.0 1 1 0
From ia = 1 to natoms variables
read: xa(ix,ia), isa(ia) HO1 0.956997
HO2 0.956997
where xa(ix,ia) is the ix coordinate of atom iai in the format
HOH 104.4
(units) specified by AtomicCoordinatesFormat, and isa(ia) is %endblock Zmatrix
the species index of atom ia.
NOTE: This block must be present in the fdf file. If Num- The sections that can be used within the Zmatrix block are as follows:
berOfAtoms is not specified, NumberOfAtoms will be defaulted Firstly, all atomic positions must be specified within either a
to the number of atoms in this block. “molecule” block or a “cartesian” block. Any atoms subject to

28
 constraints more complicated than “do not change this coordinate of are to be specified in Cartesian coordinates. Again, an option of
this atom” must be specified within a “molecule” block. “fractional” or “scaled” may be added, to specify the units
used; and again, in their absence, the value of “ZM.UnitsLength”
molecule There must be one of these blocks for each independent set
is taken.
of constrained atoms within the simulation.
The format of each atom in the block will look like:
This specifies the atoms that make up each molecule and their ge-
ometry. In addition, an option of “fractional” or “scaled” may Nspecies x y z ix iy iz
be passed, which indicates that distances are specified in scaled or Here Nspecies, ix, iy, and iz are integers and x, y, z are reals.
fractional units. In the absence of such an option, the distance Nspecies is the species number of the atom being specified, while
units are taken to be the value of “ZM.UnitsLength”. x, y, and z are the Cartesian coordinates of the atom in whichever
A line is needed for each atom in the molecule; the format of each units are being used. The values ix, iy and iz are integer flags that
line should be: indicate whether the x, y, and z coordinates, respectively, should
Nspecies i j k r a t ifr ifa ift be varied or not. A value of 0 implies that the coordinate is fixed,
while 1 implies that it should be varied. NOTE: When performing
Here the values Nspecies, i, j, k, ifr, ifa, and ift are integers “variable cell” optimization while using a Zmatrix format for input,
and r, a, and t are double precision reals. the algorithm will not work if some of the coordinates of an atom
For most atoms, Nspecies is the species number of the atom, r in a cartesian block are variables and others are not (i.e., ix iy
is distance to atom number i, a is the angle made by the present iz above must all be 0 or 1). This will be fixed in future versions
atom with atoms j and i, while t is the torsional angle made by of the program.
the present atom with atoms k, j, and i. The values ifr, ifa and A Zmatrix block may also contain the following, additional, sec-
ift are integer flags that indicate whether r, a, and t, respectively, tions, which are designed to make it easier to read.
should be varied; 0 for fixed, 1 for varying.
The first three atoms in a molecule are a special case. Because there constants Instead of specifying a numerical value, it is possible to
are insufficient atoms defined to specify a distance/angle/torsion, specify a symbol within the above geometry definitions. This sec-
the values are set differently. For atom 1, r, a, and t, are the tion allows the user to define the value of the symbol as a constant.
Cartesian coordinates of the atom. For the second atom, r, a, and The format is just a symbol followed by the value:
t are the coordinates in spherical form of the second atom relative HOH 104.4
to the first: first the radius, then the polar angle (angle between the variables Instead of specifying a numerical value, it is possible to
z-axis and the displacement vector) and then the azimuthal angle specify a symbol within the above geometry definitions. This sec-
(angle between the x-axis and the projection of the displacement tion allows the user to define the value of the symbol as a variable.
vector on the x-y plane). Finally, for the third atom, the numbers The format is just a symbol followed by the value:
take their normal form, but the torsional angle is defined relative
HO1 0.956997
to a notional atom 1 unit in the z-direction above the atom j.
Secondly. blocks of atoms all of which are subject to the simplest Finally, constraints must be specified in a constraints block.
of constraints may be specified in one of the following three ways, constraint This sub-section allows the user to create constraints be-
according to the units used to specify their coordinates: tween symbols used in a Z-matrix:
cartesian This section specifies a block of atoms whose coordinates constraint
var1 var2 A B

29
 Here var1 and var2 are text symbols for two quantities in the Z- 3 0.166667 0.750000 0.150000 0 0 0
matrix definition, and AandB are real numbers. The variables are 3 0.500000 0.750000 0.150000 0 0 0
related by var1 = A ∗ var2 + B. 3 0.833333 0.750000 0.150000 0 0 0
constants
An example of a Z-matrix input for a benzene molecule over a metal ym1 3.68
surface is: variables
zm1 6.9032294
%block Zmatrix CC 1.417
molecule CH 1.112
2 0 0 0 xm1 ym1 zm1 0 0 0 CCH 120.0
2 1 0 0 CC 90.0 60.0 0 0 0 CCC 120.0
2 2 1 0 CC CCC 90.0 0 0 0 constraints
2 3 2 1 CC CCC 0.0 0 0 0 xm1 CC -1.0 3.903229
2 4 3 2 CC CCC 0.0 0 0 0 %endblock Zmatrix
2 5 4 3 CC CCC 0.0 0 0 0
1 1 2 3 CH CCH 180.0 0 0 0 Here the species 1, 2 and 3 represent H, C, and the metal of the
1 2 1 7 CH CCH 0.0 0 0 0 surface, respectively.
1 3 2 8 CH CCH 0.0 0 0 0
(Note: the above example shows the usefulness of symbolic names for
1 4 3 9 CH CCH 0.0 0 0 0
1 5 4 10 CH CCH 0.0 0 0 0 the relevant coordinates, in particular for those which are allowed to
1 6 5 11 CH CCH 0.0 0 0 0 vary. The current output options for Zmatrix information work best
fractional when this approach is taken. By using a “fixed” symbolic Zmatrix
3 0.000000 0.000000 0.000000 0 0 0 block and specifying the actual coordinates in a “variables” section,
3 0.333333 0.000000 0.000000 0 0 0 one can monitor the progress of the optimization and easily recon-
3 0.666666 0.000000 0.000000 0 0 0 struct the coordinates of intermediate steps in the original format.)
3 0.000000 0.500000 0.000000 0 0 0
3 0.333333 0.500000 0.000000 0 0 0 ZM.UnitsLength Bohr (string)
3 0.666666 0.500000 0.000000 0 0 0
Parameter that specifies the units of length used during Z-matrix
3 0.166667 0.250000 0.050000 0 0 0
3 0.500000 0.250000 0.050000 0 0 0 input.
3 0.833333 0.250000 0.050000 0 0 0 Specify Bohr or Ang for the corresponding unit of length.
3 0.166667 0.750000 0.050000 0 0 0
3 0.500000 0.750000 0.050000 0 0 0 ZM.UnitsAngle rad (string)
3 0.833333 0.750000 0.050000 0 0 0 Parameter that specifies the units of angles used during Z-matrix
3 0.000000 0.000000 0.100000 0 0 0 input.
3 0.333333 0.000000 0.100000 0 0 0
Specify rad or deg for the corresponding unit of angle.
3 0.666666 0.000000 0.100000 0 0 0
3 0.000000 0.500000 0.100000 0 0 0
3 0.333333 0.500000 0.100000 0 0 0 6.4.3 Output of structural information
3 0.666666 0.500000 0.100000 0 0 0
3 0.166667 0.250000 0.150000 0 0 0
SIESTA is able to generate several kinds of files containing structural
3 0.500000 0.250000 0.150000 0 0 0
3 0.833333 0.250000 0.150000 0 0 0 information (maybe too many).

30
• SystemLabel.STRUCT_OUT:Siesta always produces a .STRUCT_OUT • Additionally, several optional formats are supported:
file with cell vectors in Å and atomic positions in fractional coor-
dinates. This file, renamed to .STRUCT_IN can be used for crystal- WriteCoorXmol false (logical)
structure input. Note that the geometry reported is the last one for If true it originates the writing of an extra file named
which forces and stresses were computed. See UseStructFile SystemLabel.xyz containing the final atomic coordinates in
a format directly readable by XMol.4 Coordinates come out
• SystemLabel.STRUCT_NEXT_ITER:This file is always written, in the in Ångström independently of what specified in AtomicCoor-
same format as .STRUCT_OUT file. The only difference is that it dinatesFormat and in AtomCoorFormatOut. There is a
contains the structural information after it has been updated by present Java implementation of XMol called JMol.
the relaxation or the molecular-dynamics algorithms, and thus it
could be used as input (renamed as .STRUCT_IN) for a continuation WriteCoorCerius false (logical)
run, in the same way as the .XV file. If trueit originates the writing of an extra file named
SystemLabel.xtl containing the final atomic coordinates in
See UseStructFile
a format directly readable by Cerius.5 Coordinates come out
• SystemLabel.XV:The coordinates are always written in the .XV file, in Fractional format (the same as ScaledByLatticeVectors)
and overriden at every step. independently of what specified in AtomicCoordinatesFor-
mat and in AtomCoorFormatOut. If negative coordinates
• OUT.UCELL.ZMATRIX:This file is produced if the Zmatrix format is are to be avoided, it has to be done from the start by shifting all
being used for input. (Please note that SystemLabel is not used the coordinates rigidly to have them positive, by using Atom-
as a prefix.) It contains the structural information in fdf form, with icCoordinatesOrigin. See the Sies2arc utility in the Util/
blocks for unit-cell vectors and for Zmatrix coordinates. The Zma- directory for generating ..arc files for CERIUS animation.
trix block is in a “canonical” form with the following characteristics:
WriteMDXmol false (logical)
1. No symbolic variables or constants are used. If true it causes the writing of an extra file named
2. The position coordinates of the first atom in each molecule SystemLabel.ANI containing all the atomic coordinates of the
are absolute Cartesian coordinates. simulation in a format directly readable by XMol for anima-
3. Any coordinates in ‘‘cartesian’’ blocks are also absolute Cartesians. tion. Coordinates come out in Ångström independently of what
4. There is no provision for output of constraints. is specified in AtomicCoordinatesFormat and in Atom-
5. The units used are those initially specified by the user, and are CoorFormatOut. This file is accumulative even for different
noted also in fdf form. runs.
There is an alternative for animation by generating a .arc file
Note that the geometry reported is the last one for which forces and for CERIUS. It is through the Sies2arc postprocessing utility
stresses were computed. in the Util/ directory, and it requires the coordinates to be
accumulated in the output file, i.e., WriteCoorStep true.
• NEXT_ITER.UCELL.ZMATRIX:A file with the same format as 4
XMol is under © copyright of Research Equipment Inc., dba Minnesota Supercom-
OUT.UCELL.ZMATRIX but with a possibly updated geometry. puter Center Inc.
5
Cerius is under © copyright of Molecular Simulations Inc.
• The coordinates can be also accumulated in the SystemLabel.MD or
SystemLabel.MDX files depending on WriteMDHistory.

31
6.4.4 Input of structural information from external files 6.4.5 Input from a FIFO file

The structural information can be also read from external files. Note that See the “Forces” option in MD.TypeOfRun. Note that Chemical-
ChemicalSpeciesLabel is mandatory in the fdf file. SpeciesLabel is still mandatory in the fdf file.

MD.UseSaveXV false (logical)

Logical variable which instructs SIESTA to read the atomic positions 6.4.6 Precedence issues in structural input
and velocities stored in file SystemLabel.XV by a previous run.
• If the “Forces” option is active, it takes precedence over everything
If the file does not exist, a warning is printed but the program does
(it will overwrite all other input with the information it gets from
not stop. Overrides UseSaveData, but can be implicitly set by it.
the FIFO file).
UseStructFile false (logical)
• If MD.UseSaveXV is active, it takes precedence over the options
Controls whether the structural information is read from an external below.
file of name SystemLabel.STRUCT_IN. If true, all other structural
information in the fdf file will be ignored. • If UseStructFile (or MD.UseStructFile) is active, it takes prece-
The format of the file is implied by the following code: dence over the options below.

read(*,*) ((cell(ixyz,ivec),ixyz=1,3),ivec=1,3) ! Cell vectors, • For

in atomic coordinates, the traditional and Zmatrix formats in the
Angstroms
read(*,*) na fdf file are mutually exclusive. If MD.UseSaveZM is active, the
do ia = 1,na contents of the ZM file, if found, take precedence over the Zmatrix
read(iu,*) isa(ia), dummy, xfrac(1:3,ia) ! Species number information in the fdf file.
! Dummy numerical column
! Fractional coordinates
6.4.7 Interatomic distances
enddo
WarningMinimumAtomicDistance 1 Bohr (length)
Warning: Note that the resulting geometry could be clobbered if an
.XV file is read after this file. It is up to the user to remove any .XV Fixes a threshold interatomic distance below which a warning mes-
files. sage is printed.

MD.UseSaveZM false (logical) MaxBondDistance 6 Bohr (length)

Instructs to read the Zmatrix information stored in file .ZM by a SIESTA prints the interatomic distances, up to a range of
previous run. MaxBondDistance, to file SystemLabel.BONDS upon first reading
the structural information, and to file SystemLabel.BONDS_FINAL af-
If the required file does not exist, a warning is printed but the pro-
ter the last geometry iteration. The reference atoms are all the atoms
gram does not stop. Overrides UseSaveData, but can be implicitly
in the unit cell. The routine now prints the real location of the neigh-
set by it.
bor atoms in space, and not, as in earlier versions, the location of the
Warning: Note that the resulting geometry could be clobbered if an
equivalent representative in the unit cell.
.XV file is read after this file. It is up to the user to remove any .XV
files.

32
6.5 k-point sampling where Mk(j,i) are integers and dk(i) are usually either 0.0 or 0.5
(the program will warn the user if the displacements chosen are
These are options for the k-point grid used in the SCF cycle. For other not optimal). The k-grid supercell is defined from Mk as in block
specialized grids, see the Macroscopic Polarization and Density of States SuperCell above, i.e.: KgridSuperCell(ix, i) = j CELL(ix, j) ∗
P
sections. M k(j, i). Note again that the matrix indexes are inverted: each in-
put line gives the decomposition of a supercell vector in terms of the
kgrid.Cutoff 0. Bohr (length)
unit cell vectors.
Parameter which determines the fineness of the k-grid used for Bril-
Use: Used only if SolutionMethod diagon. The k-grid supercell
louin zone sampling. It is half the length of the smallest lattice vector
is compatible and unrelated (except for the default value, see below)
of the supercell required to obtain the same sampling precision with
with the SuperCell specifier. Both supercells are given in terms
a single k point. Ref: Moreno and Soler, PRB 45, 13891 (1992).
of the CELL specified by the LatticeVectors block. If Mk is the
Use: If it is zero, only the gamma point is used. The resulting identity matrix and dk is zero, only the Γ point of the unit cell is
k-grid is chosen in an optimal way, according to the method of used. Overrides kgrid.Cutoff
Moreno and Soler (using an effective supercell which is as spheri-
cal as possible, thus minimizing the number of k-points for a given ChangeKgridInMD false (logical)
precision). The grid is displaced for even numbers of effective mesh If true, the k-point grid is recomputed at every iteration during
divisions. This parameter is not used if kgrid.MonkhorstPack is MD runs that potentially change the unit cell: Parrinello-Rahman,
specified. If the unit cell changes during the calculation (for example, Nose-Parrinello-Rahman, and Anneal. Regardless of the setting of
in a cell-optimization run, the k-point grid will change accordingly this flag, the k-point grid is always updated at every iteration of a
(see ChangeKgridInMD for the case of variable-cell molecular- variable-cell optimization and after each step in a “siesta-as-server”
dynamics runs, such as Parrinello-Rahman). This is analogous to run.
the changes in the real-space grid, whose fineness is specified by an It is defaulted to false for historical reasons. The rationale was to
energy cutoff. If sudden changes in the number of k-points are not avoid sudden jumps in some properties when the sampling changes,
desired, then the Monkhorst-Pack data block should be used instead. but if the calculation is well-converged there should be no problems
In this case there will be an implicit change in the quality of the if the update is enabled.
sampling as the cell changes. Both methods should be equivalent for
a well-converged sampling. TimeReversalSymmetryForKpoints true (logical)
If true, the k-points in the BZ generated by the methods above are
%block kgrid.MonkhorstPack Γ-point (block)
paired as (k,-k) and only one member of the pair is retained. This
Real-space supercell, whose reciprocal unit cell is that of the k- symmetry is valid in the absence of external magnetic fields or non-
sampling grid, and grid displacement for each grid coordinate. Spec- collinear/spin-orbit interaction.
ified as an integer matrix and a real vector:
This flag should be used with care, as the code will produce wrong
%block kgrid.MonkhorstPack results if there is no support for the appropriate symmetrization.
Mk(1,1) Mk(2,1) Mk(3,1) dk(1) The default value is trueunless: a) the option Spin.Spiral is used.
Mk(1,2) Mk(2,2) Mk(3,2) dk(2)
In this case time-reversal-symmetry is broken explicitly. b) non-
Mk(1,3) Mk(2,3) Mk(3,3) dk(3)
%endblock collinear spin calculations. This case is less clear cut, but the time-
reversal symmetry is not used to avoid possible breakings due to

33
 subtle implementation details, and to make the set of wavefunctions • RPBE: Modified GGA-PBE functional of B. Hammer, L. B.
compatible with spin-orbit case in analysis tools. Hansen and J. K. Norskov Phys. Rev. B 59, 7413 (1999)
• WC: Modified GGA-PBE functional of Z. Wu and R. E. Cohen,
6.5.1 Output of k-point information Phys. Rev. B 73, 235116 (2006)
• AM05: Modified GGA-PBE functional of R. Armiento and A.
The coordinates of the ~k points used in the sampling are always stored in E. Mattsson, Phys. Rev. B 72, 085108 (2005)
the file SystemLabel.KP. • PBEsol: Modified GGA-PBE functional of J. P. Perdew et al,
WriteKpoints false (logical) Phys. Rev. Lett. 100, 136406 (2008)
• PBEJsJrLO: GGA-PBE functional with parameters β, µ, and
If true it writes the coordinates of the ~k vectors used in the grid for
κ fixed by the jellium surface (Js), jellium response (Jr), and
k-sampling, into the main output file.
Lieb-Oxford bound (LO) criteria, respectively, as described by
Default depends on LongOutput. L. S. Pedroza, A. J. R. da Silva, and K. Capelle, Phys. Rev.
B 79, 201106(R) (2009), and by M. M. Odashima, K. Capelle,
6.6 Exchange-correlation functionals and S. B. Trickey, J. Chem. Theory Comput. 5, 798 (2009)
• PBEJsJrHEG: Same as PBEJsJrLO, with parameter κ fixed
XC.Functional LDA (string)
by the Lieb-Oxford bound for the low density limit of the ho-
Exchange-correlation functional type. May be LDA (local density mogeneous electron gas (HEG)
approximation, equivalent to LSD), GGA (Generalized Gradient
• PBEGcGxLO: Same as PBEJsJrLO, with parameters β and µ
Approximation), or VDW (van der Waals).
fixed by the gradient expansion of correlation (Gc) and exchange
XC.Authors PZ (string) (Gx), respectively
Particular parametrization of the exchange-correlation functional. • PBEGcGxHEG: Same as previous ones, with parameters β, µ,
Options are: and κ fixed by the Gc, Gx, and HEG criteria, respectively.
• CA (equivalent to PZ): (Spin) local density approximation • BLYP (equivalent to LYP): GGA with Becke exchange (A. D.
(LDA/LSD). Quantum Monte Carlo calculation of the homo- Becke, Phys. Rev. A 38, 3098 (1988)) and Lee-Yang-Parr cor-
geneous electron gas by D. M. Ceperley and B. J. Alder, Phys. relation (C. Lee, W. Yang, R. G. Parr, Phys. Rev. B 37, 785
Rev. Lett. 45,566 (1980), as parametrized by J. P. Perdew and (1988)), as modified by B. Miehlich, A. Savin, H. Stoll, and H.
A. Zunger, Phys. Rev B 23, 5075 (1981) Preuss, Chem. Phys. Lett. 157, 200 (1989). See also B. G.
Johnson, P. M. W. Gill and J. A. Pople, J. Chem. Phys. 98,
• PW92: LDA/LSD, as parametrized by J. P. Perdew and Y.
5612 (1993). (Some errors were detected in this last paper, so
Wang, Phys. Rev B, 45, 13244 (1992)
not all of their expressions correspond exactly to those imple-
• PW91: Generalized gradients approximation (GGA) of Perdew mented in SIESTA)
and Wang. Ref: P&W, J. Chem. Phys., 100, 1290 (1994)
• DRSLL (equivalent to DF1): van der Waals density functional
• PBE: GGA of J. P. Perdew, K. Burke and M. Ernzerhof, Phys. (vdW-DF) of M. Dion, H. Rydberg, E. Schröder, D. C. Lan-
Rev. Lett. 77, 3865 (1996) greth, and B. I. Lundqvist, Phys. Rev. Lett. 92, 246401 (2004),
• revPBE: Modified GGA-PBE functional of Y. Zhang and W. with the efficient implementation of G. Román-Pérez and J. M.
Yang, Phys. Rev. Lett. 80, 890 (1998) Soler, Phys. Rev. Lett. 103, 096102 (2009)

34
 • LMKLL (equivalent to DF2): vdW-DF functional of Dion et GGA PBE 0.5 0.25
al (same as DRSLL) reparametrized by K. Lee, E. Murray, L. %endblock XC.hybrid
Kong, B. I. Lundqvist and D. C. Langreth, Phys. Rev. B 82,
081101 (2010)
6.7 Spin polarization
• KBM: vdW-DF functional of Dion et al (same as DRSLL)
with exchange modified by J. Klimes, D. R. Bowler, and A. Spin non-polarized (string)
Michaelides, J. Phys.: Condens. Matter 22, 022201 (2010) Choose the spin-components in the simulation.
(optB88-vdW version) NOTE: This flag has precedence over SpinOrbit, NonCollinear-
• C09: vdW-DF functional of Dion et al (same as DRSLL) with Spin and SpinPolarized while these deprecated flags may still be
exchange modified by V. R. Cooper, Phys. Rev. B 81, 161104 used.
(2010) non-polarized Perform a calculation with spin-degeneracy (only one
• BH: vdW-DF functional of Dion et al (same as DRSLL) with component).
exchange modified by K. Berland and P. Hyldgaard, Phys. Rev. polarized Perform a calculation with colinear spin (two spin compo-
B 89, 035412 (2014) nents).
• VV: vdW-DF functional of O. A. Vydrov and T. Van Voorhis,
non-colinear Perform a calculation with non-colinear spin (4 spin
J. Chem. Phys. 133, 244103 (2010)
components), up-down and angles.
%block XC.Hybrid 〈None〉 (block) Refs: T. Oda et al, PRL, 80, 3622 (1998); V. M. García-Suárez et
This data block allows the user to create a “cocktail” functional by al, Eur. Phys. Jour. B 40, 371 (2004); V. M. García-Suárez et al,
mixing the desired amounts of exchange and correlation from each of Journal of Phys: Cond. Matt 16, 5453 (2004).
the functionals described under XC.authors. Note that these “mixed” spin-orbit Perform a calculation with spin-orbit coupling. This re-
functionals do not have the exact Hartree-Fock exchange which is a quires the pseudopotentials to be relativistic.
key ingredient of the true “hybrid” functionals. The use of the word See Sect. 6.8.
“hybrid” in the label is unfortunate in this regard, and might be
deprecated in a future version. SIESTA can read a .DM with different spin structure by adapting the
The first line of the block must contain the number of functionals information to the currently selected spin multiplicity, averaging or
to be mixed. On the subsequent lines the values of XC.functl and splitting the spin components equally, as needed. This may be used
XC.authors must be given and then the weights for the exchange and to greatly increase convergence.
correlation, in that order. If only one number is given then the same Certain options may not be used together with specific parallelization
weight is applied to both exchange and correlation. routines. For instance only a spin-polarized calculation may use the
The following is an example in which a 75:25 mixture of Ceperley- Diag.ParallelOverK option.
Alder and PBE correlation is made, with an equal split of the ex- Spin.Fix false (logical)
change energy:
If true, the calculation is done with a fixed value of the spin of the
%block XC.hybrid system, defined by variable Spin.Total. This option can only be
2 used for colinear spin polarized calculations.
LDA CA 0.5 0.75

35
 Spin.Total 0 (real) • Selfconsistent calculations for gamma point as well as for bulks (Not
Value of the imposed total spin polarization of the system (in units yet implemented for optimizations).
of the electron spin, 1/2). It is only used if Spin.Fix true.
• Magnetic Anisotropy Energy (MAE) can be easily calculated. From
SingleExcitation false (logical) first principles calculations, MAE is obtained after subtract the total
If true, SIESTA calculates a very rough approximation to the lowest selfconsistent energy in two different orientations, usually the total
excited state by swapping the populations of the HOMO and the energy associated with easy axis from the hard axis. In SIESTA it is
LUMO. If there is no spin polarisation, it is half swap only. It is possible to perform several self-consistent calculations for different
done for the first spin component (up) and first k vector. magnetization orientations using the specific block DM.InitSpin
in the fdf file. In doing so one will be able to include the initial
orientation angles of the magnetization for each atom, as well as an
6.8 Spin–Orbit coupling initial value of their net magnetic moments.

SIESTA includes the posibility to perform fully relativistic calculations • By means of Mulliken analysis, after the self-consistent procedure,
by means of the inclusion in the total Hamiltonian not only the Darwin local spin and orbital moments can be calculated by means of the
and velocity correction terms (Scalar–Relativistic calculations), but also flags WriteMullikenPop and WriteOrbMom.
the spin-orbit (SO) contribution. The implementation is based on the
on-site SO approximation, where only the intra-SO contribution of each Note: Due to the small SO energy value contribution to the total energy,
atom is taken into account. See Spin on how to turn on the spin-orbit the level of precision requiered to perform a proper fully relativistic calcu-
coupling. lation during the selfconsistent process is quite demanding. The following
values must be carefully converged and checked for each specific system
The current implementation in SIESTA has been implemented by Dr. to assure that the results are accurate enough: SCF.H.Tolerance dur-
Ramón Cuadrado based on the original on-site SO formalism and imple- ing the selfconsistency (typically <10−5 eV), ElectronicTemperature,
mentation developed by Prof. Jaime Ferrer, et al (L Fernández–Seivane, k-point sampling and high values of MeshCutoff (specifically for ex-
M Oliveira, S Sanvito, and J Ferrer, Journal of Physics: Condensed Mat- tended solids). In general, one can say that a good calculation will have
ter, 2006 vol. 18 pp. 7999; L Fernández–Seivane and Jaime Ferrer, Phys. high number of k–points, low ElectronicTemperature, extremely small
Rev. Lett. 99, 2007, 183401). SCF.H.Tolerance and high values of MeshCutoff . We encourage the
The inclusion of the SO term in the Hamiltonian (and in the Density user to test carefully these options for each system. An additional point to
Matrix) will involve the increase of non-zero elements in their off-diagonal take into account when the spin–orbit contribution is included is the mix-
0 σσ 0 0
parts, i.e., for some µν orbitals, Hσσ
µν (DMµν ) [σ, σ =↑, ↓] will be 6=0. This ing scheme employed. You are encouraged to use SCF.Mix hamiltonian
is mainly due to the fact that the L · S operator will promote the mixing instead of the density matrix, due to the fact that the convergence speed
between different spin-up/down components. The terms responsible of increases considerably for the first case. In addition, the pseudopotentials
this matrices expansion are the exchange-correlation potential and the SO. have to be well generated and tested for each specific system and they
The remaining terms such as the kinetic energy or Hartree contribution have to be generated in their fully relativistic form and use the non-linear
do not depend of the spin orientations and hence will be only added to core corrections.
the total Hamiltonian (and DM) to their diagonal parts.
Spin.OrbitStrength 1.0 (real)
The current SO formalism enables the possibility of several types of cal- It allows to vary the strength of the spin-orbit interaction from zero
culations: to any positive value, including the physical value. This flag is only

36
 active when Spin is set to spin-orbit. calls to rhoofd, poison, and cellxc), and is turned on by the option
SCF.Want.Variational.EKS.
WriteOrbMom false (logical)
If true, a table is provided in the main output file, which includes • The program now prints a new column labeled “dHmax” for the self-
an estimation of the vector orbital magnetic moments, in units of the consistent cycle. The value represents the maximum absolute value
Bohr magneton, projected onto each orbital and also onto each atom. of the changes in the entries of H, but its actual meaning depends
The estimation for the orbital moments is based on a two-center on whether DM or H mixing is in effect: if mixing the DM, dHmax
approximation, and makes use of the Mulliken population analysis. refers to the change in H(in) with respect to the previous step; if
If MullikenInScf is true, this information is printed at every scf mixing H, dHmax refers to H(out)-H(in) in the previous(?) step.
step. • When achieving convergence, the loop might be exited without a
further mixing of the DM, thus preserving DM(out) for further pro-
6.9 The self-consistent-field loop cessing (including the calculation of forces and the analysis of the
electronic structure) (see the SCF.Mix.AfterConvergence op-
IMPORTANT NOTE: Convergence of the Kohn-Sham energy tion).
and forces
• It remains to be seen whether the forces, being computed “right”
In versions prior to 4.0 of the program, the Kohn-Sham energy was com- on the basis of DM(out), exhibit somehow better convergence as
puted using the “in” DM. The typical DM used as input for the calculation a function of the scf step. In order to gain some more data and
of H was not directly computed from a set of wave-functions (it was ei- heuristics on this we have implemented a force-monitoring option,
ther the product of mixing or of the initialization from atomic values). activated by setting to true the variable SCF.MonitorForces.
In this case, the “kinetic energy” term in the total energy computed in The program will then print the maximum absolute value of the
the way stated in the Siesta paper had an error which decreased with the change in forces from one step to the next. Other statistics could
approach to self-consistency, but was non-zero. The net result was that be implemented.
the Kohn-Sham energy converged more slowly than the “Harris” energy
(which is correctly computed). • While the (mixed) DM is saved at every SCF step, as was standard
practice, the final DM(out) overwrites the .DM file at the end of
When mixing H (see below under “Mixing Options”), the KS energy is in
the SCF cycle. Thus it is still possible to use a “mixed” DM for
effect computed from DM(out), so this error vanishes.
restarting an interrupted loop, but a “good” DM will be used for
As a related issue, the forces and stress computed after SCF convergence any other post-processing.
were calculated using the DM coming out of the cycle, which by default
was the product of a final mixing. This also introduced errors which grew MinSCFIterations 0 (integer)
with the degree of non-selfconsistency. Minimum number of SCF iterations per time step. In MD simulations
The current version introduces several changes: this can with benefit be set to 3.

MaxSCFIterations 1000 (integer)

• When mixing the DM, the Kohn-Sham energy may be corrected to Maximum number of SCF iterations per time step.
make it variational. This involves an extra call to dhscf (although
with neither forces nor matrix elements being calculated, i.e. only SCF.MustConverge true (logical)

37
 Defines the behaviour if convergence is not reached in the maximum density Mix the density matrix.
number of SCF iterations. The default is to stop on the first SCF con-
charge Mix the real-space charge density. Note this is an experimen-
vergence failure. Increasing MaxSCFIterations to a large number
tal feature.
may be advantageous when this is true.
NOTE: Real-space charge density does not follow the regular op-
tions that adhere to density-matrix or Hamiltonian mixing. Also it
6.9.1 Harris functional
is not recommended to use real-space charge density mixing with
Harris.Functional false (logical) TranSIESTA.
Logical variable to choose between self-consistent Kohn-Sham func-
SCF.Mix.Spin all|spinor|sum|sum+diff (string)
tional or non self-consistent Harris functional to calculate energies
Controls how the mixing is performed when carrying out spin-
and forces.
polarized calculations.
• false: Fully self-consistent Kohn-Sham functional.
all Use all spin-components in the mixing
• true: Non self consistent Harris functional. Cheap but pretty
crude for some systems. The forces are computed within the spinor Estimate mixing coefficients using the spinor components
Harris functional in the first SCF step. Only implemented for sum Estimate mixing coefficients using the sum of the spinor compo-
LDA in the Perdew-Zunger parametrization. It really only ap- nents
plies to starting densities which are superpositions of atomic
charge densities. sum+diff Estimate mixing coefficients using the sum and the differ-
ence between the spinor components
When this option is choosen, the values of DM.UseSaveDM,
SCF.MustConverge and SCF.Mix.First are automatically NOTE: This option only influences density-matrix (ρ) or Hamilto-
set falseand MaxSCFIterations is set to 1, no matter what- nian (H) mixing when using anything but the linear mixing scheme.
ever other specification are in the INPUT file. And it does not influence not charge (ρ) mixing.

SCF.Mix.First true (logical)

6.9.2 Mixing options Whether the first SCF should be mixed or it uses the output as input
in the next SCF step. It is generally advised to set this to true, at
Whether a calculation reaches self-consistency in a moderate number of least when restarting calculations.
steps depends strongly on the mixing parameters used. The available
mixing options should be carefully tested for a given calculation type. This In the following the density matrix (ρ) will be used in the equations, while
search for optimal parameters can repay itself handsomely by potentially for Hamiltonian mixing, ρ, should be replaced by the Hamiltonian matrix.
saving many self-consistency steps in production runs. Also we define R[i] = ρiout − ρiin and ∆R[i] = R[i] − R[i − 1].
SCF.Mix Hamiltonian|density|charge (string) SCF.Mixer.Method Pulay|Broyden|Linear (string)
Control what physical quantity to mix in the self-consistent cycle. Choose the mixing algorithm between different methods. Each
The default is mixing the Hamiltonian, which may typically perform method may have different variants, see SCF.Mixer.Variant.
better than density matrix mixing.
Hamiltonian Mix the Hamiltonian matrix (default).

38
Linear A simple linear extrapolation of the input matrix as It should be noted that wi for i > 0 may be chosen arbitrarily.
Comparing with the Pulay mixing scheme it is obvious that Broy-
ρn+1
in = ρnin + w R[n]. (3) den and Pulay are equivalent for a suitable set of parameters.

Pulay Using the Pulay mixing method corresponds using the Kresse SCF.Mixer.Variant original (string)
and Furthmüller [5] variant. It relies on the previous N steps and Choose the variant of the mixing method.
uses those for estimating an optimal input ρn+1in for the following
Pulay This is implemented in two variants:
iteration. The equation can be written as
original|kresse The original6 Pulay mixing scheme, as imple-
N −1
mented in Kresse and Furthmüller [5] .
ρn+1
X
in = ρnin + G R[n] + αi (R[i] + G ∆R[i]), (4)
i=n−N +1 GR The “guaranteed-reduction” variant of Pulay [3] . This variant
has a special convergence path. It interchanges between linear
where G is the damping factor of the Pulay mixing (also known as
and Pulay mixing thus using the exact gradient at each ρnin .
the mixing weight). The values αi are calculated using this formula
For relatively simple systems this may be advantageous to use.
N −1 However, for complex systems it may be worse until it reaches a
A−1
X
αi = − ji h∆R[j]| R[N ]i, (5) convergence basin.
j=1 To obtain the original guaranteed-reduction variant one should
with Aji = h∆R[j]| ∆R[i]i. set SCF.Mixer.<>.weight.linear to 1.
In SIESTA G is a constant, and not a matrix. SCF.Mixer.Weight 0.25 (real)
NOTE: Pulay mixing is a special case of Broyden mixing, see the The mixing weight used to mix the quantity. In the linear mixing
Broyden method. case this refers to
Broyden The Broyden mixing is mixing method relying on the pre- ρn+1
in = ρnin + w R[n]. (11)
vious N steps in the history for calculating an optimum input ρn+1
in For details regarding the other methods please see
for the following iteration. The equation can be written as SCF.Mixer.Method.
N −1 N −1
ρn+1 = ρnin + G R[n] −
X X
wi wj cj βij (R[i] + G ∆R[i]), SCF.Mixer.History 2 (integer)
in
i=n−N +1 j=n−N +1 Number of previous SCF steps used in estimating the following input.
(6) Increasing this number, typically, increases stability and a number of
where G is the damping factor (also known as the mixing weight). around 6 or above may be advised.
The values weights may be expressed by
SCF.Mixer.Kick 0 (integer)
wi = 1 , for i > 0 (7) After every N SCF steps a linear mix is inserted to kick the SCF
ci = h∆R[i]| R[n]i, (8) cycle out of a possible local minimum.

−1 i
As such the “original” version is a variant it-self. But this is more stable in the far
h 6
βij = w02 I + A (9)
ij majority of cases.
Aij = wi wj h∆R[i]| ∆R[j]i. (10)

39
 The mixing weight for this linear kick is determined by In conjunction with the above simple settings controlling the SCF cycle
SCF.Mixer.Kick.Weight. SIESTA employs a very configurable mixing scheme. In essence one
may switch mixing methods, arbitrarily, during the SCF cycle via control
SCF.Mixer.Kick.Weight 〈SCF.Mixer.Weight〉 (real) commands. This can greatly speed up convergence.
The mixing weight for the linear kick (if used).
%block SCF.Mixers 〈None〉 (block)
SCF.Mixer.Restart 0 (integer) Each line in this block defines a separate mixer that is defined in a
When using advanced mixers (Pulay/Broyden) the mixing scheme subsequent SCF.Mixer.<> block.
may periodically restart the history. This may greatly improve The first line is the initial mixer used.
the convergence path as local constraints in the minimization pro-
See the following options for controlling individual mixing methods.
cess are periodically removed. This method has similarity to the
method proposed in Banerjee et al. [2] and is a special case of the NOTE: If this block is defined you must define all mixing parameters
SCF.Mixer.Kick method. individually.
Please see SCF.Mixer.Restart.Save which is advised to be set %block SCF.Mixer.<> 〈None〉 (block)
simultaneously. This block controls the mixer named <>.
SCF.Mixer.Restart.Save 1 (integer) method Define the method for the mixer, see SCF.Mixer.Method
When restarting the history of saved SCF steps one may choose for possible values.
to save a subset of the latest history steps. When using
variant Define the variant of the method, see SCF.Mixer.Variant
SCF.Mixer.Restart it is encouraged to also save a couple of pre-
for possible values.
vious history steps.
weight|w Define the mixing weight for the mixing scheme, see
SCF.Mixer.Linear.After -1 (integer) SCF.Mixer.Weight.
After reaching convergence one may run additional SCF cycles using
history Define number of previous history steps used in the mini-
a linear mixing scheme. If this has a value ≥ 0 SIESTA will perform
mization process, see SCF.Mixer.History.
linear mixing after it has converged using the regular mixing method
(SCF.Mixer.Method). weight.linear|w.linear Define the linear mixing weight for the mix-
The mixing weight for this linear mixing is controlled by ing scheme. This only has meaning for Pulay or Broyden mixing.
SCF.Mixer.Linear.After.Weight. It defines the initial linear mixing weight.
To obtain the original Pulay Guarenteed-Reduction variant one
SCF.Mixer.Linear.After.Weight 〈SCF.Mixer.Weight〉 (real) should set this to 1.
After reaching convergence one may run additional SCF cycles using
restart Define the periodic restart of the saved history, see
a linear mixing scheme. If this has a value ≥ 0 SIESTA will perform
SCF.Mixer.Restart.
linear mixing after it has converged using the regular mixing method
(SCF.Mixer.Method). restart.save Define number of latest history steps retained when
The mixing weight for this linear mixing is controlled by restarting the history, see SCF.Mixer.Restart.Save.
SCF.Mixer.Linear.After.Weight. iterations Define the maximum number of iterations this mixer
should run before changing to another mixing method.

40
 NOTE: This must be used in conjunction with the next setting.
%block SCF.Mixer.init
next <> Specify the name of the next mixing scheme after having method pulay
conducted iterations SCF cycles using this mixing method. weight 0.05
next.conv <> If SCF convergence is reached using this mixer, history 10
restart 25
switch to the mixing scheme via <>. Then proceed with the
restart.save 4
SCF cycle. next.conv final
next.p If the relative difference between the latest two residuals is %endblock
below this quantity, the mixer will switch to the method given in
%block SCF.Mixer.final
next. Thus if method linear
hR[i]| R[i]i − hR[i − 1]| R[i − 1]i weight 0.1
< next.p (12) %endblock
hR[i − 1]| R[i − 1]i

is fulfilled it will skip to the next mixer. This advanced setup may be used to change mixers during the SCF to
change certain parameters of the mixing method, or fully change the
restart.p If the relative difference between the latest two residuals is
method for mixing. For instance it may be advantageous to increase the
below this quantity, the mixer will restart the history. Thus if
mixing weight once a certain degree of self-consistency has been reached.
hR[i]| R[i]i − hR[i − 1]| R[i − 1]i In the following example we change the mixing method to a different
< restart.p (13) scheme by increasing the weight and decreasing the history steps:
hR[i − 1]| R[i − 1]i

is fulfilled it will reset the history. %block SCF.Mixers

init
The options covered now may be exemplified in these examples. If the final
input file contains: %endblock

SCF.Mixer.Method pulay %block SCF.Mixer.init

SCF.Mixer.Weight 0.05 method pulay
SCF.Mixer.History 10 weight 0.05
SCF.Mixer.Restart 25 history 10
SCF.Mixer.Restart.Save 4 next final
SCF.Mixer.Linear.After 0 # Switch when the relative residual goes below 5%
SCF.Mixer.Linear.After.Weight 0.1 next.p 0.05
%endblock
This may be equivalently setup using the more advanced input blocks:
%block SCF.Mixer.final
method pulay
%block SCF.Mixers weight 0.1
init history 6
final %endblock
%endblock

41
In essence, very complicated schemes of convergence may be created using dhscf for correction of the variational character of the Kohn-Sham
the block’s input. energy)
The following options refer to the global treatment of how/when mixing • The “in” and “out” charges are mixed (see below), and the resulting
should be performed. “in” fourier components are used by dhscf in successive iterations
Compat.Pre-v4-DM-H false (logical) to reconstruct the charge density.
This controls the default values of SCF.Mix.AfterConvergence, • The new arrays needed and the processing of most new options is
SCF.RecomputeHAfterScf and SCF.Mix.First. done in the new module m_rhog.F90. The fourier-transforms are
In versions prior to v4 the two former options where defaulted to carried out by code in rhofft.F.
true while the latter option was defaulted to false.
• Following standard practice, two options for mixing are offered:
SCF.Mix.AfterConvergence false (logical)
– A simple Kerker mixing, with an optional Thomas-Fermi
Indicate whether mixing is done in the last SCF cycle (after con-
wavevector to damp the contributions for small G’s. The over-
vergence has been achieved) or not. Not mixing after convergence
all mixing weight is the same as for other kinds of mixing, read
improves the quality of the final Kohn-Sham energy and of the forces
from DM.MixingWeight.
when mixing the DM.
– A DIIS (Pulay) procedure that takes into account a sub-set of
NOTE: See Compat.Pre-v4-DM-H.
the G vectors (those within a smaller cutoff). Optionally, the
SCF.RecomputeHAfterSCF false (logical) scalar product used for the construction of the DIIS matrix
Indicate whether the Hamiltonian is updated after the scf cycle, while from the residuals uses a weight factor.
computing the final energy, forces, and stresses. Not recomputing The DIIS extrapolation is followed by a Kerker mixing step.
H makes further analysis tasks (such as the computation of band The code is m_diis.F90. The DIIS history is kept in a circu-
structures) more consistent, as they will be able to use the same H lar stack, implemented using the new framework for reference-
used to generate the last density matrix. counted types. This might be overkill for this particular use,
NOTE: See Compat.Pre-v4-DM-H. and there are a few rough edges, but it works well.

The default convergence criteria remains based on the differences in the

6.9.3 Mixing of the Charge Density
density matrix, but in this case the differences are from step to step,
not the more fundamental DM_out-DM_in. Perhaps some other criterion
See SCF.Mix on how to enable charge density mixing. If charge den-
should be made the default (max |∆rho(G)|, convergence of the free-
sity mixing is enabled the fourier components of the charge density are
energy...)
mixed, as done in some plane-wave codes. (See for example Kresse and
Furthmüller, Comp. Mat. Sci. 6, 15-50 (1996), KF in what follows.) Note that with charge mixing the Harris energy as it is currently computed
in Siesta loses its meaning, since there is no DM_in. The program prints
The charge mixing is implemented roughly as follows:
zeroes in the Harris energy field.
• The charge density computed in dhscf is fourier-transformed and Note that the KS energy is correctly computed throughout the scf cycle,
stored in a new module. This is done both for “ρ(G)(in)” and as there is an extra step for the calculation of the charge stemming from
“ρ(G)(out)” (the “out” charge is computed during the extra call to DM_out, which also updates the energies. Forces and final energies are

42
correctly computed with the final DM_out, regardless of the setting of the the master node.
option for mixing after scf convergence.
Debug.DIIS false (logical)
Initial tests suggest that charge mixing has some desirable properties and
Controls the level of debugging output in the DIIS procedure. If set,
could be a drop-in replacement for density-matrix mixing, but many more
the program prints the DIIS matrix and the extrapolation coefficients.
tests are needed to calibrate its efficiency for different kinds of systems,
and the heuristics for the (perhaps too many) parameters: SCF.MixCharge.SCF1 false (logical)
Logical variable to indicate whether or not the charge is mixed in
SCF.Kerker.q0sq 0 Ry (energy)
2 the first SCF cycle. Anecdotal evidence indicates that it might be
Determines the parameter q0 featuring in the Kerker preconditioning,
advantageous, at least for calculations started from scratch, to avoid
which is always performed on all components of ρ(G), even those
that first mixing, and retain the “out” charge density as “in” for the
treated with the DIIS scheme.
next step.
SCF.RhoGMixingCutoff 9 Ry (energy)
Determines the sub-set of G vectors which will undergo the DIIS 6.9.4 Initialization of the density-matrix
procedure. Only those with kinetic energies below this cutoff will be
considered. The optimal extrapolation of the ρ(G) elements will be NOTE: The conditions and options for density-matrix re-use are quite
replaced in the fourier series before performing the Kerker mixing. varied and not completely orthogonal at this point. For further informa-
tion, see routine Src/m_new_dm.F. What follows is a summary.
SCF.RhoG.DIIS.Depth 0 (integer)
The Density matrix can be:
Determines the maximum number of previous steps considered in the
DIIS procedure.
1. Synthesized directly from atomic occupations.
NOTE: The information from the first scf step is not included in the DIIS (See the options below for spin considerations)
history. There is no provision yet for any other kind of “kick-starting” 2. Read from a .DM file (if the appropriate options are set)
procedure. The logic is in m_rhog (rhog_mixing routine). 3. Extrapolated from previous geometry steps
(this includes as a special case the re-use of the DM
SCF.RhoG.Metric.Preconditioner.Cutoff 〈None〉 (energy)
2
of the previous geometry iteration)
Determines the value of q1 in the weighing of the different G compo-
nents in the scalar products among residuals in the DIIS procedure. In cases 2 and 3, the structure of the read or extrapolated DM
Following the KF ansatz, this parameter is chosen so that the smallest is automatically adjusted to the current sparsity pattern.
(non-zero) G has a weight 20 times larger than that of the smallest
G vector in the DIIS set. In what follows, "Initialization" of the DM means that the DM is
The default is the result of the KF prescription. either read from file (if available) or synthesized from atomic
data. This is confusing, and better terminology should be used.
SCF.DebugRhoGMixing false (logical)
Controls the level of debugging output in the mixing procedure (ba-
sically whether the first few stars worth of Fourier components are Special cases:
printed). Note that this feature will only display the components in

43
 Harris functional: The matrix is always initialized polarized, and beyond, see Spin for details.

Force calculation: The DM should be written to disk DM.Init.Unfold true (logical)

depends on: DM.UseSaveDM
at the time of the "no displacement"
calculation and read from file at When reading the DM from a previous calculation there may be
every subsequent step. inconsistencies in the auxiliary supercell. E.g. if the previous calcu-
lation did not use an auxiliary supercell and the current calculation
Variable-cell calculation: does (adding k-point sampling). SIESTA will automatically unfold
the Γ-only DM to the auxiliary supercell elements (if true).
If the auxiliary cell changes, the DM is forced to be For false the DM elements are assumed to originate from an auxiliary
supercell calculation and the sparse elements are not unfolded but
synthesized (conceivably one could rescue some important
information from an old DM, but it is too much troubledirectly copied.
NOTE: Generally this shouldn’t not be touched, however, if the
for now). NOTE that this is a change in policy with respect
initial DM is generated using sisl [11] and only on-site DM elements
to previous versions of the program, in which a (blind?)
are set, this should be set to false.
re-use was allowed, except if ’ReInitialiseDM’ was ’true’.
Now ’ReInitialiseDM’ is ’true’ by default. Setting it to
’false’ is not recommended. DM.FormattedFiles false (logical)
Setting this alters the default for DM.FormattedInput and
In all other cases (including "server operation"), theDM.FormattedOutput. Instructs to use formatted files for read-
ing and writing the density matrix. In this case, the files are labelled
default is to allow DM re-use (with possible extrapolation)
from previous geometry steps. SystemLabel.DMF.
Only usable if one has problems transferring files from one computer
to another.
For "CG" calculations, the default is not to extrapolate the
DM (unless requested by setting ’DM.AllowExtrapolation’ to
"true"). The previous step’s DM is reused. DM.FormattedInput false (logical)
Instructs to use formatted files for reading the density matrix.
The fdf variables ’DM.AllowReuse’ and ’DM.AllowExtrapolation’
DM.FormattedOutput false (logical)
can be used to turn off DM re-use and extrapolation.
Instructs to use formatted files for writing the density matrix.

DM.InitSpin.AF false (logical)

DM.UseSaveDM false (logical)
It defines the initial spin density for a spin polarized calculation. The
Instructs to read the density matrix stored in file SystemLabel..DM spin density is initially constructed with the maximum possible spin
by a previous run. polarization for each atom in its atomic configuration. This variable
SIESTA will continue even if .DM is not found. defines the relative orientation of the atomic spins:
NOTE: That if the spin settings has changed SIESTA allows read- If false the initial spin-configuration is a ferromagnetic order (all
ing a .DM from a similar calculation with different Spin option. This spins up). If true all odd atoms are initialized to spin-up, all even
may be advantageous when going from non-polarized calculations to atoms are initialized to spin-down.

44
%block DM.InitSpin 〈None〉 (block) This is default true for molecular-dynamics simulations, but false,
Define the initial spin density for a spin polarized calculation atom for now, for geometry-relaxations (pending further tests which users
by atom. In the block there is one line per atom to be spin-polarized, are kindly requested to perform).
containing the atom index (integer, ordinal in the block Atom-
DM.History.Depth 1 (integer)
icCoordinatesAndAtomicSpecies) and the desired initial spin-
polarization (real, positive for spin up, negative for spin down). A Sets the number of geometry steps for which density-matrix informa-
value larger than possible will be reduced to the maximum possible tion is saved for extrapolation.
polarization, keeping its sign. Maximum polarization can also be
given by introducing the symbol + or - instead of the polarization 6.9.5 Initialization of the SCF cycle with charge densities
value. There is no need to include a line for every atom, only for
those to be polarized. The atoms not contemplated in the block will SCF.Read.Charge.NetCDF false (logical)
be given non-polarized initialization. Instructs SIESTA to read the charge density stored in the netCDF
For non-colinear spin, the spin direction may be specified for each file Rho.IN.grid.nc. This feature allows the easier re-use of
atom by the polar angle θ and the azimuthal angle φ (using the electronic-structure information from a previous run. It is not nec-
physics ISO convention), given as the last two arguments in degrees. essary that the basis sets are “similar” (a requirement if density-
If not specified, θ = 0 is assumed (z-polarized). Spin must be set to matrices are to be read in).
use non-colinear or spin-orbit for the directions to have effect. NOTE: This is an experimental feature. Until robust checks are
Example: implemented, care must be taken to make sure that the FFT grids
in the .grid.nc file and in SIESTA are the same.
%block DM.InitSpin
5 -1. 90. 0. SCF.Read.Deformation.Charge.NetCDF
# Atom index, spin, theta, phi (deg) false (logical)
3 + 45. -90. Instructs Siesta to read the deformation charge density stored in the
7 -
netCDF file DeltaRho.IN.grid.nc. This feature allows the easier re-
%endblock DM.InitSpin
use of electronic-structure information from a previous run. It is not
In the above example, atom 5 is polarized in the x-direction. necessary that the basis sets are “similar” (a requirement if density-
If this block is defined, but empty, all atoms are not polarized. This matrices are to be read in). The deformation charge is particularly
block has precedence over DM.InitSpin.AF. useful to give a good starting point for slightly different geometries.
NOTE: This is an experimental feature. Until robust checks are
DM.AllowReuse true (logical)
implemented, care must be taken to make sure that the FFT grids
Controls whether density matrix information from previous geometry in the .grid.nc file and in Siesta are the same.
iterations is re-used to start the new geometry’s SCF cycle.

DM.AllowExtrapolation true (logical) 6.9.6 Output of density matrix and Hamiltonian

Controls whether the density matrix information from several previ-
ous geometry iterations is extrapolated to start the new geometry’s Performance Note: For large-scale calculations, writing the DM at
SCF cycle. This feature is useful for molecular dynamics simulations every scf step can have a severe impact on performance. The sparse-
and possibly also for geometry relaxations. The number of geometry matrix I/O is undergoing a re-design, to facilitate the analysis of data
steps saved is controlled by the variable DM.History.Depth. and to increase the efficiency.

45
Use.Blocked.WriteMat false (logical) Write.H false (logical)
By using blocks of orbitals (according to the underlying default block- Whether restart Hamiltonians should be written (not intrinsically
cyclic distribution), the sparse-matrix I/O can be speeded-up signif- supported in 4.1).
icantly, both by saving MPI communication and by reducing the If true these files will be created; H_MIXED or H_DMGEN which is the
number of file accesses. This is essential for large systems, for which mixed or the generated Hamiltonian from the current density matrix,
the I/O could take a significant fraction of the total computation respectively. If Use.Blocked.WriteMat the just mentioned files
time. will have the additional suffix .blocked.
To enable this “blocked format” (recommended for large-scale calcu-
lations) use the option Use.Blocked.WriteMat true. Note that it Write.H.end.of.cycle 〈Write.H〉 (logical)
is off by default. Equivalent to Write.H, but will only write at the end of each SCF
The new format is not backwards compatible. A converter program loop.
(Util/DensityMatrix/dmUnblock.F90) has been written to post- NOTE: The file generated depends on
process those files intended for further analysis or re-use in Siesta. SCF.Mix.AfterConvergence.
This is the best option for now, since it allows liberal checkpointing
The following options control the creation of netCDF files. The relevant
with a much smaller time consumption, and only incurs costs when
routines have not been optimized yet for large-scale calculations, so in
re-using or analyzing files.
this case the options should not be turned on (they are off by default).
Note that TranSIESTA will continue to produce SystemLabel.DM
files, in the old format (See save_density_matrix.F) Write.DM.NetCDF true (logical)
To test the new features, the option S.Only true can be used. It It determines whether the density matrix (after the mixing step) is
will produce three files: a standard one, another one with optimized output as a DM.nc netCDF file or not.
MPI communications, and a third, blocked one. The file is overwritten at every SCF step. Use the
Write.DM.History.NetCDF option if a complete history is de-
Write.DM true (logical)
sired.
Control the creation of the current iterations density matrix to a file
The DM.nc and standard DM file formats can be converted at will
for restart purposes and post-processing. If false nothing will be
with the programs in Util/DensityMatrix directory. Note that the
written.
DM values in the DM.nc file are in single precision.
If Use.Blocked.WriteMat is false the SystemLabel.DM file will
be written. Otherwise these density matrix files will be created; Write.DMHS.NetCDF true (logical)
DM_MIXED.blocked and DM_OUT.blocked which are the mixed and If true, the input density matrix, Hamiltonian, and output density
the diagonalization output, respectively. matrix, are stored in a netCDF file named DMHS.nc. The file also
contains the overlap matrix S.
Write.DM.end.of.cycle 〈Write.DM〉 (logical)
The file is overwritten at every SCF step. Use the
Equivalent to Write.DM, but will only write at the end of each SCF
Write.DMHS.History.NetCDF option if a complete history is de-
loop.
sired.
NOTE: The file generated depends on
SCF.Mix.AfterConvergence. Write.DM.History.NetCDF false (logical)
If true, a series of netCDF files with names of the form DM-NNNN.nc

46
 is created to hold the complete history of the density matrix (after Tolerance for unnormalized density matrices (typically the product of
mixing). (See also Write.DM.NetCDF). Each file corresponds to solvers such as PEXSI which have a built-in electron-count tolerance).
a geometry step. If this tolerance is exceeded, the program stops. It is understood as
a fractional tolerance. For example, the default will allow an excess
Write.DMHS.History.NetCDF false (logical) or shorfall of 0.01 electrons in a 1000-electron system.
If true, a series of netCDF files with names of the form
DMHS-NNNN.nc is created to hold the complete history of the in- SCF.H.Converge true (logical)
put and output density matrix, and the Hamiltonian. (See also Logical variable to use the Hamiltonian matrix elements as moni-
Write.DMHS.NetCDF). Each file corresponds to a geometry step. tor of self-consistency: this is considered achieved when the max-
The overlap matrix is stored only once per SCF cycle. imum absolute change (dHmax) in the H matrix elements is be-
low SCF.H.Tolerance. The actual meaning of dHmax depends on
Write.TSHS.History false (logical) whether DM or H mixing is in effect: if mixing the DM, dHmax refers
If true, a series of TSHS files with names of the form to the change in H(in) with respect to the previous step; if mixing H,
SystemLabel.N.TSHS is created to hold the complete history of the dHmax refers to H(out)-H(in) in the previous(?) step.
Hamiltonian and overlap matrix. Each file corresponds to a geometry
step. The overlap matrix is stored only once per SCF cycle. This SCF.H.Tolerance 10−3 eV (energy)
option only works with TranSIESTA. depends on: SCF.H.Converge
If SCF.H.Converge is true, then self-consistency is achieved when
the maximum absolute change in the Hamiltonian matrix elements
6.9.7 Convergence criteria
is below this value.
NOTE: The older options with a DM prefix is still working for backwards SCF.EDM.Converge true (logical)
compatibility. However, the following flags has precedence. Logical variable to use the energy density matrix elements as monitor
Note that all convergence criteria are additive and may thus be used of self-consistency: this is considered achieved when the maximum
simultaneously for complete control. absolute change (dEmax) in the energy density matrix elements is
below SCF.EDM.Tolerance. The meaning of dEmax is equivalent
SCF.DM.Converge true (logical) to that of SCF.DM.Tolerance.
Logical variable to use the density matrix elements as monitor of
self-consistency. SCF.EDM.Tolerance 10−3 eV (energy)
depends on: SCF.EDM.Converge
SCF.DM.Tolerance 10−4 (real) If SCF.EDM.Converge is true, then self-consistency is achieved
depends on: SCF.DM.Converge
when the maximum absolute change in the energy density matrix
Tolerance of Density Matrix. When the maximum difference between elements is below this value.
the output and the input on each element of the DM in a SCF cycle
is smaller than SCF.DM.Tolerance, the self-consistency has been SCF.FreeE.Converge false (logical)
achieved. Logical variable to request an additional requirement for self-
NOTE: DM.Tolerance is the actual default for this flag. consistency: it is considered achieved when the change in the to-
tal (free) energy between cycles of the SCF procedure is below
DM.Normalization.Tolerance 10−5 (real)

47
 SCF.FreeE.Tolerance and the density matrix change criterion is mined by its plane-wave cutoff, as given by the MeshCutoff option. It
also satisfied. means that all periodic plane waves with kinetic energy lower than this
cutoff can be represented in the grid without aliasing. In turn, this im-
SCF.FreeE.Tolerance 10−4 eV (energy) plies that if a function (e.g. the density or the effective potential) is an
depends on: SCF.FreeE.Converge
expansion of only these plane waves, it can be Fourier transformed back
If SCF.FreeE.Converge is true, then self-consistency is achieved and forth without any approximation.
when the change in the total (free) energy between cycles of the SCF
procedure is below this value and the density matrix change criterion The existence of the grid causes the breaking of translational symmetry
is also satisfied. (the egg-box effect, due to the fact that the density and potential do have
plane wave components above the mesh cutoff). This symmetry breaking
SCF.Harris.Converge false (logical) is clear when moving one single atom in an otherwise empty simulation
Logical variable to use the Harris energy as monitor of self- cell. The total energy and the forces oscillate with the grid periodicity
consistency: this is considered achieved when the change in the when the atom is moved, as if the atom were moving on an eggbox. In
Harris energy between cycles of the SCF procedure is below the limit of infinitely fine grid (infinite mesh cutoff) this effect disappears.
SCF.Harris.Tolerance. This is useful if only energies are needed, For reasonable values of the mesh cutoff, the effect of the eggbox on
as the Harris energy tends to converge faster than the Kohn-Sham en- the total energy or on the relaxed structure is normally unimportant.
ergy. The user is responsible for using the correct energies in further However, it can affect substantially the process of relaxation, by increasing
processing, e.g., the Harris energy if the Harris criterion is used. the number of steps considerably, and can also spoil the calculation of
To help in basis-optimization vibrations, usually much more demanding than relaxations.
tasks, a new file BASIS_HARRIS_ENTHALPY is provided, holding the
The Util/Scripting/eggbox_checker.py script can be used to diagnose
same information as BASIS_ENTHALPY but using the Harris energy
the eggbox effect to be expected for a particular pseudopotential/basis-set
instead of the Kohn-Sham energy.
combination.
NOTE: Setting this to true makes SCF.DM.Converge
SCF.H.Converge default to false. Apart from increasing the mesh cutoff (see the MeshCutoff option), the
following options might help in lessening a given eggbox problem. But
SCF.Harris.Tolerance 10−4 eV (energy) note also that a filtering of the orbitals and the relevant parts of the
depends on: SCF.Harris.Converge pseudopotential and the pseudocore charge might be enough to solve the
If SCF.Harris.Converge is true, then self-consistency is achieved issue (see Sec. 6.3.9).
when the change in the Harris energy between cycles of the SCF
MeshCutoff 300 Ry (energy)
procedure is below this value. This is useful if only energies are
needed, as the Harris energy tends to converge faster than the Kohn- Defines the plane wave cutoff for the grid.
Sham energy. MeshSubDivisions 2 (integer)
Defines the number of sub-mesh points in each direction used to save
index storage on the mesh. It affects the memory requirements and
6.10 The real-space grid and the eggbox-effect the CPU time, but not the results.
NOTE: The default value might be a bit conservative. Users might
SIESTA uses a finite 3D grid for the calculation of some integrals and
experiment with higher values, 4 or 6, to lower the memory and
the representation of charge densities and potentials. Its fineness is deter-

48
 cputime usage. 0.5 0.5 0.5
%endblock Grid.CellSampling
%block Grid.CellSampling 〈None〉 (block)
gives again a cubic sampling with half the original side length. It is
It specifies points within the grid cell for a symmetrization sampling.
not trivial to choose a right set of displacements so as to maximize
For a given grid the grid-cutoff convergence can be improved (and the
the new ’effective’ cutoff. It depends on the kind of cell. It may
eggbox lessened) by recovering the lost symmetry: by symmetrizing
be automatized in the future, but it is now left to the user, who
the sensitive quantities. The full symmetrization implies an integra-
introduces the displacements manually through this block.
tion (averaging) over the grid cell. Instead, a finite sampling can be
The quantities which are symmetrized are: (i) energy terms that
performed.
depend on the grid, (ii) forces, (iii) stress tensor, and (iv) electric
It is a sampling of rigid displacements of the system with respect
dipole.
to the grid. The original grid-system setup (one point of the grid
The symmetrization is performed at the end of every SCF cycle.
at the origin) is always calculated. It is the (0,0,0) displacement.
The whole cycle is done for the (0,0,0) displacement, and, when the
The block Grid.CellSampling gives the additional displacements
density matrix is converged, the same (now fixed) density matrix is
wanted for the sampling. They are given relative to the grid-cell
used to obtain the desired quantities at the other displacements (the
vectors, i.e., (1,1,1) would displace to the next grid point across the
density matrix itself is not symmetrized as it gives a much smaller
body diagonal, giving an equivalent grid-system situation (a useless
egg-box effect). The CPU time needed for each displacement in the
displacement for a sampling).
Grid.CellSampling block is of the order of one extra SCF iteration.
Examples: Assume a cubic cell, and therefore a (smaller) cubic grid
This may be required in systems where very precise forces are needed,
cell. If there is no block or the block is empty, then the original
and/or if partial cores are used. It is advantageous to test whether
(0,0,0) will be used only. The block:
the forces are sampled sufficiently by sampling one point.
%block Grid.CellSampling Additionally this may be given as a list of 3 integers which corre-
0.5 0.5 0.5
sponds to a “Monkhorst-Pack” like grid sampling. I.e.
%endblock Grid.CellSampling
Grid.CellSampling [2 2 2]
would use the body center as a second point in the sampling. Or:
is equivalent to
%block Grid.CellSampling
0.5 0.5 0.0 %block Grid.CellSampling
0.5 0.0 0.5 0.5 0.0 0.0
0.0 0.5 0.5 0.0 0.5 0.0
%endblock Grid.CellSampling 0.5 0.5 0.0
0.0 0.0 0.5
gives an fcc kind of sampling, and 0.5 0.0 0.5
%block Grid.CellSampling 0.0 0.5 0.5
0.5 0.0 0.0 0.5 0.5 0.5
0.0 0.5 0.0 %endblock Grid.CellSampling
0.0 0.0 0.5
0.0 0.5 0.5
This is an easy method to see if the flag is important for your system
0.5 0.0 0.5 or not.
0.5 0.5 0.0

49
%block EggboxRemove 〈None〉 (block) 1 0 1 1 -0.00015
For recovering translational invariance in an approximate way. 1 1 0 0 0.00035
1 1 0 1 -0.00017
It works by substracting from Kohn-Sham’s total energy (and forces) 2 0 0 0 -270.81903
an approximation to the eggbox energy, sum of atomic contributions. 2 0 0 1 0.00015
Each atom has a predefined eggbox energy depending on where it 2 0 1 0 0.00024
sits on the cell. This atomic contribution is species dependent and 2 1 0 0 0.00035
is obviously invariant under grid-cell translations. Each species con- 2 1 0 1 -0.00077
tribution is thus expanded in the appropriate Fourier series. It is 2 1 1 0 -0.00075
important to have a smooth eggbox, for it to be represented by a 2 1 1 1 -0.00002
%endblock EggBoxRemove
few Fourier components. A jagged egg-box (unless very small, which
is then unimportant) is often an indication of a problem with the It represents an alternative to grid-cell sampling (above). It is only
pseudo. approximate, but once the Fourier components for each species are
In the block there is one line per Fourier component. The first in- given, it does not represent any computational effort (neither memory
teger is for the atomic species it is associated with. The other three nor time), while the grid-cell sampling requires CPU time (roughly
represent the reciprocal lattice vector of the grid cell (in units of the one extra SCF step per point every MD step).
basis vectors of the reciprocal cell). The real number is the Fourier It will be particularly helpful in atoms with substantial partial core
coefficient in units of the energy scale given in EggboxScale (see or semicore electrons.
below), normally 1 eV. NOTE: This should only be used for fixed cell calculations, i.e. not
The number and choice of Fourier components is free, as well as their with MD.VariableCell.
order in the block. One can choose to correct only some species and For the time being, it is up to the user to obtain the Fourier
not others if, for instance, there is a substantial difference in hardness components to be introduced. They can be obtained by moving
of the cores. The 0 0 0 components will add a species-dependent one isolated atom through the cell to be used in the calculation
constant energy per atom. It is thus irrelevant except if comparing (for a give cell size, shape and mesh), once for each species. The
total energies of different calculations, in which case they have to be Util/Scripting/eggbox_checker.py script can be used as a starting
considered with care (for instance by putting them all to zero, i.e. by point for this.
not introducing them in the list). The other components average to
zero representing no bias in the total energy comparisons. EggboxScale 1 eV (energy)
If the total energies of the free atoms are put as 0 0 0 coefficients Defines the scale in which the Fourier components of the egg-box
(with spin polarisation if adequate etc.) the corrected total energy energy are given in the EggboxRemove block.
will be the cohesive energy of the system (per unit cell).
Example: For a two species system, this example would give a quite 6.11 Matrix elements of the Hamiltonian and overlap
sufficent set in many instances (the actual values of the Fourier coef-
ficients are not realistic). NeglNonOverlapInt false (logical)
Logical variable to neglect or compute interactions between orbitals
%block EggBoxRemove
1 0 0 0 -143.86904 which do not overlap. These come from the KB projectors. Neglect-
1 0 0 1 0.00031 ing them makes the Hamiltonian more sparse, and the calculation
1 0 1 0 0.00016 faster.

50
 NOTE: Use with care! ForceAuxCell false (logical)
If true, the program uses an auxiliary cell even for gamma-point-only
SaveHS false (logical)
calculations. This might be needed for COOP/COHP calculations,
Instructs to write the Hamiltonian and overlap matrices, as well as noted above, or in degenerate cases, such as when the cell is so
as other data required to generate bands and density of states, in small that a given orbital “self-interacts” with its own images (via
file SystemLabel.HSX. The .HSX format is more compact than the direct overlap or through a KB projector). In this case, the diagonal
traditional .HS, and the Hamiltonian, overlap matrix, and relative- value of the overlap matrix S for this orbital is different from 1, and
positions array (which is always output, even for gamma-point only an initialization of the DM via atomic data would be faulty. The
calculations) are in single precision. program corrects the problem to zeroth-order by dividing the DM
The program hsx2hs in Util/HSX can be used to generate an old- value by the corresponding overlap matrix entry, but the initial charge
style .HS file if needed. density would exhibit distortions from a true atomic superposition
SIESTA produces also an .HSX file if the COOP.Write option is (See routine m_new_dm.F). The distortion of the charge density is a
active. serious problem for Harris functional calculations, so this option must
See also the Write.DMHS.NetCDF and be enabled for them if self-folding is present. (Note that this should
Write.DMHS.History.NetCDF options. not happen in any serious calculation...)

Compat.Matel.NRTAB false (logical)

Internally the two-center integrals involved in some matrix element 6.12 Calculation of the electronic structure
calculations are tabulated with a preset number of elements. In ver-
SIESTA can use three qualitatively different methods to determine the
sions 4.0.1 and prior this was 128. Since 4.0.2 the number of table
electronic structure of the system. The first is standard diagonalization,
elements has been increased to 1024, which translates to more accu-
which works for all systems and has a cubic scaling with the size. The
rate matrix element calculations.
second is based on the direct minimization of a special functional over
This compatibility option should only be used when preservation of a set of trial orbitals. These orbitals can either extend over the entire
the (lower accuracy) numerical results of 4.0.1 or prior versions is system, resulting in a cubic scaling algorithm, or be constrained within
required for reproducibility purposes. a localization radius, resulting in a linear scaling algorithm. The former
is a recent implementation (described in 6.12.4), that can be viewed as
6.11.1 The auxiliary supercell an equivalent approach to diagonalization in terms of the accuracy of the
solution; the latter is the historical O(N) method used by SIESTA (de-
When using k-points, this auxiliary supercell is needed to compute prop- scribed in 6.12.5); it scales in principle linearly with the size of the system
erly the matrix elements involving orbitals in different unit cells. It is (only if the size is larger than the radial cutoff for the local solution wave-
computed automatically by the program at every geometry step. functions), but is quite fragile and substantially more difficult to use, and
Note that for gamma-point-only calculations there is an implicit “folding” only works for systems with clearly separated occupied and empty states.
of matrix elements corresponding to the images of orbitals outside the unit The default is to use diagonalization. The third method (PEXSI) is based
cell. If information about the specific values of these matrix elements is on the pole expansion of the Fermi-Dirac function and the direct compu-
needed (as for COOP/COHP analysis), one has to make sure that the tation of the density matrix via an efficient scheme of selected inversion
unit cell is large enough, or force the use of an aunxiliary supercell. (see Sec 6.13).

51
The calculation of the H and S matrix elements is always done with an number of orbitals above the Fermi level for zero temperature. I.e.
O(N) method. The actual scaling is not linear for small systems, but it if −2 is specified for a system with 20 orbitals and 10 electrons it is
becomes O(N) when the system dimensions are larger than the scale of equivalent to 12.
orbital rc ’s. Using this option can greatly speed up your calculations if used cor-
The relative importance of both parts of the computation (matrix ele- rectly.
ments and solution) depends on the size and quality of the calculation. NOTE: If experiencing PDORMTR errors in Γ calculations with
The mesh cutoff affects only the matrix-element calculation; orbital cut- MRRR algorithm, it is because of a buggy ScaLAPACK implemen-
off radii affect the matrix elements and all solvers except diagonalization; tation, simply use another algorithm.
the need for k-point sampling affects the solvers only, and the number of NOTE: This only affects the MRRR, ELPA and Expert diago-
basis orbitals affects them all. nalization routines.
In practice, the vast majority of users employ diagonalization (or the Diag.UseNewDiagk false (logical)
OMM method) for the calculation of the electronic structure. This is so
Selects whether a more efficient diagonalization routine (with inter-
because the vast majority of calculations (done for intermediate system
mediate storage of eigenvectors in NetCDF format) is used for the
sizes) would not benefit from the O(N) or PEXSI solvers.
case of k-point sampling.
SolutionMethod diagon (string) In order to use the new routine, netCDF support should be compiled
Character string to choose among diagonalization (diagon), cubic- in. Specifying a number of eigenvectors to store is possible through
scaling minimization (OMM), Order-N (OrderN) solution of the symbol NumberOfEigenStates (see above). Note that for now,
the Kohn-Sham Hamiltonian, transiesta, or the PEXSI method for safety, all eigenvectors for a given k-point and spin are computed
(PEXSI). by the diagonalization routine, but only that number specified by the
user are stored. If they are insufficient, the program stops. A rule
of thumb to select the number of eigenvectors to store is to count
6.12.1 Diagonalization options the number of electrons and divide by two, and then apply a “safety
NumberOfEigenStates 〈all orbitals〉 (integer) factor” of around 1.1-1.2 to take into account fractional occupations
depends on: Diag.Algorithm and band overlaps.
This parameter allows the user to reduce the number of eigenstates A new file OCCS is produced with information about the number of
that are calculated from the maximum possible. The benefit is that, states occupied.
for any calculation, the cost of the diagonalization is reduced by find- This is an experimental feature.
ing fewer eigenvalues/eigenvectors. For example, during a geometry NOTE: It is not compatible with the Diag.ParallelOverK option.
optimisation, only the occupied states are required rather than the
full set of virtual orbitals. Note, that if the electronic temperature Diag.Use2D true (logical)
is greater than zero then the number of partially occupied states in- Determine whether a 1D or 2D data decomposition should be used
creases, depending on the band gap. The value specified must be when calling ScaLAPACK. The use of 2D leads to superior scaling on
greater than the number of occupied states and less than the number large numbers of processors and is therefore the default. This option
of basis functions. only influences the parallel performance.
If a negative number is passed it corresponds to the number of orbitals If Diag.BlockSize is different from BlockSize this flag defaults to
above the total charge of the system. In effect it corresponds to the true, else if Diag.ProcessorY is 1 or the total number of processors,

52
 then this flag will default to false. Use the multiple relatively robust algorithm.
√ NOTE: The MRRR method is defaulted not to be compiled in,
Diag.ProcessorY ∼ N (integer)
however, if your ScaLAPACK library does contain the relevant
depends on: Diag.Use2D
sources one may add this pre-processor flag -DSIESTA__MRRR.
Set the number of processors in the 2D distribution along the rows.
Its default MRRR-2stage depends on: NumberOfEigenStates
√ is equal to the lowest multiple of N (number of MPI cores)
below N such that, ideally, the distribution will be a square grid. Use the 2-stage multiple relatively robust algorithm.
The input is required to be a multiple of the total number of MPI expert depends on: NumberOfEigenStates
cores but SIESTA will reduce the input value such that it coincides Use the expert algorithm which allows calculating a subset of the
with this. eigenvalues/eigenvectors.
√
Once the lowest multiple closest to N, or the input, is determined
expert-2stage depends on: NumberOfEigenStates
the 2D distribution will be ProcessorY × N/ProcessorY, rows ×
columns. Use the 2-stage expert algorithm which allows calculating a subset
of the eigenvalues/eigenvectors.
NOTE: If the automatic correction (lowest multiple of MPI cores)
is 1 the default of Diag.Use2D will be false. noexpert|QR Use the QR algorithm.

Diag.BlockSize 〈BlockSize〉 (integer) noexpert-2stage|QR-2stage Use the 2-stage QR algorithm.

depends on: Diag.Use2D
ELPA-1stage depends on: NumberOfEigenStates
The block-size used for the 2D distribution in the ScaLAPACK calls.
Use the ELPA [1;7]
1-stage solver. Requires compilation of SIESTA
This number greatly affects the performance of ScaLAPACK.
with ELPA, see Sec. 2.4.
If the ScaLAPACK library is threaded this parameter should not be
Not compatible with Diag.ParallelOverK.
too small. In any case it may be advantageous to run a few tests to
find a suitable value. ELPA|ELPA-2stage depends on: NumberOfEigenStates

NOTE: If Diag.Use2D is set to false this flag is not used. Use the ELPA [1;7]
2-stage solver. Requires compilation of SIESTA
with ELPA, see Sec. 2.4.
Diag.Algorithm Divide-and-Conquer|... (string)
Not compatible with Diag.ParallelOverK.
Select the algorithm when calculating the eigenvalues and/or eigen-
vectors. NOTE: All the 2-stage solvers are (as of July 2017) only imple-
mented in the LAPACK library, so they will only be usable in serial
The fastest routines are typically MRRR or ELPA which may be
or when using Diag.ParallelOverK.
significantly faster by specifying a suitable NumberOfEigenStates
value. To enable the 2-stage solvers add this flag to the arch.make
Currently the implemented solvers are: FPPFLAGS += -DSIESTA__DIAG_2STAGE

divide-and-Conquer Use the divide-and-conquer algorithm. If one uses the shipped LAPACK library the 2-stage solvers are added
automatically.
divide-and-Conquer-2stage Use the divide-and-conquer 2stage al-
gorithm (fall-back to the divide-and-conquer if not available). NOTE: This flag has precedence over the deprecated flags:
Diag.DivideAndConquer, Diag.MRRR, Diag.ELPA and
MRRR depends on: NumberOfEigenStates Diag.NoExpert. However, the default is taking from the depre-

53
 cated flags. solvers.
NOTE: Do not change this variable unless you are performing bench-
Diag.ParallelOverK false (logical)
marks. It should be fastest with the lower part.
For the diagonalization there is a choice in strategy about whether
to parallelise over the k points (true) or over the orbitals (false). k
point diagonalization is close to perfectly parallel but is only useful Deprecated diagonalization options
where the number of k points is much larger than the number of
Diag.MRRR false (logical)
processors and therefore orbital parallelisation is generally preferred.
depends on: NumberOfEigenStates
The exception is for metals where the unit cell is small, but the
Use the MRRR method in ScaLAPACK for diagonalization. Specify-
number of k points to be sampled is very large. In this last case it is
ing a number of eigenvectors to store is possible through the symbol
recommend that this option be used.
NumberOfEigenStates (see above).
NOTE: This scheme is not used for the diagonalizations involved in
NOTE: The MRRR method is defaulted not to be compiled in, how-
the generation of the band-structure (as specified with BandLines
ever, if your ScaLAPACK library does contain the relevant sources
or BandPoints) or in the generation of wave-function information
one may add this pre-processor flag -DSIESTA__MRRR.
(as specified with WaveFuncKPoints). In these cases the program
falls back to using parallelization over orbitals. NOTE: Use Diag.Algorithm instead.

Diag.AbsTol 10−16 (real) Diag.DivideAndConquer true (logical)

The absolute tolerance for the orthogonality of the eigenvectors. This Logical to select whether the normal or Divide and Conquer algo-
tolerance is only applicable for the solvers: rithms are used within the ScaLAPACK/LAPACK diagonalization
routines.
expert for both the serial and parallel solvers.
NOTE: Use Diag.Algorithm instead.
mrrr for the serial solver.
Diag.ELPA false (logical)
Diag.OrFac 10−3 (real)
depends on: NumberOfEigenStates
Re-orthogonalization factor to determine when the eigenvectors
See the ELPA articles [1;7]
for additional information.
should be re-orthogonalized.
NOTE: It is not compatible with the Diag.ParallelOverK option.
Only applicable for the expert serial and parallel solvers.
NOTE: Use Diag.Algorithm instead.
Diag.Memory 1 (real)
Diag.NoExpert false (logical)
Whether the parallel diagonalization of a matrix is successful or not
can depend on how much workspace is available to the routine when Logical to select whether the simple or expert versions of the ScaLA-
there are clusters of eigenvalues. Diag.Memory allows the user to PACK/LAPACK routines are used. Usually the expert routines are
increase the memory available, when necessary, to achieve successful faster, but may require slightly more memory.
diagonalization and is a scale factor relative to the minimum amount NOTE: Use Diag.Algorithm instead.
of memory that ScaLAPACK might need.

Diag.UpperLower lower|upper (string)

Which part of the symmetric triangular part should be used in the

54
6.12.2 Output of eigenvalues and wavefunctions correspond to the physical ones if the electronic temperature is set
to the physical temperature of the system, this is not the case in the
This section focuses on the output of eigenvalues and wavefunctions pro- Methfessel-Paxton function. In this case, the tempeature is just a
duced during the (last) iteration of the self-consistent cycle, and associated mathematical artifact to obtain a more accurate integration of the
to the appropriate k-point sampling. physical quantities at a lower cost. In particular, the Methfessel-
For band-structure calculations (which typically use a different set of k- Paxton scheme has the advantage that, even for quite large smearing
points) and specific requests for wavefunctions, see Secs. 6.14 and 6.15, temperatures, the obtained energy is very close to the physical en-
respectively. ergy at T = 0. Also, it allows a much faster convergence with respect
to k-points, specially for metals. Finally, the convergence to selfcon-
The complete set of wavefunctions obtained during the last iteration sistency is very much improved (allowing the use of larger mixing
of the SCF loop will be written to a NetCDF file WFS.nc if the coefficients).
Diag.UseNewDiagk option is in effect.
For the Methfessel-Paxton case, one can use relatively large values
The complete set of wavefunctions obtained during the last iteration for the ElectronicTemperature parameter. How large depends on
of the SCF loop will be written to SystemLabel.fullBZ.WFSX if the the specific system. A guide can be found in the article by J. Kresse
COOP.Write option is in effect. and J. Furthmüller, Comp. Mat. Sci. 6, 15 (1996).
WriteEigenvalues false (logical) If Methfessel-Paxton smearing is used, the order of the corresponding
Hermite polynomial expansion must also be chosen (see description
If true it writes the Hamiltonian eigenvalues for the sampling ~k of variable OccupationMPOrder).
points, in the main output file. If false, it writes them in the file
We finally note that, in both cases (FD and MP), once a finite tem-
SystemLabel.EIG, which can be used by the Eig2DOS postprocess-
perature has been chosen, the relevant energy is not the Kohn-Sham
ing utility (in the Util/Eig2DOS directory) for obtaining the density
energy, but the Free energy. In particular, the atomic forces are
of states.
derivatives of the Free energy, not the KS energy. See R. Wentzcov-
NOTE: this option only works for SolutionMethod which calcu- itch et al., Phys. Rev. B 45, 11372 (1992); S. de Gironcoli, Phys.
lates the eigenvalues. Rev. B 51, 6773 (1995); J. Kresse and J. Furthmüller, Comp. Mat.
Sci. 6, 15 (1996), for details.
6.12.3 Occupation of electronic states and Fermi level
OccupationMPOrder 1 (integer)
OccupationFunction FD (string) Order of the Hermite-Gauss polynomial expansion for the electronic
String variable to select the function that determines the occupation occupation functions in the Methfessel-Paxton scheme (see Phys.
of the electronic states. Two options are available: Rev. B 40, 3616 (1989)). Specially for metals, higher order ex-
pansions provide better convergence to the ground state result, even
FD The usual Fermi-Dirac occupation function is used. with larger smearing temperatures, and provide also better conver-
MP The occupation function proposed by Methfessel and Paxton gence with k-points.
(Phys. Rev. B, 40, 3616 (1989)), is used. NOTE: only used if OccupationFunction is MP.
The smearing of the electronic occupations is done, in both cases, us- ElectronicTemperature 300 K (temperature/energy)
ing an energy width defined by the ElectronicTemperature vari- Temperature for Fermi-Dirac or Methfessel-Paxton distribution. Use-
able. Note that, while in the case of Fermi-Dirac, the occupations

55
 ful specially for metals, and to accelerate selfconsistency in some OMM.UseSparse false (logical)
cases. Select whether to make use of the sparsity of the Hamiltonian and
overlap matrices where possible when performing matrix-matrix mul-
6.12.4 Orbital minimization method (OMM) tiplications (these operations are thus reduced from O(N 3 ) to O(N 2 )
without loss of accuracy).
The OMM is an alternative cubic-scaling solver that uses a minimization NOTE: not compatible
algorithm instead of direct diagonalization to find the occupied subspace. with OMM.UseCholesky, OMM.Use2D, or non-Γ point calcu-
The main advantage over diagonalization is the possibility of iteratively lations
reusing the solution from each SCF/MD step as the starting guess of the
OMM.Precon -1 (integer)
following one, thus greatly reducing the time to solution. Typically, there-
fore, the first few SCF cycles of the first MD step of a simulation will be Number of SCF steps for all MD steps for which to apply a precon-
slower than diagonalization, but the rest will be faster. The main disad- ditioning scheme based on the overlap and kinetic energy matrices;
vantages are that individual Kohn-Sham eigenvalues are not computed, for negative values the preconditioning is always applied. Precondi-
and that only a fixed, integer number of electrons at each k point/spin tioning is usually essential for fast and accurate convergence (note,
is allowed. Therefore, only spin-polarized calculations with Spin.Fix are however, that it is not needed if a Cholesky factorization is performed;
allowed, and Spin.Total must be chosen appropriately. For non-Γ point in such cases this variable will have no effect on the calculation).
calculations, the number of electrons is set to be equal at all k points. NOTE: cannot be used with OMM.UseCholesky.
Non-colinear calculations (see Spin) are not supported at present. The
OMM.PreconFirstStep 〈OMM.Precon〉 (integer)
OMM implementation was initially developed by Fabiano Corsetti.
Number of SCF steps in the first MD step for which to apply the
It is important to note that the OMM requires all occupied Kohn-Sham preconditioning scheme; if present, this will overwrite the value given
eigenvalues to be negative; this can be achieved by applying a shift to the in OMM.Precon for the first MD step only.
eigenspectrum, controlled by ON.eta (in this case, ON.eta simply needs
to be higher than the HOMO level). If the OMM exhibits a pathologically OMM.Diagon 0 (integer)
slow or unstable convergence, this is almost certainly due to the fact that Number of SCF steps for all MD steps for which to use a standard
the default value of ON.eta (0.0 eV) is too low, and should be raised by diagonalization before switching to the OMM; for negative values
a few eV. diagonalization is always used, and so the calculation is effectively
equivalent to SolutionMethod diagon. In general, selecting the
OMM.UseCholesky true (logical)
first few SCF steps can speed up the calculation by removing the
Select whether to perform a Cholesky factorization of the general- costly initial minimization (at present this works best for Γ point
ized eigenvalue problem; this removes the overlap matrix from the calculations).
problem but also destroys the sparsity of the Hamiltonian matrix.
OMM.DiagonFirstStep 〈OMM.Diagon〉 (integer)
OMM.Use2D true (logical)
Number of SCF steps in the first MD step for which to use a standard
Select whether to use a 2D data decomposition of the matrices for diagonalization before switching to the OMM; if present, this will
parallel calculations. This generally leads to superior scaling for large overwrite the value given in OMM.Diagon for the first MD step
numbers of MPI processes. only.

56
OMM.BlockSize 〈BlockSize〉 (integer) OMM.LongOutput false (logical)
Blocksize used for distributing the elements of the matrix over MPI Select whether to output detailed information of the conjugate gra-
processes. Specifically, this variable controls the dimension relating dients minimization for each SCF step.
to the trial orbitals used in the minimization (equal to the number
of occupied states at each k point/spin); the equivalent variable for
6.12.5 Order(N) calculations
the dimension relating to the underlying basis orbitals is controlled
by BlockSize. The Ordern(N) subsystem is quite fragile and only works for systems with
OMM.TPreconScale 10 Ry (energy) clearly separated occupied and empty states. Note also that the option
to compute the chemical potential automatically does not yet work in
Scale of the kinetic energy preconditioning (see C. K. Gan et al.,
parallel.
Comput. Phys. Commun. 134, 33 (2001)). A smaller value indi-
cates more aggressive kinetic energy preconditioning, while an infi- NOTE: Since it is used less often, bugs creeping into the O(N) solver
nite value indicates no kinetic energy preconditioning. In general, the have been more resilient than in more popular bits of the code. Work is
kinetic energy preconditioning is much less important than the tenso- ongoing to clean and automate the O(N) process, to make the solver more
rial correction brought about by the overlap matrix, and so this value user-friendly and robust.
will have fairly little impact on the overall performace of the precon-
ditioner; however, too aggressive kinetic energy preconditioning can ON.functional Kim (string)
have a detrimental effect on performance and accuracy. Choice of order-N minimization functionals:
Kim Functional of Kim, Mauri and Galli, PRB 52, 1640 (1995).
OMM.RelTol 10−9 (real)
Relative tolerance in the conjugate gradients minimization of the Ordejon-Mauri Functional of Ordejón et al, or Mauri et al, see PRB
Kohn-Sham band energy (see ON.Etol). 51, 1456 (1995). The number of localized wave functions (LWFs)
used must coincide with Nel /2 (unless spin polarized). For the
OMM.Eigenvalues false (logical) initial assignment of LWF centers to atoms, atoms with even num-
Select whether to perform a diagonalization at the end of each MD ber of electrons, n, get n/2 LWFs. Odd atoms get (n + 1)/2 and
step to obtain the Kohn-Sham eigenvalues. (n − 1)/2 in an alternating sequence, ir order of appearance (con-
trolled by the input in the atomic coordinates block).
OMM.WriteCoeffs false (logical)
Select whether to write the coefficients of the solution orbitals to file files Reads localized-function information from a file and chooses au-
at the end of each MD step. tomatically the functional to be used.

OMM.ReadCoeffs false (logical) ON.MaxNumIter 1000 (integer)

Select whether to read the coefficients of the solution orbitals from Maximum number of iterations in the conjugate minimization of the
file at the beginning of a new calculation. Useful for restarting electronic energy, in each SCF cycle.
an interrupted calculation, especially when used in conjuction with ON.Etol 10−8 (real)
DM.UseSaveDM. Note that the same number of MPI processes
Relative-energy tolerance in the conjugate minimization of the elec-
and values of OMM.Use2D, OMM.BlockSize, and BlockSize
tronic energy. The minimization finishes if 2(En − En−1 )/(En +
must be used when restarting.
En−1 ) ≤ ON.Etol.

57
ON.eta 0 eV (energy) Specifies whether to use the calculated estimate of the Chemical Po-
Fermi level parameter of Kim et al.. This should be in the energy tential, instead of the parameter ON.eta for the order-N energy
gap, and tuned to obtain the correct number of electrons. If the functional minimization. This is useful if you do not know the po-
calculation is spin polarised, then separate Fermi levels for each spin sition of the Fermi level, typically in the beginning of an order-N
can be specified. run.
NOTE: this overrides the value of ON.eta
ON.eta.alpha 0 eV (energy) and ON.ChemicalPotential. Also, this option does not work in
Fermi level parameter of Kim et al. for alpha spin electrons. This parallel. An alternative is to obtain the approximate value of the
should be in the energy gap, and tuned to obtain the correct number chemical potential using an initial diagonalization.
of electrons. Note that if the Fermi level is not specified individually
for each spin then the same global eta will be used. ON.ChemicalPotential.Rc 9.5 Bohr (length)
Defines the cutoff radius for the density matrix or Fermi operator in
ON.eta.beta 0 eV (energy) the calculation of the estimate of the Chemical Potential.
Fermi level parameter of Kim et al. for beta spin electrons. This
should be in the energy gap, and tuned to obtain the correct number ON.ChemicalPotential.Temperature 0.05 Ry
of electrons. Note that if the Fermi level is not specified individually (temperature/energy)
for each spin then the same global eta will be used. Defines the temperature to be used in the Fermi function expansion
in the calculation of the estimate of the Chemical Potential. To have
ON.RcLWF 9.5 Bohr (length) an accurate results, this temperature should be smaller than the gap
Localization redius for the Localized Wave Functions (LWF’s). of the system.
ON.ChemicalPotential false (logical) ON.ChemicalPotential.Order 100 (integer)
Specifies whether to calculate an order-N estimate of the Chemical Order of the Chebishev expansion to calculate the estimate of the
Potential, by the projection method (Goedecker and Teter, PRB 51, Chemical Potential.
9455 (1995); Stephan, Drabold and Martin, PRB 58, 13472 (1998)).
This is done by expanding the Fermi function (or density matrix) ON.LowerMemory false (logical)
at a given temperature, by means of Chebyshev polynomials, and If true, then a slightly reduced memory algorithm is used in the
imposing a real space truncation on the density matrix. To obtain a 3-point line search during the order N minimisation. Only affects
realistic estimate, the temperature should be small enough (typically, parallel runs.
smaller than the energy gap), the localization range large enough
(of the order of the one you would use for the Localized Wannier
Output of localized wavefunctions At the end of each conjugate
Functions), and the order of the polynomial expansion sufficiently
gradient minimization of the energy functional, the LWF’s are stored on
large (how large depends on the temperature; typically, 50-100).
disk. These can be used as an input for the same system in a restart, or
NOTE: this option does not work in parallel. An alternative is in case something goes wrong. The LWF’s are stored in sparse form in
to obtain the approximate value of the chemical potential using an file SystemLabel.LWF
initial diagonalization.
It is important to keep very good care of this file, since the first mini-
ON.ChemicalPotential.Use false (logical) mizations can take MANY steps. Loosing them will mean performing the

58
whole minimization again. It is also a good practice to save it periodically 6.13.1 Pole handling
during the simulation, in case a mid-run restart is necessary.
Note that the temperature for the Fermi-Dirac distribution which is pole-
ON.UseSaveLWF false (logical) expanded is taken directly from the ElectronicTemperature parameter
Instructs to read the localized wave functions stored in file (see Sec. 6.12.3).
SystemLabel.LWF by a previous run.
PEXSI.NumPoles 40 (integer)
Effective number of poles used to expand the Fermi-Dirac function.
6.13 The PEXSI solver
PEXSI.deltaE 3 Ry (energy)
The PEXSI solver is based on the combination of the pole expansion of In principle PEXSI.deltaE should be Emax − µ, where Emax is
the Fermi-Dirac function and the computation of only a selected (sparse) the largest eigenvalue for (H,S), and µ is the chemical poten-
subset of the elements of the matrices (H − zl S)−1 at each pole zl . tial. However, due to the fast decay of the Fermi-Dirac function,
This solver can efficiently use the sparsity pattern of the Hamiltonian PEXSI.deltaE can often be chosen to be much lower. In practice
and overlap matrices generated in SIESTA, and for large systems has we set the default to be 3 Ryd. This number should be set to be larger
a much lower computational complexity than that associated with the if the difference between Tr[H · DM] and Tr[S ∗ EDM] (displayed in
matrix diagonalization procedure. It is also highly scalable. the output if PEXSI.Verbosity is at least 2) does not decrease with
the increase of the number of poles.
The PEXSI technique can be used to evaluate the electron density, free
energy, atomic forces, density of states and local density of states without PEXSI.Gap 0 Ry (energy)
computing any eigenvalue or eigenvector of the Kohn-Sham Hamiltonian. Spectral gap. This can be set to be 0 in most cases.
It can achieve accuracy fully comparable to that obtained from a matrix
diagonalization procedure for general systems, including metallic systems
at low temperature. 6.13.2 Parallel environment and control options
The current implementation of the PEXSI solver in SIESTA makes use of MPI.Nprocs.SIESTA 〈total processors〉 (integer)
the full fine-grained-level interface in the PEXSI library (http://pexsi. Specifies the number of MPI processes to be used in those parts of
org), and can deal with spin-polarization, but it is still restricted to Γ- the program (such as Hamiltonian setup and computation of forces)
point calculations. which are outside of the PEXSI solver itself. This is needed in large-
The following is a brief description of the input-file parameters relevant scale calculations, for which the number of processors that can be
to the workings of the PEXSI solver. For more background, including a used by the PEXSI solver is much higher than those needed by other
discussion of the conditions under which this solver is competitive, the parts of the code.
user is referred to the paper Lin et al. [6] , and references therein. Note that when the PEXSI solver is not used, this parameter will
simply reduce the number of processors actually used by all parts of
The technology involved in the PEXSI solver can also be used to com-
the program, leaving the rest idle for the whole calculation. This will
pute densities of states and “local densities of states”. These features
adversely affect the computing budget, so take care not to use this
are documented in this section and also linked to in the relevant general
option in that case.
sections.
PEXSI.NP-per-pole 4 (integer)

59
 Number of MPI processes used to perform the PEXSI computations PEXSI.Verbosity 1 (integer)
in one pole. If the total number of MPI processes is smaller than It determines the amount of information logged by the solver in dif-
this number times the number of poles (times the spin multiplicity), ferent places. A value of zero gives minimal information.
the PEXSI library will compute appropriate groups of poles in se-
• In the files logPEXSI[0-9]+, the verbosity level is interpreted by
quence. The minimum time to solution is achieved by increasing this
the PEXSI library itself. In the latest version, when PEXSI is
parameter as much as it is reasonable for parallel efficiency, and using
compiled in RELEASE mode, only logPEXSI0 is given in the
enough MPI processes to allow complete parallelization over poles.
output. This is because we have observed that simultaneous
On the other hand, the minimum computational cost (in the sense of
output for all processors can have very significant cost for a
computing budget) is obtained by using the minimum value of this
large number of processors (>10000).
parameter which is compatible with the memory footprint. The ad-
ditional parallelization over poles will be irrelevant for cost, but it • In the SIESTA output file, a verbosity level of 1 and above will
will obviously affect the time to solution. print lines (prefixed by &o) indicating the various heuristics used
Internally, SIESTA computes the processor grid parameters nprow at each scf step. A verbosity level of 2 and above will print extra
and npcol for the PEXSI library, with nprow >= npcol, and as information.
similar as possible. So it is best to choose PEXSI.NP-per-pole as The design of the output logging is still in flux.
the product of two similar numbers.
NOTE: The total number of MPI processes must be divisible by 6.13.3 Electron tolerance and the PEXSI solver
PEXSI.NP-per-pole. In case of spin-polarized calculations, the
total number of MPI processes must be divisible by PEXSI.NP- PEXSI.num-electron-tolerance 10−4 (real)
per-pole times 2. Tolerance in the number of electrons for the PEXSI solver. At each
iteration of the solver, the number of electrons is computed as the
PEXSI.Ordering 1 (integer) trace of the density matrix times the overlap matrix, and compared
For large matrices, symbolic factorization should be performed in with the total number of electrons in the system. This tolerance can
parallel to reduce the wall clock time. This can be done using be fixed, or dynamically determined as a function of the degree of
ParMETIS/PT-Scotch by setting PEXSI.Ordering to 0. However, convergence of the self-consistent-field loop.
we have been experiencing some instability problem of the symbolic
factorization phase when ParMETIS/PT-Scotch is used. In such PEXSI.num-electron-tolerance-lower-bound 10−2 (real)
case, for relatively small matrices one can either use the sequential See PEXSI.num-electron-tolerance-upper-bound.
METIS (PEXSI.Ordering = 1) or set PEXSI.NP-symbfact to
1. PEXSI.num-electron-tolerance-upper-bound 0.5 (real)
The upper and lower bounds for the electron tolerance are used to
PEXSI.NP-symbfact 1 (integer) dynamically change the tolerance in the PEXSI solver, following the
Number of MPI processes used to perform the symbolic factorizations simple algorithm:
needed in the PEXSI procedure. A default value should be given to
tolerance = Max(lower_bound,Min(dDmax, upper_bound))
reduce the instability problem. From experience so far setting this
to be 1 is most stable, but going beyond 64 does not usually improve The first scf step uses the upper bound of the tolerance range, and
much. subsequent steps use progressively lower values, in correspondence
with the convergence-monitoring variable dDmax.

60
 NOTE: This simple update schedule tends to work quite well. There counting is started.
is an experimental algorithm, documented only in the code itself,
which allows a finer degree of control of the tolerance update.
6.13.4 Inertia-counting
PEXSI.mu-max-iter 10 (integer) PEXSI.Inertia-Counts 3 (integer)
Maximum number of iterations of the PEXSI solver. Note that in In a given scf step, the PEXSI procedure can optionally employ a µ
this implementation there is no fallback procedure if the solver fails bracket-refinement procedure based on inertia-counting. Typically,
to converge in this number of iterations to the prescribed tolerance. this is used only in the first few scf steps, and this parameter deter-
In this case, the resulting density matrix might still be re-normalized, mines how many. If positive, inertia-counting will be performed for
and the calculation able to continue, if the tolerance for non normal- exactly that number of scf steps. If negative, inertia-counting will
ized DMs is not set too tight. For example, be performed for at least that number of scf steps, and then for as
# (true_no_electrons/no_electrons) - 1.0 long as the scf cycle is not yet deemed to be near convergence (as
DM.NormalizationTolerance 1.0e-3 determined by the PEXSI.safe-dDmax-no-inertia parameter).
NOTE: Since it is cheaper to perform an inertia-count phase than
will allow a 0.1% error in the number of electrons. For obvious rea-
to execute one iteration of the solver, it pays to call the solver only
sons, this feature, which is also useful in connection with the dynamic
when the µ bracket is sufficiently refined.
tolerance update, should not be abused.
If the parameters of the PEXSI solver are adjusted correctly (includ- PEXSI.mu-min −1 Ry (energy)
ing a judicious use of inertia-counting to refine the µ bracket), we The lower bound of the initial range for µ used in the inertia-count
should expect that the maximum number of solver iterations needed refinement. In runs with multiple geometry iterations, it is used only
is around 3 for the very first scf iteration at the first geometry step. Further
iterations inherit possibly refined values of this parameter.
PEXSI.mu −0.6 Ry (energy)
The starting guess for the chemical potential for the PEXSI solver. PEXSI.mu-max 0 Ry (energy)
Note that this value does not affect the initial µ bracket for the The upper bound of the initial range for µ used in the inertia-count
inertia-count refinement, which is controlled by PEXSI.mu-min refinement. In runs with multiple geometry iterations, it is used only
and PEXSI.mu-max. After an inertia-count phase, µ will be re- for the very first scf iteration at the first geometry step. Further
set, and further iterations inherit this estimate, so this parameter is iterations inherit possibly refined values of this parameter.
only relevant if there is no inertia-counting phase.
PEXSI.safe-dDmax-no-inertia 0.05 (real)
PEXSI.mu-pexsi-safeguard 0.05 Ry (energy) During the scf cycle, the variable conventionally called dDmax mon-
NOTE: This feature has been deactivated for now. The condition itors how far the cycle is from convergence. If PEXSI.Inertia-
for starting a new phase of inertia-counting is that the Newton es- Counts is negative, an inertia-counting phase will be performed in
timation falls outside the current bracket. The bracket is expanded a given scf step for as long as dDmax is greater than PEXSI.safe-
accordingly. dDmax-no-inertia.
The PEXSI solver uses Newton’s method to update the estimate of NOTE: Even though dDmax represents historically how far from
µ. If the attempted change in µ is larger than PEXSI.mu-pexsi- convergence the density-matrix is, the same mechanism applies to
safeguard, the solver cycle is stopped and a fresh phase of inertia- other forms of mixing in which other magnitudes are monitored for

61
 convergence (Hamiltonian, charge density...). PEXSI.safe-dDmax-ef-inertia 0.1 (real)
The change in µ from one scf iteration to the next can be crudely
PEXSI.lateral-expansion-inertia 3 eV (energy)
estimated by assuming that the change in the band structure energy
If the correct µ is outside the bracket provided to the inertia-counting (estimated as Tr∆HDM) is due to a rigid shift. When the scf cycle
phase, the bracket is expanded in the appropriate direction(s) by this is near convergence, this ∆µ can be used to estimate the new initial
amoount. bracket for the inertia-counting phase, rigidly shifting the output
PEXSI.Inertia-mu-tolerance 0.05 Ry (energy) bracket from the previous scf step. The cycle is assumed to be near
convergence when the monitoring variable dDmax is smaller than
One of the criteria for early termination of the inertia-counting phase.
PEXSI.safe-dDmax-ef-inertia.
The value of the estimated µ (basically the center of the resulting
brackets) is monitored, and the cycle stopped if its change from one NOTE: Even though dDmax represents historically how far from
iteration to the next is below this parameter. convergence the density-matrix is, the same mechanism applies to
other forms of mixing in which other magnitudes are monitored for
PEXSI.Inertia-max-iter 5 (integer) convergence (Hamiltonian, charge density...).
Maximum number of inertia-count iterations per cycle. NOTE: This criterion will lead in general to tighter brackets than the
previous one, but oscillations in H in the first few iterations might
PEXSI.Inertia-min-num-shifts 10 (integer) make it more dangerous. More information from real use cases is
Minimum number of sampling points for inertia counts. needed to refine the heuristics in this area.
PEXSI.Inertia-energy-width-tolerance PEXSI.safe-dDmax-ef-solver 0.05 (real)
〈PEXSI.Inertia-mu-tolerance〉 (energy) When the scf cycle is near convergence, the ∆µ estimated as above
One of the criteria for early termination of the inertia-counting phase. can be used to shift the initial guess for µ for the PEXSI solver. The
The cycle stops if the width of the resulting bracket is below this cycle is assumed to be near convergence when the monitoring variable
parameter. dDmax is smaller than PEXSI.safe-dDmax-ef-solver.
NOTE: Even though dDmax represents historically how far from
6.13.5 Re-use of µ information accross iterations convergence the density-matrix is, the same mechanism applies to
other forms of mixing in which other magnitudes are monitored for
This is an important issue, as the efficiency of the PEXSI procedure de- convergence (Hamiltonian, charge density...).
pends on how close a guess of µ we have at our disposal. There are two
types of information re-use: PEXSI.safe-width-solver-bracket 4 eV (energy)
In all cases, a “safe” bracket around µ is provided even in direct calls
• Bracketing information used in the inertia-counting phase. to the PEXSI solver, in case a fallback to executing internally a cycle
of inertia-counting is needed. The size of the bracket is given by
• The values of µ itself for the solver. PEXSI.safe-width-solver-bracket
PEXSI.safe-width-ic-bracket 4 eV (energy)
By default, the µ bracket used for the inertia-counting phase in
scf steps other than the first is taken as an interval of width
PEXSI.safe-width-ic-bracket around the latest estimate of µ.

62
6.13.6 Calculation of the density of states by inertia-counting 6.13.7 Calculation of the LDOS by selected-inversion

The cumulative or integrated density of states (INTDOS) can be easily The local-density-of-states (LDOS) around a given reference energy ε,
obtained by inertia-counting, which involves a factorization of H − σS representing the contribution to the charge density of the states with
for varying σ (see SIESTA-PEXSI paper). Apart from the DOS-specific eigenvalues in the vicinity of ε, can be obtained formally by a “one-pole
options below, the “ordering”, “symbolic factorization”, and “pole group expansion” with suitable broadening (see SIESTA-PEXSI paper).
size” (re-interpreted as the number of MPI processes dealing with a given Apart from the LDOS-specific options below, the “ordering”, “verbosity”,
σ) options are honored. and “symbolic factorization” options are honored.
The current version of the code generates a file with the energy-INTDOS The current version of the code generates a real-space grid file with
information, PEXSI_INTDOS, which can be later processed to gener- extension SystemLabel.LDSI, and (if netCDF is compiled-in) a file
ate the DOS by direct numerical differentiation, or a SIESTA-style Rho.grid.nc (which unfortunately will overwrite any other charge-
SystemLabel.EIG file (using the Util/PEXSI/intdos2eig program). density files produced in the same run).
PEXSI.DOS false (logical) NOTE: The LDOS computed with this procedure is not exactly the same
Whether to compute the DOS (actually, the INTDOS — see above) as the vanilla SIESTA LDOS, which uses an explicit energy interval. Here
using the PEXSI technology. the broadening acts around a single value of the energy.

PEXSI.DOS.Emin −1 Ry (energy) PEXSI.LDOS false (logical)

Lower bound of energy window to compute the DOS in. Whether to compute the LDOS using the PEXSI technology.
See PEXSI.DOS.Ef.Reference.
PEXSI.LDOS.Energy 0 Ry (energy)
PEXSI.DOS.Emax 1 Ry (energy) The (absolute) energy at which to compute the LDOS.
Upper bound of energy window to compute the DOS in.
PEXSI.LDOS.Broadening 0.01 Ry (energy)
See PEXSI.DOS.Ef.Reference.
The broadening parameter for the LDOS.
PEXSI.DOS.Ef.Reference true (logical)
PEXSI.LDOS.NP-per-pole 〈PEXSI.NP-per-pole〉 (integer)
If this flag is true, the bounds of the energy window
The value of this parameter supersedes PEXSI.NP-per-pole for
(PEXSI.DOS.Emin and PEXSI.DOS.Emax) are with respect to
the calculation of the LDOS, which otherwise would keep idle all but
the Fermi level.
PEXSI.NP-per-pole MPI processes, as it essentially consists of a
PEXSI.DOS.NPoints 200 (integer) “one-pole” procedure.
The number of points in the energy interval at which the DOS is
computed. It is rounded up to the nearest multiple of the number of 6.14 Band-structure analysis
available factorization groups, as the operations are perfectly parallel
and there will be no extra cost involved. This calculation of the band structure is performed optionally after
the geometry loop finishes, and the output information written to the
SystemLabel.bands file (see below for the format).

63
BandLinesScale pi/a (string) 0.500 0.500 0.500
Specifies the scale of the k vectors given in BandLines and Band- %endblock BandPoints
Points below. The options are: See also BandLines.
pi/a k-vector coordinates are given in Cartesian coordinates, in units WriteKbands false (logical)
of π/a, where a is the lattice constant
~
If true, it writes the coordinates of the k vectors defined for band
ReciprocalLatticeVectors k vectors are given in reciprocal-lattice- plotting, to the main output file.
vector coordinates
WriteBands false (logical)
NOTE: you might need to define explicitly a LatticeConstant tag in
If true, it writes the Hamiltonian eigenvalues corresponding to the
your fdf file if you do not already have one, and make it consistent ~k vectors defined for band plotting, in the main output file.
with the scale of the k-points and any unit-cell vectors you might
have already defined.
6.14.1 Format of the .bands file
%block BandLines 〈None〉 (block)
Specifies the lines along which band energies are calculated (usually FermiEnergy (all energies in eV) \\
along high-symmetry directions). An example for an FCC lattice is: kmin, kmax (along the k-lines path, i.e. range of k in the band plot
%block BandLines Emin, Emax (range of all eigenvalues) \\
1 1.000 1.000 1.000 L # Begin at L NumberOfBands, NumberOfSpins (1 or 2), NumberOfkPoints \\
20 0.000 0.000 0.000 \Gamma # 20 points from L tok1,
gamma((ek(iband,ispin,1),iband=1,NumberOfBands),ispin=1,NumberOfSpins
25 2.000 0.000 0.000 X # 25 points from gammak2,to ek
X \\
30 2.000 2.000 2.000 \Gamma # 30 points from X to .gamma
\\
%endblock BandLines
. \\
where the last column is an optional L TEX label for use in the band
A . \\
plot. If only given points (not lines) are required, simply specify 1 in klast, ek \\
the first column of each line. The first column of the first line must NumberOfkLines \\
be always 1. kAtBegOfLine1, kPointLabel \\
NOTE: this block is not used if BandPoints is present. kAtEndOfLine1, kPointLabel \\
. \\
%block BandPoints 〈None〉 (block) . \\
Band energies are calculated for the list of arbitrary k points given . \\
in the block. Units defined by BandLinesScale as for BandLines. kAtEndOfLastLine, kPointLabel \\
The generated SystemLabel.bands file will contain the k point co-
ordinates (in a.u.) and the corresponding band energies (in eV). The gnubands postprocessing utility program (found in the Util/Bands di-
Example: rectory) reads the SystemLabel.bands for plotting. See the BandLines
%block BandPoints data descriptor above for more information.
0.000 0.000 0.000 # This is a comment. eg this is gamma
1.000 0.000 0.000

64
6.14.2 Output of wavefunctions associated to bands Diag.UseNewDiagk option is in effect.

The user can optionally request that the wavefunctions corresponding WaveFuncKPointsScale pi/a (string)
to the computed bands be written to file. They are written to the Specifies the scale of the k vectors given in WaveFuncKPoints be-
SystemLabel.bands.WFSX file. The relevant options are: low. The options are:

WFS.Write.For.Bands false (logical) pi/a k-vector coordinates are given in Cartesian coordinates, in units
of π/a, where a is the lattice constant
Instructs the program to compute and write the wave functions as-
sociated to the bands specified (by a BandLines or a BandPoints ReciprocalLatticeVectors k vectors are given in reciprocal-lattice-
block) to the file SystemLabel.WFSX. vector coordinates
The information in this file might be useful, among other things, to
%block WaveFuncKPoints 〈None〉 (block)
generate “fatbands” plots, in which both band eigenvalues and infor-
mation about orbital projections is presented. See the fat program Specifies the k-points at which the electronic wavefunction coefficients
in the Util/COOP directory for details. are written. An example for an FCC lattice is:
%block WaveFuncKPoints
WFS.Band.Min 1 (integer) 0.000 0.000 0.000 from 1 to 10 # Gamma wavefuncs 1 to 10
Specifies the lowest band index of the wave-functions to be written to 2.000 0.000 0.000 1 3 5 # X wavefuncs 1,3 and 5
the file SystemLabel.WFSX for each k-point (all k-points in the band 1.500 1.500 1.500 # K wavefuncs, all
set are affected). %endblock WaveFuncKPoints

The index of a wavefunction is defined by its energy, so that the first

WFS.Band.Max number of orbitals (integer)
one has lowest energy.
Specifies the highest band index of the wave-functions to be written
The user can also narrow the energy-range used with the
to the file SystemLabel.WFSX for each k-point (all k-points in the
WFS.Energy.Min and WFS.Energy.Max options (both take an
band set are affected).
energy (with units) as extra argument – see section 6.17.3). Care
should be taken to make sure that the actual values of the options
6.15 Output of selected wavefunctions make sense.
The output of the wavefunctions in described in Section 6.15.
The user can optionally request that specific wavefunctions are written to
file. These wavefunctions are re-computed after the geometry loop (if any) WriteWaveFunctions false (logical)
finishes, using the last (presumably converged) density matrix produced If true, it writes to the output file a list of the wavefunctions actu-
during the last self-consistent field loop (after a final mixing). They are ally written to the SystemLabel.selected.WFSX file, which is always
written to the SystemLabel.selected.WFSX file. produced.
Note that the complete set of wavefunctions obtained during the last
The unformatted WFSX file contains the information of the k-points for
iteration of the SCF loop will be written to SystemLabel.fullBZ.WFSX if
which wavefunctions coefficients are written, and the energies and coef-
the COOP.Write option is in effect.
ficients of each wavefunction which was specified in the input file (see
Note that the complete set of wavefunctions obtained during the last WaveFuncKPoints descriptor above). It also contains information on
iteration of the SCF loop will be written to a NetCDF file WFS.nc if the the atomic species and the orbitals for postprocessing purposes.

65
NOTE: The SystemLabel.WFSX file is in a more compact form than • Using the Util/COOP/mprop program for the off-line analysis of the
the old WFS, and the wavefunctions are output in single precision. The electronic structure in PDOS mode. This method allows the flexi-
Util/WFS/wfsx2wfs program can be used to convert to the old format. bility of specifying energy ranges, orbitals, and resolutions at will,
The readwf and readwfsx postprocessing utilities programs (found in the without re-running SIESTA. See Sec. 6.17.3.
Util/WFS directory) read the SystemLabel.WFS or SystemLabel.WFSX %block ProjectedDensityOfStates 〈None〉 (block)
files, respectively, and generate a readable file.
Instructs to write the Total Density Of States (Total DOS) and the
Projected Density Of States (PDOS) on the basis orbitals, between
6.16 Densities of states two given energies, in files SystemLabel.DOS and SystemLabel.PDOS,
respectively. The block must be a single line with the energies of the
6.16.1 Total density of states range for PDOS projection, (relative to the program’s zero, i.e. the
same as the eigenvalues printed by the program), the peak width (an
There are several options to obtain the total density of states: energy) for broadening the eigenvalues, the number of points in the
energy window, and the energy units. An example is:
• The Hamiltonian eigenvalues for the SCF sampling ~k points can be
%block ProjectedDensityOfStates
dumped into SystemLabel.EIG in a format analogous to SystemLa- -20.00 10.00 0.200 500 eV
bel.bands, but without the kmin, kmax, emin, emax information, %endblock ProjectedDensityOfStates
and without the abscissa. The Eig2DOS postprocessing utility can
be then used to obtain the density of states. See the WriteEigen- By default the projected density of states is generated for the same
values descriptor. grid of points in reciprocal space as used for the SCF calcula-
tion. However, a separate set of K-points, usually on a finer grid,
• As a side-product of a partial-density-of-states calculation (see be- can be generated using one of the options PDOS.kgrid.Cutoff or
low) PDOS.kgrid.MonkhorstPack. The format of these options is ex-
actly the same as for kgrid.Cutoff and kgrid.MonkhorstPack,
• As one of the files produced by the Util/COOP/mprop during the respectively. Note that if a gamma point calculation is being used in
off-line analysis of the electronic structure. This method allows the the SCF part, especially as part of a geometry optimisation, and this
flexibility of specifying energy ranges and resolutions at will, without is then to be run with a grid of K-points for the PDOS calculation
re-running SIESTA See Sec. 6.17.3. it is more efficient to run the SCF phase first and then restart to
• Using the inertia-counting routines in the PEXSI solver (see perform the PDOS evaluation using the density matrix saved from
Sec. 6.13.6). the SCF phase.
NOTE: the two energies of the range must be ordered, with lowest
first.
6.16.2 Partial (projected) density of states
The total DOS is stored in a file called SystemLabel.DOS. The format
There are two options to obtain the partial density of states of this file is:
Energy value, Total DOS (spin up), Total DOS (spin down)
• Using the options below
The Projected Density Of States for all the orbitals in the unit cell
is dumped sequentially into a file called SystemLabel.PDOS. This

66
 file is structured using spacing and xml tags. A machine-readable It determines the level of Mulliken population analysis printed:
(but not very human readable) xml file SystemLabel.PDOS.xml
0 none
is also produced. Both can be processed by the program in
Util/pdosxml. The SystemLabel.PDOS file can be processed by 1 atomic and orbital charges
utilites in Util/Contrib/APostnikov. 2 atomic, orbital and atomic overlap populations
In all cases, the units for the DOS are (number of states/eV), and
the Total DOS, g(), is normalized as follows: 3 atomic, orbital, atomic overlap and orbital overlap populations
Z ∞ The order of the orbitals in the population lists is defined by the order
g()d = number of basis orbitals in unit cell (14) of atoms. For each atom, populations for PAO orbitals and double-
−∞
z, triple-z, etc... derived from them are displayed first for all the
angular momenta. Then, populations for perturbative polarization
6.16.3 Local density of states
orbitals are written. Within a l-shell be aware that the order is not
The LDOS is formally the DOS weighted by the amplitude of the corre- conventional, being y, z, x for p orbitals, and xy, yz, z 2 , xz, and
sponding wavefunctions at different points in space, and is then a function x2 − y 2 for d orbitals.
of energy and position. SIESTA can output the LDOS integrated over a MullikenInSCF false (logical)
range of energies. This information can be used to obtain simple STM im-
If true, the Mulliken populations will be written for every SCF step
ages in the Tersoff-Hamann approximation (See Util/STM/simple-stm).
at the level of detail specified in WriteMullikenPop. Useful when
%block LocalDensityOfStates 〈None〉 (block) dealing with SCF problems, otherwise too verbose.
Instructs to write the LDOS, integrated between two given energies, SpinInSCF true (logical)
at the mesh used by DHSCF, in file SystemLabel.LDOS. This file can
If true, the size and components of the (total) spin polarization will be
be read by routine IORHO, which may be used by an application
printed at every SCF step. This is analogous to the MullikenInSCF
program in later versions. The block must be a single line with the
feature. Enabled by default for calculations involving spin.
energies of the range for LDOS integration (relative to the program’s
zero, i.e. the same as the eigenvalues printed by the program) and
their units. An example is: 6.17.2 Voronoi and Hirshfeld atomic population analysis
%block LocalDensityOfStates WriteHirshfeldPop false (logical)
-3.50 0.00 eV
If true, the program calculates and prints the Hirshfeld “net” atomic
%endblock LocalDensityOfStates
populations on each atom in the system. For a definition of the
NOTE: the two energies of the range must be ordered, with lowest Hirshfeld charges, see Hirshfeld, Theo Chem Acta 44, 129 (1977) and
first. Fonseca et al, J. Comp. Chem. 25, 189 (2003). Hirshfeld charges
are more reliable than Mulliken charges, specially for large basis sets.
6.17 Options for chemical analysis The number printed is the total net charge of the atom: the variation
from the neutral charge, in units of |e|: positive (negative) values
6.17.1 Mulliken charges and overlap populations indicate deficiency (excess) of electrons in the atom.

WriteMullikenPop 0 (integer) WriteVoronoiPop false (logical)

67
 If true, the program calculates and prints the Voronoi “net” atomic • A tutorial introduction: Dronskowski, R. Computational Chemistry
populations on each atom in the system. For a definition of the of Solid State Materials; Wiley-VCH: Weinheim, 2005.
Voronoi charges, see Bickelhaupt et al, Organometallics 15, 2923
(1996) and Fonseca et al, J. Comp. Chem. 25, 189 (2003). Voronoi • Online material maintained by R. Dronskowski’s group: http://
charges are more reliable than Mulliken charges, specially for large www.cohp.de/
basis sets. The number printed is the total net charge of the atom: COOP.Write false (logical)
the variation from the neutral charge, in units of |e|: positive (nega-
Instructs the program to generate SystemLabel.fullBZ.WFSX
tive) values indicate deficiency (excess) of electrons in the atom.
(packed wavefunction file) and SystemLabel.HSX (H, S and X_ ij
The Hirshfeld and Voronoi populations (partial charges) are computed by file), to be processed by Util/COOP/mprop to generate COOP/COHP
default only at the end of the program (i.e., for the final geometry, after curves, (projected) densities of states, etc.
self-consistency). The following options allow more control: The .WFSX file is in a more compact form than the usual .WFS, and
the wavefunctions are output in single precision. The Util/wfsx2wfs
PartialChargesAtEveryGeometry false (logical) program can be used to convert to the old format. The HSX file is
The Hirshfeld and Voronoi populations are computed after self- in a more compact form than the usual HS, and the Hamiltonian,
consistency is achieved, for all the geometry steps. overlap matrix, and relative-positions array (which is always output,
even for gamma-point only calculations) are in single precision.
PartialChargesAtEverySCFStep false (logical)
The user can narrow the energy-range used (and save some file space)
The Hirshfeld and Voronoi populations are computed for every step
by using the WFS.Energy.Min and WFS.Energy.Max options
of the self-consistency process.
(both take an energy (with units) as extra argument), and/or the
Performance note: The default behavior (computing at the end of the WFS.Band.Min and WFS.Band.Max options. Care should be
program) involves an extra calculation of the charge density. taken to make sure that the actual values of the options make sense.
Note that the band range options could also affect the output of wave-
functions associated to bands (see section 6.14.2), and that the en-
6.17.3 Crystal-Orbital overlap and hamilton populations
ergy range options could also affect the output of user-selected wave-
(COOP/COHP)
functions with the WaveFuncKPoints block (see section 6.15).
These curves are quite useful to analyze the electronic structure to get WFS.Energy.Min −∞ (energy)
insight about bonding characteristics. See the Util/COOP directory for Specifies the lowest value of the energy (eigenvalue) of the wave-
more details. The COOP.Write option must be activated to get the functions to be written to the file SystemLabel.fullBZ.WFSX for
information needed. each k-point (all k-points in the BZ sampling are affected).
References:
WFS.Energy.Max ∞ (energy)
• Original COOP reference: Hughbanks, T.; Hoffmann, R., J. Am. Specifies the highest value of the energy (eigenvalue) of the wave-
Chem. Soc., 1983, 105, 3528. functions to be written to the file SystemLabel.fullBZ.WFSX for
each k-point (all k-points in the BZ sampling are affected).
• Original COHP reference: Dronskowski, R.; BlÃűchl, P. E., J. Phys.
Chem., 1993, 97, 8617.

68
6.18 Optical properties %block Optical.Mesh 〈None〉 (block)
OpticalCalculation false (logical) This block contains 3 numbers that determine the mesh size used for
the integration across the Brillouin zone. For example:
If specified, the imaginary part of the dielectric function will be cal-
culated and stored in a file called SystemLabel.EPSIMG. The calcu- %block Optical.Mesh
lation is performed using the simplest approach based on the dipolar 5 5 5
%endblock Optical.Mesh
transition matrix elements between different eigenfunctions of the
self-consistent Hamiltonian. For molecules the calculation is per- The three values represent the number of mesh points in the direction
formed using the position operator matrix elements, while for solids of each reciprocal lattice vector.
the calculation is carried out in the momentum space formulation.
Corrections due to the non-locality of the pseudopotentials are intro- Optical.OffsetMesh false (logical)
duced in the usual way. If set to true, then the mesh is offset away from the gamma point for
odd numbers of points.
Optical.Energy.Minimum 0 Ry (energy)
This specifies the minimum of the energy range in which the fre- Optical.PolarizationType polycrystal (string)
quency spectrum will be calculated. This option has three possible values that represent the type of po-
larization to be used in the calculation. The options are
Optical.Energy.Maximum 10 Ry (energy)
polarized implies the application of an electric field in a given direc-
This specifies the maximum of the energy range in which the fre-
tion
quency spectrum will be calculated.
unpolarized implies the propagation of light in a given direction
Optical.Broaden 0 Ry (energy)
If this is value is set then a Gaussian broadening will be applied to polycrystal In the case of the first two options a direction in space
the frequency values. must be specified for the electric field or propagation using the
Optical.Vector data block.
Optical.Scissor 0 Ry (energy)
%block Optical.Vector 〈None〉 (block)
Because of the tendency of DFT calculations to under estimate the
band gap, a rigid shift of the unoccupied states, known as the scissor This block contains 3 numbers that specify the vector direction for
operator, can be added to correct the gap and thereby improve the either the electric field or light propagation, for a polarized or unpo-
calculated results. This shift is only applied to the optical calculation larized calculation, respectively. A typical block might look like:
and no where else within the calculation. %block Optical.Vector
1.0 0.0 0.5
Optical.NumberOfBands all bands (integer) %endblock Optical.Vector
This option controls the number of bands that are included in the
optical property calculation. Clearly this number must be larger than
6.19 Macroscopic polarization
the number of occupied bands and less than or equal to the number of
basis functions (which determines the number of unoccupied bands %block PolarizationGrids 〈None〉 (block)
available). Note, while including all the bands may be the most If specified, the macroscopic polarization will be calculated using the
accurate choice this will also be the most expensive! geometric Berry phase approach (R.D. King-Smith, and D. Vander-

69
bilt, PRB 47, 1651 (1993)). In this method the electronic contri- integrals, while a 3 × 4 mesh will be used for the surface integration.
bution to the macroscopic polarization, along a given direction, is This last grid will be displaced from the origin, so Γ will not be in-
calculated using a discretized version of the formula cluded in the bidimensional integral. For the directions of the second
and third lattice vectors, the number of points will be 20 and 2 × 2,
M Z |Gk |
if qe δ and 15 and 4 × 4, respectively.
Z X
Pe,k = dk⊥ dkk hukn | |ukn i (15)
8π 3 A n=1 0
δkk It has to be stressed that the macroscopic polarization can only be
meaningfully calculated using this approach for insulators. Therefore,
where f is the occupation (2 for a non-magnetic system), qe the the presence of an energy gap is necessary, and no band can cross the
electron charge, M is the number of occupied bands (the system Fermi level. The program performs a simple check of this condition,
must be an insulator), and ukn are the periodic Bloch functions. Gk just by counting the electrons in the unit cell ( the number must
is the shortest reciprocal vector along the chosen direction. be even for a non-magnetic system, and the total spin polarization
As it can be seen in formula (15), to compute each component of the must have an integer value for spin polarized systems), however is
polarization we must perform a surface integration of the result of a the responsability of the user to check that the system under study
1-D integral in the selected direction. The grids for the calculation is actually an insulator (for both spin components if spin polarized).
along the direction of each of the three lattice vectors are specified The total macroscopic polarization, given in the output of the pro-
in the block PolarizationGrids. gram, is the sum of the electronic contribution (calculated as the
%block PolarizationGrids Berry phase of the valence bands), and the ionic contribution, which
10 3 4 yes is simply defined as the sum of the atomic positions within the unit
cell multiply by the ionic charges ( N
P a
2 20 2 no i Zi ri ). In the case of the
4 4 15 magnetic systems, the bulk polarization for each spin component has
%endblock PolarizationGrids been defined as
Na
All three grids must be specified, therefore a 3 × 3 matrix of integer 1X
Pσ = Pσe + Zi ri (16)
numbers must be given: the first row specifies the grid that will 2 i
be used to calculate the polarization along the direction of the first
Na is the number of atoms in the unit cell, and ri and Zi are the
lattice vector, the second row will be used for the calculation along
positions and charges of the ions.
the the direction of the second lattice vector, and the third row for
the third lattice vector. The numbers in the diagonal of the matrix It is also worth noting, that the macroscopic polarization given by
specifie the number of points to be used in the one dimensional line formula (15) is only defined modulo a “quantum” of polarization
integrals along the different directions. The other numbers specifie (the bulk polarization per unit cell is only well defined modulo f qe R,
the mesh used in the surface integrals. The last column specifies if being R an arbitrary lattice vector). However, the experimentally
the bidimensional grids are going to be diplaced from the origin or observable quantities are associated to changes in the polarization
not, as in the Monkhorst-Pack algorithm (PRB 13, 5188 (1976)). induced by changes on the atomic positions (dynamical charges),
This last column is optional. If the number of points in one of the strains (piezoelectric tensor), etc... The calculation of those changes,
grids is zero, the calculation will not be performed for this particular between different configurations of the solid, will be well defined as
direction. long as they are smaller than the “quantum”, i.e. the perturbations
are small enough to create small changes in the polarization.
For example, in the given example, for the computation in the di-
rection of the first lattice vector, 15 points will be used for the line BornCharge false (logical)

70
 If true, the Born effective charge tensor is calculated for each atom It is strongly recommended to read the original papers on which this
by finite differences, by calculating the change in electric polarization method is based and the documentation of wannier90 code. Here we
(see PolarizationGrids) induced by the small displacements gener- shall focus only on those internal SIESTA variables required to produce
ated for the force constants calculation (see MD.TypeOfRun FC): the files that will be processed by wannier90.
 A complete list of examples and tests (including molecules, metals, semi-
∗ Ω0 ∂Pα 
Zi,α,β =  (17) conductors, insulators, magnetic systems, plotting of Fermi surfaces or
e ∂ui,β q=0
interpolation of bands), can be downloaded from
where e is the charge of an electron and Ω0 is the unit cell volume. http://personales.unican.es/junqueraj/Wannier-examples.tar.gz
To calculate the Born charges it is necessary to specify both the
NOTE: The Bloch functions produced by a first-principles code have
Born charge flag and the mesh used to calculate the polarization, for
arbitrary phases that depend on the number of processors used and other
example:
possibly non-reproducible details of the calculation. In what follows it
%block PolarizationGrids is essential to maintain consistency in the handling of the overlap and
7 3 3 Bloch-funcion files produced and fed to wannier90.
3 7 3
3 3 7 Siesta2Wannier90.WriteMmn false (logical)
%endblock PolarizationGrids This flag determines whether the overlaps between the periodic part
BornCharge True
of the Bloch states at neighbour k-points are computed and dumped
The Born effective charge matrix is then written to the file into a file in the format required by wannier90. These overlaps are
SystemLabel.BC. defined in Eq. (27) in the paper by N. Marzari et al., Review of
The method by which the polarization is calculated may introduce an Modern Physics 84, 1419 (2012), or Eq. (1.7) of the Wannier90 User
arbitrary phase (polarization quantum), which in general is far larger Guide, Version 2.0.1.
than the change in polarization which results from the atomic dis- The k-points for which the overlaps will be computed are read from
placement. It is removed during the calculation of the Born effective a .nnkp file produced by wannier90. It is strongly recommended for
charge tensor. the user to read the corresponding user guide.
The Born effective charges allow the calculation of LO-TO splittings The overlap matrices are written in a file with extension .mmn.
and infrared activities. The version of the Vibra utility code in which
these magnitudes are calculated is not yet distributed with SIESTA, Siesta2Wannier90.WriteAmn false (logical)
but can be obtained form Tom Archer ([email protected]). This flag determines whether the overlaps between Bloch states and
trial localized orbitals are computed and dumped into a file in the
format required by wannier90. These projections are defined in Eq.
6.20 Maximally Localized Wannier Functions. (16) in the paper by N. Marzari et al., Review of Modern Physics
Interface with the wannier90 code 84, 1419 (2012), or Eq. (1.8) of the Wannier90 User Guide, Version
2.0.1.
wannier90 (http://www.wannier.org) is a code to generate maximally lo-
The localized trial functions to use are taken from the .nnkp file
calized wannier functions according to the original Marzari and Vanderbilt
produced by wannier90. It is strongly recommended for the user to
recipe.
read the corresponding user guide.

71
 The overlap matrices are written in a file with extension .amn. periodic part of the wave functions will be plotted.

Siesta2Wannier90.WriteEig false (logical) Siesta2Wannier90.UnkGridBinary true (logical)

Flag that determines whether the Kohn-Sham eigenvalues (in eV) Flag that determines whether the periodic part of the wave function
at each point in the Monkhorst-Pack mesh required by wannier90 in the real space grid is written in binary format (default) or in ASCII
are written to file. This file is mandatory in wannier90 if any of format.
disentanglement, plot_bands, plot_fermi_surface or hr_plot options
are set to true in the wannier90 input file. Siesta2Wannier90.NumberOfBands occupied bands (integer)
The eigenvalues are written in a file with extension .eigW. This ex- In spin unpolarized calculations, number of bands that will be ini-
tension is chosen to avoid name clashes with SIESTA’s standard tially considered by SIESTA to generate the information required by
eigenvalue file in case-insensitive filesystems. wannier90. Note that it should be at least as large as the index of the
highest-lying band in the wannier90 post-processing. For example,
Siesta2Wannier90.WriteUnk false (logical) if the wannierization is going to involve bands 3 to 5, the SIESTA
Produces UNKXXXXX.Y files which contain the periodic part of a Bloch number of bands should be at least 5. Bands 1 and 2 should appear
function in the unit cell on a grid given by global unk_nx, unk_ny, in a “excluded” list.
unk_nz variables. The name of the output files is assumed to have NOTE: you are highly encouraged to explicitly specify the number
the previous form, where the XXXXXX refer to the k-point index (from of bands.
00001 to the total number of k-points considered), and the Y refers
to the spin component (1 or 2) Siesta2Wannier90.NumberOfBandsUp
〈Siesta2Wannier90.NumberOfBands〉 (integer)
The periodic part of the Bloch functions is defined by
In spin-polarized calculations, number of bands with spin up that
~ ~
cnµ (~k)eik·(~rµ +RÂă−~r) φµ (~r − ~rµ − R),
~
X
un~k (~r) = (18) will be initially considered by SIESTA to generate the information
~
RÂăµ required by wannier90.
~ is a basis set atomic orbital centered on atom µ
where φµ (~r − ~rµ − R) Siesta2Wannier90.NumberOfBandsDown
~ and cnµ (~k) are the coefficients of the wave function.
in the unit cell R, 〈Siesta2Wannier90.NumberOfBands〉 (integer)
The latter must be identical to the ones used for wannierization in In spin-polarized calculations, number of bands with spin down that
Mmn . (See the above comment about arbitrary phases.) will be initially considered by SIESTA to generate the information
required by wannier90.
Siesta2Wannier90.UnkGrid1 〈mesh points along A〉 (integer)
Number of points along the first lattice vector in the grid where the
periodic part of the wave functions will be plotted. 6.21 Systems with net charge or dipole, and electric fields
NetCharge 0 (real)
Siesta2Wannier90.UnkGrid2 〈mesh points along B〉 (integer)
Specify the net charge of the system (in units of |e|). For charged sys-
Number of points along the second lattice vector in the grid where
tems, the energy converges very slowly versus cell size. For molecules
the periodic part of the wave functions will be plotted.
or atoms, a Madelung correction term is applied to the energy to
Siesta2Wannier90.UnkGrid3 〈mesh points along C〉 (integer) make it converge much faster with cell size (this is done only if the
Number of points along the third lattice vector in the grid where the cell is SC, FCC or BCC). For other cells, or for periodic systems

72
 (chains, slabs or bulk), this energy correction term can not be ap- SlabDipoleCorrection false (logical)
plied, and the user is warned by the program. It is not advised to If true, SIESTA calculates the electric field required to compensate
do charged systems other than atoms and molecules in SC, FCC or the dipole of the system at every iteration of the self-consistent cycle.
BCC cells, unless you know what you are doing. The potential added to the grid corresponds to that of a dipole layer
Use: For example, the F− ion would have NetCharge -1 , and the at the middle of the vacuum layer. For slabs, this exactly compen-
Na+ ion would have NetCharge 1. Fractional charges can also be sates the electric field at the vacuum created by the dipole moment
used. of the system, thus allowing to treat asymmetric slabs (including sys-
tems with an adsorbate on one surface) and compute properties such
SimulateDoping false (logical) as the work funcion of each of the surfaces.
This option instructs the program to add a background charge density NOTE: If the program is fed a starting density matrix from an uncor-
to simulate doping. The new “doping” routine calculates the net rected calculation (i.e., with an exagerated dipole), the first iteration
charge of the system, and adds a compensating background charge might use a compensating field that is too big, with the risk of taking
that makes the system neutral. This background charge is constant the system out of the convergence basin. In that case, it is advisable
at points of the mesh near the atoms, and zero at points far from the to use the SCF.Mix.First option to request a mix of the input and
atoms. This simulates situations like doped slabs, where the extra output density matrices after that first iteration.
electrons (holes) are compensated by oposite charges at the material
See Tests/sic-slab.
(the ionized dopant impurities), but not at the vacuum. This serves
to simulate properly doped systems in which there are large portions This will default to true if an external field is applied to a slab
of vacuum, such as doped slabs. calculation, otherwise it will default to false.
See Tests/sic-slab. For TranSIESTA calculations an additional step is added. For more
than 1 electrode, the dipole moments along the semi-infinite direc-
%block ExternalElectricField 〈None〉 (block) tions are removed. Otherwise, for 1 electrode, the dipole is only
It specifies an external electric field for molecules, chains and slabs. allowed along the semi-infinite direction.
The electric field should be orthogonal to ‘bulk directions’, like those
%block Geometry.Hartree 〈None〉 (block)
parallel to a slab (bulk electric fields, like in dielectrics or ferro-
electrics, are not allowed). If it is not, an error message is issued Allows introduction of regions with changed Hartree potential. Intro-
and the components of the field in bulk directions are suppressed au- ducing a potential can act as a repulsion (positive value) or attraction
tomatically. The input is a vector in Cartesian coordinates, in the (negative value) region.
specified units. Example: The regions are defined as geometrical objects and there are no limits
to the number of defined geometries.
%block ExternalElectricField
0.000 0.000 0.500 V/Ang Details regarding this implementation may be found in Papior
%endblock ExternalElectricField et al. [9] .
Currently 4 different kinds of geometries are allowed:
Starting with version 4.0, applying an electric field perpendicular to
a slab will by default enable the slab dipole correction, see Slab- Infinite plane Define a geometry by an infinite plane which cuts the
DipoleCorrection. To reproduce older calculations, set this cor- unit-cell.
rection option explicitly to false in the input file. This geometry is defined by a single point which is in the plane
and a vector normal to the plane.

73
 This geometry has 3 different settings: plane 1. eV # The lifting potential on the geometry
delta An infinite plane with δ-height. exp 1. 2. Ang # the half-length and the cut-off length
1.0 1.0 1.0 Ang # An intersection point, in the plane
gauss An infinite plane with a Gaussian distributed height profile. 1.0 0.5 0.2 # The normal vector to the plane
square 1. eV # The lifting potential on the geometry
exp An infinite plane with an exponentially distributed height pro- delta
file. 1.0 1.0 1.0 Ang # The starting point of the square
2.0 0.5 0.2 Ang # The first spanning vector
Bounded plane Define a geometric plane which is bounded, i.e. not
0.0 2.5 0.2 Ang # The second spanning vector
infinite. square 1. eV # The lifting potential on the geometry
This geometry is defined by an origo of the bounded plane and two gauss 1. 2. Ang # the std. and the cut-off length
vectors which span the plane, both originating in the respective 1.0 1.0 1.0 Ang # The starting point of the square
origo. 2.0 0.5 0.2 Ang # The first spanning vector
0.0 2.5 0.2 Ang # The second spanning vector
This geometry has 3 different settings:
square 1. eV # The lifting potential on the geometry
delta A plane with δ-height. exp 1. 2. Ang # the half-length and the cut-off length
1.0 1.0 1.0 Ang # The starting point of the square
gauss A plane with a Gaussian distributed height profile.
2.0 0.5 0.2 Ang # The first spanning vector
exp A plane with an exponentially distributed height profile. 0.0 2.5 0.2 Ang # The second spanning vector
box 1. eV # The lifting potential on the geometry
Box This geometry is defined by an origo of the box and three vectors delta
which span the box, all originating from the respective origo. 1.0 1.0 1.0 Ang # Origo of the box
This geometry has 1 setting: 2.0 0.5 0.2 Ang # The first spanning vector
0.0 2.5 0.2 Ang # The second spanning vector
delta No decay-region outside the box. 0.0 0.5 3.2 Ang # The third spanning vector
Spheres This geometry is defined by a list of spheres and a common coords 1. eV # The lifting potential on the geometry
radii. gauss 2. 4. Ang # First is std. deviation, second is cut-off
2 spheres # How many spheres in the following lines
This geometry has 2 settings: 0.0 4. 2. Ang # The centre coordinate of 1. sphere
gauss All spheres have an gaussian distribution about their centre. 1.3 4. 2. Ang # The centre coordinate of 2. sphere
coords 1. eV # The lifting potential on the geometry
exp All spheres have an exponential decay. exp 2. 4. Ang # First is half-length, second is cut-off rad
Here is a list of all options combined in one block: 2 spheres # How many spheres in the following lines
0.0 4. 2. Ang # The centre coordinate of 1. sphere
%block Geometry.Hartree 1.3 4. 2. Ang # The centre coordinate of 2. sphere
plane 1. eV # The lifting potential on the geometry %endblock Geometry.Hartree
delta
1.0 1.0 1.0 Ang # An intersection point, in the plane %block Geometry.Charge 〈None〉 (block)
1.0 0.5 0.2 # The normal vector to the plane
This is similar to the Geometry.Hartree block. However, instead
plane -1. eV # The lifting potential on the geometry
gauss 1. 2. Ang # the std. and the cut-off length
of specifying a potential, one defines the total charge that is spread
1.0 1.0 1.0 Ang # An intersection point, in the plane on the geometry.
1.0 0.5 0.2 # The normal vector to the plane To see how the input should be formatted, see Geometry.Hartree

74
 and remove the unit-specification. Note that the input value is num- If netCDF support is compiled in, the file RhoXC.grid.nc is pro-
ber of electrons (similar to NetCharge). duced.
Details regarding this implementation may be found in Papior
SaveElectrostaticPotential false (logical)
et al. [9] .
Instructs to write the total electrostatic potential, defined as the sum
of the hartree potential plus the local pseudopotential, at the mesh
6.22 Output of charge densities and potentials on the grid used by DHSCF, in file SystemLabel.VH. This file can be read by
routine IORHO, which may be used by an application program in
SIESTA represents these magnitudes on the real-space grid. The fol- later versions.
lowing options control the generation of the appropriate files, which Use: File .VH is only written, not read, by siesta.
can be processed by the programs in the Util/Grid directory, and also
If netCDF sup-
by Andrei Postnikov’s utilities in Util/Contrib/APostnikov. See also
port is compiled in, the file ElectrostaticPotential.grid.nc is
Util/Denchar for an alternative way to plot the charge density (and
produced.
wavefunctions).
SaveNeutralAtomPotential false (logical)
SaveRho false (logical)
Instructs to write the neutral-atom potential, defined as the sum
Instructs to write the valence pseudocharge density at the mesh used
of the hartree potential of a “pseudo atomic valence charge” plus
by DHSCF, in file SystemLabel.RHO.
the local pseudopotential, at the mesh used by DHSCF, in file
NOTE: file .RHO is only written, not read, by siesta. This file can SystemLabel.VNA. It is written at the start of the self-consistency
be read by routine IORHO, which may be used by other application cycle, as this potential does not change.
programs.
Use: File .VNA is only written, not read, by siesta.
If netCDF support is compiled in, the file Rho.grid.nc is produced.
If netCDF support is compiled in, the file Vna.grid.nc is produced.
SaveDeltaRho false (logical)
SaveTotalPotential false (logical)
Instructs to write δρ(~r) = ρ(~r) − ρatm (~r), i.e., the valence pseu-
Instructs to write the valence total effective local potential (local
docharge density minus the sum of atomic valence pseudocharge den-
pseudopotential + Hartree + Vxc), at the mesh used by DHSCF, in
sities. It is done for the mesh points used by DHSCF and it comes
file SystemLabel.VT. This file can be read by routine IORHO, which
in file SystemLabel.DRHO. This file can be read by routine IORHO,
may be used by an application program in later versions.
which may be used by an application program in later versions.
Use: File .VT is only written, not read, by siesta.
NOTE: file .DRHO is only written, not read, by siesta.
If netCDF support is compiled in, the file TotalPotential.grid.nc
If netCDF support is compiled in, the file DeltaRho.grid.nc is pro-
is produced.
duced.
NOTE: a side effect; the vacuum level, defined as the effective poten-
SaveRhoXC false (logical) tial at grid points with zero density, is printed in the standard output
Instructs to write the valence pseudocharge density at the mesh, in- whenever such points exist (molecules, slabs) and either SaveElec-
cluding the nonlocal core corrections used to calculate the exchange- trostaticPotential or SaveTotalPotential are true. In a symetric
correlation energy, in file SystemLabel.RHOXC. (nonpolar) slab, the work function can be computed as the difference
Use: File .RHOXC is only written, not read, by siesta. between the vacuum level and the Fermi energy.

75
SaveIonicCharge false (logical) (for example, see http://theory.cm.utexas.edu/bader/). Due to
Instructs to write the soft diffuse ionic charge at the mesh used by the need to represent a localized core charge, it is advisable to use a
DHSCF, in file SystemLabel.IOCH. This file can be read by rou- moderately high MeshCutoff when invoking this option (300-500 Ry).
tine IORHO, which may be used by an application program in later The size of the “basin of attraction” around each atom in the Bader
versions. Remember that, within the SIESTA sign convention, the analysis should be monitored to check that the model core charge is
electron charge density is positive and the ionic charge density is contained in it.
negative. The radii for the model core charges can be specified in the input fdf
Use: File .IOCH is only written, not read, by siesta. file. For example:
If netCDF support is compiled in, the file Chlocal.grid.nc is pro- bader-core-radius-standard 1.3 Bohr
duced. bader-core-radius-hydrogen 0.4 Bohr

SaveTotalCharge false (logical) The suggested way to run the Bader analysis with the Univ. of
Instructs to write the total charge density (ionic+electronic) at the Texas code is to use both the RHO and BADER files (both in “cube”
mesh used by DHSCF, in file SystemLabel.TOCH. This file can be format), with the BADER file providing the “reference” and the RHO
read by routine IORHO, which may be used by an application pro- file the actual significant valence charge data which is important in
gram in later versions. Remember that, within the SIESTA sign con- bonding. (See the notes for pseudopotential codes in the above web
vention, the electron charge density is positive and the ionic charge page.) For example, for the h2o-pop example:
density is negative. bader h2o-pop.RHO.cube -ref h2o-pop.BADER.cube
Use: File .TOCH is only written, not read, by siesta. If netCDF support is compiled in, the file BaderCharge.grid.nc is
If netCDF support is compiled in, the file TotalCharge.grid.nc is produced.
produced.
AnalyzeChargeDensityOnly false (logical)
SaveBaderCharge false (logical) If true, the program optionally generates charge density files and
Instructs the program to save the charge density for further post- computes partial atomic charges (Hirshfeld, Voronoi, Bader) from
processing by a Bader-analysis program. This “Bader charge” is the the information in the input density matrix, and stops. This is use-
sum of the electronic valence charge density and a set of “model core ful to analyze the properties of the charge density without a diag-
charges” placed at the atomic sites. For a given atom, the model onalization step, and with a user-selectable mesh cutoff. Note that
core charge is a generalized Gaussian, but confined to a radius of the DM.UseSaveDM option should be active. Note also that if
1.0 Bohr (by default), and integrating to the total core charge (Z- an initial density matrix (DM file) is used, it is not normalized. All
Zval ). These core charges are needed to provide local maxima for the relevant fdf options for charge-density file production and partial
the charge density at the atomic sites, which are not guaranteed charge calculation can be used with this option.
in a pseudopotential calculation. For hydrogen, an artificial core
of 1 electron is added, with a confinement radius of 0.6 Bohr by SaveInitialChargeDensity false (logical)
default. The Bader charge is projected on the grid points of the If true, the program generates a SystemLabel.RHOINIT file (and a
mesh used by DHSCF, and saved in file SystemLabel.BADER. This RhoInit.grid.nc file if netCDF support is compiled in) containing
file can be post-processed by the program Util/grid2cube to convert the charge density used to start the first self-consistency step, and it
it to the “cube” format, accepted by several Bader-analysis programs stops. Note that if an initial density matrix (DM file) is used, it is not

76
 normalized. This is useful to generate the charge density associated 2 3 Grimme 6.0 3.2
to “partial” DMs, as created by progras such as dm_creator and %endblock MM.Potentials
dm_filter. To automatically create input for Grimme’s method, please see the
(This option is to be deprecated in favor of AnalyzeChargeDensi- utility: Util/Grimme which can read an fdf file and create the correct
tyOnly). input for Grimme’s method.

MM.Cutoff 30 Bohr (length)

6.23 Auxiliary Force field
Specifies the distance out to which molecular mechanics potential will
It is possible to supplement the DFT interactions with a limited set of act before being treated as going to zero.
force-field options, typically useful to simulate dispersion interactions. It MM.UnitsEnergy eV (unit)
is not yet possible to turn off DFT and base the dynamics only on the
Specifies the units to be used for energy in the molecular mechanics
force field. The GULP program should be used for that.
potentials.
%block MM.Potentials 〈None〉 (block)
MM.UnitsDistance Ang (unit)
This block allows the input of molecular mechanics potentials be-
Specifies the units to be used for distance in the molecular mechanics
tween species. The following potentials are currently implemented:
potentials.
• C6, C8, C10 powers of the Tang-Toennes damped dispersion
potential. MM.Grimme.D 20.0 (real)
Specifies the scale factor d for the scaling function in the Grimme
• A harmonic interaction.
dispersion potential (see above).
• A dispersion potential of the Grimme type (similar to the C6
type but with a different damping function). (See S. Grimme, MM.Grimme.S6 1.66 (real)
J. Comput. Chem. Vol 27, 1787-1799 (2006)). See also Specifies the overall fitting factor s6 for the Grimme dispersion po-
MM.Grimme.D and MM.Grimme.S6 below. tential (see above). This number depends on the quality of the basis
The format of the input is the two species numbers that are to inter- set, the exchange-correlation functional, and the fitting set.
act, the potential name (C6, C8, C10, harm, or Grimme), followed
by the potential parameters. For the damped dispersion potentials 6.24 Parallel options
the first number is the coefficient and the second is the exponent of
the damping term (i.e., a reciprocal length). A value of zero for the BlockSize 〈automatic〉 (integer)
latter term implies no damping. For the harmonic potential the force The orbitals are distributed over the processors when running in par-
constant is given first, followed by r0. For the Grimme potential C6 allel using a 1-D block-cyclic algorithm. BlockSize is the number
is given first, followed by the (corrected) sum of the van der Waals of consecutive orbitals which are located on a given processor before
radii for the interacting species (a real length). Positive values of the moving to the next one. Large values of this parameter lead to poor
C6, C8, and C10 coefficients imply attractive potentials. load balancing, while small values can lead to inefficient execution.
The performance of the parallel code can be optimised by varying
%block MM.Potentials
1 1 C6 32.0 2.0
this parameter until a suitable value is found.
1 2 harm 3.0 1.4

77
 ProcessorY 〈automatic〉 (integer) achieve better load balance in some cases. This is controlled by the
The mesh points are divided in the Y and Z directions (more precisely, variable RcSpatial.
along the second and third lattice vectors) over the processors in a 2-D NOTE: the distribution algorithm is quite fragile and a careful tun-
grid. ProcessorY specifies the dimension of the processor grid in the ing of RcSpatial might be needed. This option is therefore not
Y-direction and must be a factor of the total number of processors. enabled by default.
Ideally the processors should be divided so that the number of mesh
points per processor along each axis is as similar as possible. RcSpatial 〈maximum orbital range〉 (length)
Defaults to a multiple of number of processors. Controls the cell size during the spatial decomposition.

6.24.1 Parallel decompositions for O(N) 6.25 Efficiency options

DirectPhi false (logical)
Apart from the default block-cyclic decomposition of the orbital data,
The calculation of the matrix elements on the mesh requires the value
O(N) calculations can use other schemes which should be more efficient:
of the orbitals on the mesh points. This array represents one of the
spatial decomposition (based on atom proximity), and domain decompo-
largest uses of memory within the code. If set to true this option
sition (based on the most efficient abstract partition of the interaction
allows the code to generate the orbital values when needed rather
graph of the Hamiltonian).
than storing the values. This obviously costs more computer time
UseDomainDecomposition false (logical) but will make it possible to run larger jobs where memory is the
This option instructs the program to employ a graph-partitioning al- limiting factor.
gorithm (using the METIS library (See www.cs.umn.edu/~metis) to This controls whether the values of the orbitals at the mesh points
find an efficient distribution of the orbital data over processors. To are stored or calculated on the fly.
use this option (meaningful only in parallel) the program has to be
compiled with the preprocessor option SIESTA__METIS (or the dep- 6.26 Memory, CPU-time, and Wall time accounting op-
recated ON_DOMAIN_DECOMP) and the METIS library has to be linked tions
in.
AllocReportLevel 0 (integer)
UseSpatialDecomposition false (logical) Sets the level of the allocation report, printed
When performing a parallel order N calculation, this option instructs in file SystemLabel.alloc. However, not all the allocated arrays
the program to execute a spatial decomposition algorithm in which are included in the report (this will be corrected in future versions).
the system is divided into cells, which are then assigned, together The allowed values are:
with the orbitals centered in them, to the different processors. The
size of the cells is, by default, equal to the maximum distance at which • level 0 : no report at all (the default)
there is a non-zero matrix element in the Hamiltonian between two • level 1 : only total memory peak and where it occurred
orbitals, or the radius of the Localized Wannier function - which ever • level 2 : detailed report printed only at normal program termi-
is the larger. If this is the case, then an orbital will only interact nation
with other orbitals in the same or neighbouring cells. However, by • level 3 : detailed report printed at every new memory peak
decreasing the cell size and searching over more cells it is possible to
• level 4 : print every individual (re)allocation or deallocation

78
 NOTE: In MPI runs, only node-0 peak reports are produced. by MaxWalltime.Slack. See Sec. 16 for available units of time (s,
mins, hours, days).
AllocReportThreshold 0. (real)
Sets the minimum size (in bytes) of the arrays whose memory use is MaxWalltime.Slack 5 s (real time)
individually printed in the detailed allocation reports (levels 2 and The code checks its wall time Twall periodically and will abort if
3). It does not affect the reported memory sums and peaks, which Twall > Tmax − Tslack , so that some slack is left for any clean-up
always include all arrays. operations.

TimerReportThreshold 0. (real)
Sets the minimum fraction, of total CPU time, of the subroutines or 6.27 The catch-all option UseSaveData
code sections whose CPU time is individually printed in the detailed
timer reports. To obtain the accounting of MPI communication times This is a dangerous feature, and is deprecated, but retained for historical
in parallel executions, you must compile with option -DMPI_TIMING. compatibility. Use the individual options instead.
In serial execution, the CPU times are printed at the end of the UseSaveData false (logical)
output file. In parallel execution, they are reported in a separated
Instructs to use as much information as possible stored from
file named SystemLabel.times.
previous runs in files SystemLabel.XV, SystemLabel.DM and
UseTreeTimer false (logical) SystemLabel.LWF,
Enable an experimental timer which is based on wall time on the NOTE: if the files are not existing it will read the information from
master node and is aware of the tree-structure of the timed sections. the fdf file.
At the end of the program, a report is generated in the output file,
and a time.json file in JSON format is also written. This file can 6.28 Output of information for Denchar
be used by third-party scripts to process timing data.
NOTE: , if used with the PEXSI solver (see Sec. 6.13) this defaults The program denchar in Util/Denchar can generate charge-density and
to true. wavefunction information in real space.

UseParallelTimer true (logical) Write.Denchar false (logical)

Determine whether timings are performed in parallel. This may in- Instructs to write information needed by the utility program
troduce slight overhead. DENCHAR (by J. Junquera and P. Ordejón) to generate va-
NOTE: , if used with the PEXSI solver (see Sec. 6.13) this defaults lence charge densities and/or wavefunctions in real space (see
to false. Util/Denchar). The information is written in files SystemLabel.PLD
and SystemLabel.DIM.
MaxWalltime Infinity (real time) To run DENCHAR you will need, apart from the .PLD and .DIM files,
Set an internal limit to the wall time allotted to the program’s ex- the Density-Matrix (DM) file and/or a wavefunction (.WFSX) file, and
ecution. Typically this is related to the external limit imposed by the .ion files containing the information about the basis orbitals.
queuing systems. The code checks its wall time periodically and will
abort if nearing the limit, with some slack left for clean-up oper-
ations (proper closing of files, emergency output...), as determined

79
6.29 NetCDF (CDF4) output file NOTE: this is an experimental flag.

NOTE: this requires SIESTA compiled with CDF4 support. CDF.Grid.Precision single|double (string)
At which precision should the real-space grid quantities be stored,
To unify and construct a simple output file for an entire SIESTA calcu-
such as the density, electrostatic potential etc.
lation a generic NetCDF file will be created if SIESTA is compiled with
ncdf support, see Sec. 2.4 and the ncdf section.
Generally all output to NetCDF flags, SaveElectrostaticPotential, etc.
apply to this file as well. 7 STRUCTURAL RELAXATION, PHONONS,
One may control the output file with compressibility and parallel I/O, if AND MOLECULAR DYNAMICS
needed.
This functionality is not SIESTA-specific, but is implemented to provide
CDF.Save false (logical) a more complete simulation package. The program has an outer geom-
Create the SystemLabel.nc file which is a NetCDF file. etry loop: it computes the electronic structure (and thus the forces and
This file will be created with a large set of groups which make sepa- stresses) for a given geometry, updates the atomic positions (and maybe
rating the quantities easily. Also it will inherently denote the units the cell vectors) accordingly and moves on to the next cycle. If there are
for the stored quantities. molecular dynamics options missing you are highly recommend to look
NOTE: this option is not available for MD/relaxations, only for force into MD.TypeOfRun Lua or MD.TypeOfRun Master.
constant runs. Several options for MD and structural optimizations are implemented,
selected by
CDF.Compress 0 (integer)
Integer between 0 and 9. The former represents no compressing and MD.TypeOfRun CG (string)
the latter is the highest compressing.
CG Coordinate optimization by conjugate gradients). Optionally (see
The higher the number the more computation time is spent on com- variable MD.VariableCell below), the optimization can include
pressing the data. A good compromise between speed and compres- the cell vectors.
sion is 3.
NOTE: if one requests parallel I/O (CDF.MPI) this will automat- Broyden Coordinate optimization by a modified Broyden scheme).
ically be set to 0. One cannot perform parallel IO and compress the Optionally, (see variable MD.VariableCell below), the optimiza-
data simultaneously. tion can include the cell vectors.
NOTE: instead of using SIESTA for compression you may compress FIRE Coordinate optimization by Fast Inertial Relaxation Engine
after execution by: (FIRE) (E. Bitzek et al, PRL 97, 170201, (2006)). Optionally, (see
variable MD.VariableCell below), the optimization can include
nccopy -d 3 -s noncompressed.nc compressed.nc
the cell vectors.
CDF.MPI false (logical) Verlet Standard Verlet algorithm MD
Write SystemLabel.nc in parallel using MPI for increased perfor-
mance. This has almost no memory overhead but may for very large Nose MD with temperature controlled by means of a Nosé thermostat
number of processors saturate the file-system. ParrinelloRahman MD with pressure controlled by the Parrinello-

80
 Rahman method NOTE: if Compat.Pre-v4-Dynamics is true this will default to
Verlet.
NoseParrinelloRahman MD with temperature controlled by means
of a Nosé thermostat and pressure controlled by the Parrinello- Note that some options specified in later variables (like quenching)
Rahman method modify the behavior of these MD options.
Appart from being able to act as a force subroutine for a driver
Anneal MD with annealing to a desired temperature and/or pressure
program that uses module fsiesta,
(see variable MD.AnnealOption below)
SIESTA is also prepared to communicate with the i-PI code (see
FC Compute force constants matrix for phonon calculations. http://epfl-cosmo.github.io/gle4md/index.html?page=ipi).
To do this, SIESTA must be started after i-PI (it acts as a client of
Master|Forces Receive coordinates from, and return forces to, an
i-PI, communicating with it through Inet or Unix sockets), and the
external driver program, using MPI, Unix pipes, or Inet sock-
following lines must be present in the .fdf data file:
ets for communication. The routines in module fsiesta allow
the user’s program to perform this communication transparently, MD.TypeOfRun Master # equivalent to ’Forces’
as if SIESTA were a conventional force-field subroutine. See Master.code i-pi # ( fsiesta | i-pi )
Master.interface socket # ( pipes | socket | mpi )
Util/SiestaSubroutine/README for details. WARNING: if this
Master.address localhost # or driver’s IP, e.g. 150.242.7
option is specified without a driver program sending data, siesta Master.port 10001 # 10000+siesta_process_order
may hang without any notice. Master.socketType inet # ( inet | unix )
See directory Util/Scripting for other driving options.
Lua Fully control the MD cycle and convergence path using an ex- 7.1 Compatibility with pre-v4 versions
ternal Lua script.
With an external Lua script one may control nearly everything Starting in the summer of 2015, some changes were made to the behavior
from a script. One can query any internal data-structures in of the program regarding default dynamics options and choice of coor-
SIESTA and, similarly, return any data thus overwriting the in- dinates to work with during post-processing of the electronic structure.
ternals. A list of ideas which may be implemented in such a Lua The changes are:
script are:
• The default dynamics option is “CG” instead of “Verlet”.
• New geometry relaxation algorithms
• NEB calculations • The coordinates, if moved by the dynamics routines, are reset to
• New MD routines their values at the previous step for the analysis of the electronic
• Convergence tests of MeshCutoff and structure (band structure calculations, DOS, LDOS, etc).
kgrid.MonkhorstPack, or other parameters (currently basis • Some output files reflect the values of the “un-moved” coordinates.
set optimizations cannot be performed in the Lua script).
• The
Sec. 9 for additional details (and a description of flos which im-
default convergence criteria is now both density and Hamiltonian
plements some of the above mentioned items).
convergence, see SCF.DM.Converge and SCF.H.Converge.
Using this option requires the compilation of SIESTA with the
flook library.If SIESTA is not compiled as prescribed in Sec. 2.4 To recover the previous behavior, the user can turn on the compatibility
this option will make SIESTA die. switch Compat.Pre-v4-Dynamics, which is off by default.

81
Note that complete compatibility cannot be perfectly guaranteed. Force tolerance in coordinate optimization. Run stops if the
maximum atomic force is smaller than MD.MaxForceTol (see
MD.MaxStressTol for variable cell).
7.2 Structural relaxation
MD.MaxStressTol 1 GPa (pressure)
In this mode of operation, the program moves the atoms (and optionally Stress tolerance in variable-cell CG optimization. Run stops if the
the cell vectors) trying to minimize the forces (and stresses) on them. maximum atomic force is smaller than MD.MaxForceTol and the
These are the options common to all relaxation methods. If the Zmatrix maximum stress component is smaller than MD.MaxStressTol.
input option is in effect (see Sec. 6.4.2) the Zmatrix-specific options take Special consideration is needed if used with Sankey-type basis sets,
precedence. The ’MD’ prefix is misleading but kept for historical reasons. since the combination of orbital kinks at the cutoff radii and the finite-
grid integration originate discontinuities in the stress components,
MD.VariableCell false (logical)
whose magnitude depends on the cutoff radii (or energy shift) and the
If true, the lattice is relaxed together with the atomic coordinates. It mesh cutoff. The tolerance has to be larger than the discontinuities
allows to target hydrostatic pressures or arbitrary stress tensors. See to avoid endless optimizations if the target stress happens to be in a
MD.MaxStressTol, MD.TargetPressure, MD.TargetStress, discontinuity.
MD.ConstantVolume, and MD.PreconditionVariableCell.
NOTE: only compatible with MD.TypeOfRun CG, Broyden or MD.Steps 0 (integer)
fire. depends on: MD.NumCGsteps
Maximum number of steps in a minimization routine (the minimiza-
MD.ConstantVolume false (logical) tion will stop if tolerance is reached before; see MD.MaxForceTol
If true, the cell volume is kept constant in a variable-cell relaxation: below).
only the cell shape and the atomic coordinates are allowed to change. NOTE: The old flag MD.NumCGsteps will remain for historical
Note that it does not make much sense to specify a target stress or reasons.
pressure in this case, except for anisotropic (traceless) stresses. See
MD.VariableCell, MD.TargetStress. MD.MaxDispl 0.2 Bohr (length)
NOTE: only compatible with MD.TypeOfRun CG, Broyden or depends on: MD.MaxCGDispl

fire. Maximum atomic displacements in an optimization move.

In the Broyden optimization method, it is
MD.RelaxCellOnly false (logical) also possible to limit indirectly the initial atomic displacements using
If true, only the cell parameters are relaxed (by the Broyden or MD.Broyden.Initial.Inverse.Jacobian. For the FIRE method,
FIRE method, not CG). The atomic coordinates are re-scaled to the the same result can be obtained by choosing a small time step.
new cell, keeping the fractional coordinates constant. For Zmatrix Note that there are Zmatrix-specific options that override this option.
calculations, the fractional position of the first atom in each molecule
NOTE: The old flag MD.MaxCGDispl will remain for historical
is kept fixed, and no attempt is made to rescale the bond distances
reasons.
or angles.
NOTE: only compatible with MD.TypeOfRun Broyden or fire. MD.PreconditionVariableCell 5 Ang (length)
A length to multiply to the strain components in a variable-cell op-
MD.MaxForceTol 0.04 eV/Ang (force)
timization. The strain components enter the minimization on the

82
 same footing as the coordinates. For good efficiency, this length 7.2.2 Broyden optimization
should make the scale of energy variation with strain similar to the
one due to atomic displacements. It is also used for the application It uses the modified Broyden algorithm to build up the Jacobian matrix.
of the MD.MaxCGDispl value to the strain components. (See D.D. Johnson, PRB 38, 12807 (1988)). (Note: This is not BFGS.)

ZM.ForceTolLength 0.00155574 Ry/Bohr (force) MD.Broyden.History.Steps 5 (integer)

Parameter that controls the convergence with respect to forces on Number of relaxation steps during which the modified Broyden algo-
Z-matrix lengths rithm builds up the Jacobian matrix.

ZM.ForceTolAngle 0.00356549 Ry/rad (torque) MD.Broyden.Cycle.On.Maxit true (logical)

Parameter that controls the convergence with respect to forces on Upon reaching the maximum number of history data sets which are
Z-matrix angles kept for Jacobian estimation, throw away the oldest and shift the
rest to make room for a new data set. The alternative is to re-start
ZM.MaxDisplLength 0.2 Bohr (length) the Broyden minimization algorithm from a first step of a diagonal
Parameter that controls the maximum change in a Z-matrix length inverse Jacobian (which might be useful when the minimization is
during an optimisation step. stuck).
ZM.MaxDisplAngle 0.003 rad (angle) MD.Broyden.Initial.Inverse.Jacobian 1 (real)
Parameter that controls the maximum change in a Z-matrix angle Initial inverse Jacobian for the optimization procedure. (The units
during an optimisation step. are those implied by the internal Siesta usage. The default value
seems to work well for most systems.
7.2.1 Conjugate-gradients optimization
7.2.3 FIRE relaxation
This was historically the default geometry-optimization method, and all
the above options were introduced specifically for it, hence their names. Implementation of the Fast Inertial Relaxation Engine (FIRE) method (E.
The following pertains only to this method: Bitzek et al, PRL 97, 170201, (2006) in a manner compatible with the CG
and Broyden modes of relaxation. (An older implementation activated by
MD.UseSaveCG false (logical)
the MD.FireQuench variable is still available).
Instructs to read the conjugate-gradient hystory information stored
in file SystemLabel.CG by a previous run. MD.FIRE.TimeStep 〈MD.LengthTimeStep〉 (time)
NOTE: to get actual continuation of iterrupted CG runs, use to- The (fictitious) time-step for FIRE relaxation. This is the main user-
gether with MD.UseSaveXV true with the .XV file generated in variable when the option FIRE for MD.TypeOfRun is active.
the same run as the CG file. If the required file does not exist, a NOTE: the default value is encouraged to be changed as the link to
warning is printed but the program does not stop. Overrides Us- MD.LengthTimeStep is misleading.
eSaveData. There are other low-level options tunable by the user (see the routines
NOTE: no such feature exists yet for a Broyden-based relaxation. fire_optim and cell_fire_optim for more details.

83
7.3 Target stress options tal stresses are printed in addition to the uncorrected items. The
corrected Voigt form is also printed.
Useful for structural optimizations and constant-pressure molecular dy-
namics.
7.4 Molecular dynamics
MD.TargetPressure 0 GPa (pressure)
Target pressure for Parrinello-Rahman method, variable cell opti- In this mode of operation, the program moves the atoms (and optionally
mizations, and annealing options. the cell vectors) in response to the forces (and stresses), using the classical
equations of motion.
NOTE: this is only compatible with MD.TypeOfRun Parrinel-
loRahman, NoseParrinelloRahman, CG, Broyden or FIRE Note that the Zmatrix input option (see Sec. 6.4.2) is not compatible
(variable cell), or Anneal (if MD.AnnealOption Pressure or with molecular dynamics. The initial geometry can be specified using
TemperatureandPressure). the Zmatrix format, but the Zmatrix generalized coordinates will not be
updated.
%block MD.TargetStress −1 − 1 − 1000 (block)
External or target stress tensor for variable cell optimizations. Stress MD.InitialTimeStep 1 (integer)
components are given in a line, in the order xx, yy, zz, xy, xz, Initial time step of the MD simulation. In the current version of
yz. In units of MD.TargetPressure, but with the opposite sign. SIESTA it must be 1.
For example, a uniaxial compressive stress of 2 GPa along the 100 Used only if MD.TypeOfRun is not CG or Broyden.
direction would be given by
MD.FinalTimeStep 〈MD.Steps〉 (integer)
MD.TargetPressure 2. GPa
%block MD.TargetStress Final time step of the MD simulation.
-1.0 0.0 0.0 0.0 0.0 0.0
MD.LengthTimeStep 1 fs (time)
%endblock MD.TargetStress
Length of the time step of the MD simulation.
Only used if MD.TypeOfRun is CG, Broyden or FIRE and
MD.VariableCell is true. MD.InitialTemperature 0 K (temperature/energy)
Initial temperature for the MD run. The atoms are assigned random
MD.RemoveIntramolecularPressure false (logical) velocities drawn from the Maxwell-Bolzmann distribution with the
If true, the contribution to the stress coming from the internal de- corresponding temperature. The constraint of zero center of mass
grees of freedom of the molecules will be subtracted from the stress velocity is imposed.
tensor used in variable-cell optimization or variable-cell molecular- NOTE: only used if MD.TypeOfRun Verlet, Nose, Parrinel-
dynamics. This is done in an approximate manner, using the virial loRahman, NoseParrinelloRahman or Anneal.
form of the stress, and assumming that the “mean force” over the co-
ordinates of the molecule represents the “inter-molecular” stress. The MD.TargetTemperature 0 K (temperature/energy)
correction term was already computed in earlier versions of SIESTA Target temperature for Nose thermostat and annealing options.
and used to report the “molecule pressure”. The correction is now NOTE: only used if MD.TypeOfRun Nose, NoseParrinel-
computed molecule-by-molecule if the Zmatrix format is used. loRahman or Anneal if MD.AnnealOption is Temperature or
If the intra-molecular stress is removed, the corrected static and to- TemperatureandPressure.

84
MD.NoseMass 100 Ry fs2 (moment of inertia) Only applicable for MD.TypeOfRun Anneal, when
Generalized mass of Nose variable. This determines the time scale of MD.AnnealOption is Pressure or TemperatureAndPressure
the Nose variable dynamics, and the coupling of the thermal bath to
the physical system. 7.5 Output options for dynamics
Only used for Nose MD runs.
Every time the atoms move, either during coordinate relaxation or molec-
MD.ParrinelloRahmanMass 100 Ry fs2 (moment of inertia)
ular dynamics, their positions predicted for next step and current
Generalized mass of Parrinello-Rahman variable. This determines velocities are stored in file SystemLabel.XV. The shape of the unit cell
the time scale of the Parrinello-Rahman variable dynamics, and its and its associated ’velocity’ (in Parrinello-Rahman dynamics) are also
coupling to the physical system. stored in this file.
Only used for Parrinello-Rahman MD runs.
WriteCoorInitial true (logical)
MD.AnnealOption TemperatureAndPressure (string) It determines whether the initial atomic coordinates of the simula-
Type of annealing MD to perform. The target temperature or pres- tion are dumped into the main output file. These coordinates cor-
sure are achieved by velocity and unit cell rescaling, in a given time respond to the ones actually used in the first step (see the section
determined by the variable MD.TauRelax below. on precedence issues in structural input) and are output in Cartesian
Temperature Reach a target temperature by velocity rescaling coordinates in Bohr units.
It is not affected by the setting of LongOutput.
Pressure Reach a target pressure by scaling of the unit cell size and
shape WriteCoorStep false (logical)
TemperatureandPressure Reach a target temperature and pres- If true, it writes the atomic coordinates to standard output at every
sure by velocity rescaling and by scaling of the unit cell size and MD time step or relaxation step. The coordinates are always written
shape in the SystemLabel.XV file, but overriden at every step. They can
be also accumulated in the .MD or SystemLabel.MDX files depending
Only applicable for MD.TypeOfRun Anneal. on WriteMDHistory.
MD.TauRelax 100 fs (time) WriteForces false (logical)
Relaxation time to reach target temperature and/or pressure in an- If true, it writes the atomic forces to the output file at every MD
nealing MD. Note that this is a “relaxation time”, and as such it gives time step or relaxation step. Note that the forces of the last step can
a rough estimate of the time needed to achieve the given targets. As be found in the file SystemLabel.FA. If constraints are used, the file
a normal simulation also exhibits oscillations, the actual time needed SystemLabel.FAC is also written.
to reach the averaged targets will be significantly longer.
Only applicable for MD.TypeOfRun Anneal. WriteMDHistory false (logical)
If true, SIESTA accumulates the molecular dynamics trajectory in
MD.BulkModulus 100 Ry/Bohr3 (pressure) the following files:
Estimate (may be rough) of the bulk modulus of the system. This is
needed to set the rate of change of cell shape to reach target pressure • SystemLabel.MD : atomic coordinates and velocities (and lat-
in annealing MD. tice vectors and their time derivatives, if the dynamics implies

85
 variable cell). The information is stored unformatted for post- unit cell and its associated ’velocity’ (in Parrinello-Rahman dynamics)
processing with utility programs to analyze the MD trajectory. are also stored in this file. For MD runs of type Verlet, Parrinello-
• SystemLabel.MDE : shorter description of the run, with energy, Rahman, Nose, Nose-Parrinello-Rahman, or Anneal, a file named Sys-
temperature, etc., per time step. temLabel.VERLET_RESTART, SystemLabel.PR_RESTART, System-
Label.NOSE_RESTART, SystemLabel.NPR_RESTART, or SystemLa-
These files are accumulative even for different runs. bel.ANNEAL_RESTART, respectively, is created to hold the values of
The trajectory of a molecular dynamics run (or a conjugate gra- auxiliary variables needed for a completely seamless continuation.
dient minimization) can be accumulated in different files: System-
If the restart file is not available, a simulation can still make use of the
Label.MD, SystemLabel.MDE, and SystemLabel.ANI. The first file
XV information, and “restart” by basically repeating the last-computed
keeps the whole trajectory information, meaning positions and ve-
step (the positions are shifted backwards by using a single Euler-like step
locities at every time step, including lattice vectors if the cell varies.
with the current velocities as derivatives). While this feature does not
NOTE that the positions (and maybe the cell vectors) stored at each
result in seamless continuations, it allows cross-restarts (those in which a
time step are the predicted values for the next step. Care should be
simulation of one kind (e.g., Anneal) is followed by another (e.g., Nose)),
taken if joint position-velocity correlations need to be computed from
and permits to re-use dynamical information from old runs.
this file. The second gives global information (energy, temperature,
etc), and the third has the coordinates in a form suited for XMol This restart fix is not satisfactory from a fundamental point of view, so
animation. See the WriteMDHistory and WriteMDXmol data the MD subsystem in Siesta will have to be redesigned eventually. In
descriptors above for information. SIESTA always appends new in- the meantime, users are reminded that the scripting hooks being steadily
formation on these files, making them accumulative even for different introduced (see Util/Scripting) might be used to create custom-made MD
runs. scripts.
The iomd subroutine can generate both an unformatted file .MD (de-
fault) or ASCII formatted files .MDX and .MDC containing the atomic 7.7 Use of general constraints
and lattice trajectories, respectively. Edit the file to change the set-
tings if desired. Note: The Zmatrix format (see Sec. 6.4.2) provides an alternative con-
straint formulation which can be useful for system involving molecules.
Write.OrbitalIndex true (logical)
If true it causes the writing of %block Geometry.Constraints 〈None〉 (block)
an extra file named SystemLabel.ORB_INDX containing all orbitals Constrains certain atomic coordinates or cell parameters in a consis-
used in the calculation. tent method.
Its formatting is clearly specified at the end of the file. There are a high number of configurable parameters that may be
used to control the relaxation of the coordinates.
7.6 Restarting geometry optimizations and MD runs NOTE: SIESTA prints out a small section of how the constraints
are recognized.
Every time the atoms move, either during coordinate relaxation or molec- atom|position Fix certain atomic coordinates.
ular dynamics, their positions predicted for next step and current
This option takes a variable number of integers which each corre-
velocities are stored in file SystemLabel.XV, where SystemLabel is the
spond to the atomic index (or input sequence) in AtomicCoor-
value of that fdf descriptor (or ’siesta’ by default). The shape of the
dinatesAndAtomicSpecies.

86
 atom is now the preferred input option while position still works NOTE: this specification is apt for directional constraints.
for backwards compatibility.
rigid|molecule Move a selection of atoms together as though they
One may also specify ranges of atoms according to: where one atom.
atom A [B [C [. . . ]]] A sequence of atomic indices which are con- The forces are summed and averaged to get a net-force on the
strained. entire molecule.
atom from A to B [step s] Here atoms A up to and including B Atomic indices may be specified according to atom.
are constrained. If step <s> is given, the range A:B will be NOTE: this specification is apt for directional constraints.
taken in steps of s.
rigid-max|molecule-max Move a selection of atoms together as
atom from 3 to 10 step 2 though they where one atom.
will constrain atoms 3, 5, 7 and 9. The maximum force acting on one of the atoms in the selection
atom from A plus/minus B [step s] Here atoms A up to and will be expanded to act on all atoms specified.
including A + B − 1 are constrained. If step <s> is given, the Atomic indices may be specified according to atom.
range A:A + B − 1 will be taken in steps of s. cell-angle Control whether the cell angles (α, β, γ) may be altered.
atom [A, B -- C [step s], D] Equivalent to from . . . to speci- This takes either one or more of alpha/beta/gamma as argu-
fication, however in a shorter variant. Note that the list may ment.
contain arbitrary number of ranges and/or individual indices. alpha is the angle between the 2nd and 3rd cell vector.
atom [2, 3 -- 10 step 2, 6] beta is the angle between the 1st and 3rd cell vector.
will constrain atoms 2, 3, 5, 7, 9 and 6. gamma is the angle between the 1st and 2nd cell vector.
atom [2, 3 -- 6, 8] NOTE: currently only one angle can be constrained at a time and
it forces only the spanning vectors to be relaxed.
will constrain atoms 2, 3, 4, 5, 6 and 8.
cell-vector Control whether the cell vectors (A, B, C) may be al-
atom all Constrain all atoms.
tered.
NOTE: these specifications are apt for directional constraints. This takes either one or more of A/B/C as argument.
Z Equivalent to atom with all indices of the atoms that have atomic Constraining the cell-vectors are only allowed if they only have a
number equal to the specified number. component along their respective Cartesian direction. I.e. B must
NOTE: this specification is apt for directional constraints. only have a y-component.
species-i Equivalent to atom with all indices of the atoms that have stress Control which of the 6 stress components are constrained.
species according to the ChemicalSpeciesLabel and Atomic- This takes a number of integers 1 ≤ i ≤ 6 where 1 corresponds
CoordinatesAndAtomicSpecies. to the AA stress-component, 2 is BB, 3 is CC, 4 is BC /CB, 5 is
NOTE: this specification is apt for directional constraints. AC /CA and 6 is AB/BA.
center One may retain the coordinate center of a range of atoms (say routine This calls the constr routine specified in the file: constr.f.
molecules or other groups of atoms). Without having changed the corresponding source file, this does
Atomic indices may be specified according to atom. nothing. See details and comments in the source-file.

87
clear Remove constraints on selected atoms from all previously spec- %block Geometry.Constraints
ified constraints. atom all
clear-prev [2 -- 12 step 2]
This may be handy when specifying constraints via Z or species-i.
%endblock
Atomic indices may be specified according to atom.
where the 3 last blocks all create the same result.
clear-prev Remove constraints on selected atoms from the previous
Finally, the directional constraint is an important and often useful
specified constraint.
feature. When relaxing complex structures it may be advantageous
This may be handy when specifying constraints via Z or species-i. to first relax along a given direction (where you expect the stress
Atomic indices may be specified according to atom. to be largest) and subsequently let it fully relax. Another example
NOTE: two consecutive clear-prev may be used in conjunction would be to relax the binding distance between a molecule and a
as though the atoms where specified on the same line. surface, before relaxing the entire system by forcing the molecule
It is instructive to give an example of the input options presented. and adsorption site to relax together. To use directional constraint
one may provide an additional 3 reals after the atom/rigid. For
Consider a benzene molecule (C6 H6 ) and we wish to relax all Hydro-
instance in the previous example (benzene) one may first relax all
gen atoms. This may be accomplished in this fashion
Hydrogen atoms along the y and z Cartesian vector by constraining
%block Geometry.Constraints the x Cartesian vector
Z 6
%endblock %block Geometry.Constraints
Z 6 # constrain Carbon
Or as in this example Z 1 1. 0. 0. # constrain Hydrogen along x Cartesian vector
%endblock
%block AtomicCoordinatesAndAtomicSpecies
... ... ... 1 # C 1 Note that you must append a “.” to denote it a real. The vector spec-
... ... ... 2 # H 2 ified need not be normalized. Also, if you want it to be constrained
... ... ... 1 # C 3 along the x-y vector you may do
... ... ... 2 # H 4
... ... ... 1 # C 5 %block Geometry.Constraints
... ... ... 2 # H 6 Z 6
... ... ... 1 # C 7 Z 1 1. 1. 0.
... ... ... 2 # H 8 %endblock
... ... ... 1 # C 9
... ... ... 2 # H 10
... ... ... 1 # C 11 7.8 Phonon calculations
... ... ... 2 # H 12
%endblock If MD.TypeOfRun is FC, SIESTA sets up a special outer geometry
%block Geometry.Constraints loop that displaces individual atoms along the coordinate directions to
atom from 1 to 12 step 2 build the force-constant matrix.
%endblock
%block Geometry.Constraints The output (see below) can be analyzed to extract phonon frequencies
atom [1 -- 12 step 2] and vectors with the VIBRA package in the Util/Vibra directory. For
%endblock computing the Born effective charges together with the force constants,

88
see BornCharge. LDAU.ProjectorGenerationMethod 2 (integer)
Generation method of the LDA+U projectors. The LDA+U projec-
MD.FCDispl 0.04 Bohr (length)
tors are the localized functions used to calculate the local populations
Displacement to use for the computation of the force constant matrix used in a Hubbard-like term that modifies the LDA Hamiltonian and
for phonon calculations. energy. It is important to recall that LDA+U projectors should be
MD.FCFirst 1 (integer) quite localized functions. Otherwise the calculated populations loose
their atomic character and physical meaning. Even more importantly,
Index of first atom to displace for the computation of the force con-
the interaction range can increase so much that jeopardizes the effi-
stant matrix for phonon calculations.
ciency of the calculation.
MD.FCLast 〈MD.FCFirst〉 (integer) Two methods are currently implemented:
Index of last atom to displace for the computation of the force con- 1 Projectors are slightly-excited numerical atomic orbitals similar to
stant matrix for phonon calculations. those used as an automatic basis set by SIESTA. The radii of these
The force-constants matrix is written in file SystemLabel.FC. The format orbitals are controlled using the parameter LDAU.EnergyShift
is the following: for the displacement of each atom in each direction, the and/or the data included in the block LDAU.Proj (quite similar
forces on each of the other atoms is writen (divided by the value of the to the data block PAO.Basis used to specify the basis set, see
displacement), in units of eV/Å2 . Each line has the forces in the x, y and below).
z direction for one of the atoms. 2 Projectors are exact solutions of the pseudoatomic problem (and,
If constraints are used, the file SystemLabel.FCC is also written. in principle, are not strictly localized) which are cut using a Fermi
function 1/{1 + exp[(r − rc )ω]}. The values of rc and ω are con-
trolled using the parameter LDAU.CutoffNorm and/or the data
8 LDA+U included in the block LDAU.Proj.

LDAU.EnergyShift 0.05 Ry (energy)

Important note: Current implementation is based on the simplified rota-
Energy increase used to define the localization radius of the LDA+U
tionally invariant LDA+U formulation of Dudarev and collaborators [see,
projectors (similar to the parameter PAO.EnergyShift).
Dudarev et al., Phys. Rev. B 57, 1505 (1998)]. Although the input allows
to define independent values of the U and J parameters for each atomic NOTE: only used when LDAU.ProjectorGenerationMethod is
shell, in the actual calculation the two parameters are combined to pro- 1.
duce an effective Coulomb repulsion Ueff = U − J. Ueff is the parameter LDAU.CutoffNorm 0.9 (real)
actually used in the calculations for the time being.
Parameter used to define the value of rc used in the Fermi distribu-
For large or intermediate values of Ueff the convergence is sometimes diffi- tion to cut the LDA+U projectors generated according to generation
cult. A step-by-step increase of the value of Ueff can be advisable in such method 2 (see above). LDAU.CutoffNorm is the norm of the orig-
cases. inal pseudoatomic orbital contained inside a sphere of radius equal
Currently, the LDA+U implementation does not support non-colinear, to rc .
nor spin-orbit coupling. NOTE: only used when LDAU.ProjectorGenerationMethod is
2.

89
%block LDAU.Proj 〈None〉 (block) LDAU.ThresholdTol 0.01 (real)
Data block used to specify the LDA+U projectors. Local populations only calculated and/or updated if the change in
the density matrix elements (dDmax) is lower than
• If LDAU.ProjectorGenerationMethod is 1, the syntax is
LDAU.ThresholdTol.
as follows:
%block LDAU.Proj # Define LDA+U projectors LDAU.PopTol 0.001 (real)
Fe 2 # Label, l_shells Convergence criterium for the LDA+U local populations. In the
n=3 2 E 50.0 2.5 # n (opt if not using semicore levels),l,Softconf(opt)
current implementation the Hubbard-like term of the Hamiltonian is
5.00 0.35 # U(eV), J(eV) for this shell
2.30 # rc (Bohr)
only updated (except for the last iteration) if the variations of the
0.95 # scaleFactor (opt) local populations are larger than this value.
0 # l
1.00 0.05 # U(eV), J(eV) for this shell LDAU.PotentialShift false (logical)
0.00 # If set to true, the value given to the U parameter in the input file
rc(Bohr) (if 0, automatic r_c from LDAU.EnergyShift)
%endblock LDAU.Proj is interpreted as a local potential shift. Recording the change of the
• If LDAU.ProjectorGenerationMethod is 2, the syntax is local populations as a function of this potential shift, we can calculate
as follows: the appropriate value of U for the system under study following the
methology proposed by Cococcioni and Gironcoli in Phys. Rev. B
%block LDAU.Proj # Define LDAU projectors
Fe 2 # Label, l_shells 71, 035105 (2005).
n=3 2 E 50.0 2.5 # n (opt if not using semicore levels),l,Softconf(opt)
5.00 0.35 # U(eV), J(eV) for this shell
2.30 0.15 # 9 External
rc (Bohr), \omega(Bohr) (Fermi cutoff function) control of SIESTA
0.95 # scaleFactor (opt)
0 # l Since SIESTA 4.1 an additional method of controlling the convergence
1.00 0.05 # U(eV), J(eV) for this shell
and MD of SIESTA is enabled through external scripting capability. The
0.00 0.00 # rc(Bohr), \omega(Bohr) (if 0 r_c from LDAU.CutoffNorm
%endblock LDAU.Proj #
external control comes in two variants:
and \omega from default value)

Certain of the quantites have default values: • Implicit control of MD through updating/changing parameters and
U 0.0 eV optimizing forces. For instance one may use a Verlet MD method
J 0.0 eV but additionally update the forces through some external force-field
ω 0.05 Bohr to amend limitations by the Verlet method for your particular
Scale factor 1.0 case. In the implicit control the molecular dynamics is controlled
rc depends on LDAU.EnergyShift or LDAU.CutoffNorm de- by SIESTA.
pending on the generation method. • Explicit control of MD. In this mode the molecular dynamics must
LDAU.FirstIteration false (logical) be controlled in the external Lua script and the convergence of the
geometry should also be controlled via this script.
If true, local populations are calculated and Hubbard-like term is
switch on in the first iteration. Useful if restarting a calculation The implicit control is in use if MD.TypeOfRun is something other
reading a converged or an almost converged density matrix from file. than lua, while if the option is lua the explicit control is in use.

90
For examples on the usage of the Lua scripting engine and the power you
may find the library flos7 , see https://github.com/siesta-project/ end
flos. At the time of writing the flos library already implements new ge- Within this function there are certain states which defines different
ometry/cell relaxation schemes and new force-constants algorithms. You execution points in SIESTA:
are highly encouraged to use the new relaxation schemes as they may
provide faster convergence of the relaxation. Initialization This is right after SIESTA has read the options from
the FDF file. Here you may query some of the FDF options (and
Lua.Script 〈none〉 (file) even change them) for your particular problem.
Specify a Lua script file which may be used to control the internal NOTE: siesta.state == siesta.INITIALIZE.
variables in SIESTA. Such a script file must contain at least one
function named siesta_comm with no arguments. Initialize-MD Right before the SCF step starts. This point is some-
what superfluous, but is necessary to communicate the actual
An example file could be this (note this is Lua code):
meshcutoff used8 .
-- This function (siesta_comm) is REQUIRED NOTE: siesta.state == siesta.INIT_MD.
function siesta_comm()
SCF Right after SIESTA has calculated the output density matrix,
-- Define which variables we want to retrieve from SIESTA and just after SIESTA has performed mixing.
get_tbl = {"geom.xa", "E.total"} NOTE: siesta.state == siesta.SCF_LOOP.
-- Signal to SIESTA which variables we want to explore Forces This stage is right after SIESTA has calculated the forces.
siesta.receive(get_tbl) NOTE: siesta.state == siesta.FORCES.
-- Now we have the required variables, Move This state will only be reached if MD.TypeOfRun is lua.
-- convert to a simpler variable name (not nested tables) If one does not return updated atomic coordinates SIESTA will
-- (note the returned quantities are in SIESTA units (Bohr, Ry) reuse the same geometry as just analyzed.
xa = siesta.geom.xa
Etot = siesta.E.total NOTE: siesta.state == siesta.MOVE.
Analysis Just before SIESTA completes and exits.
-- If we know our energy is wrong by 0.001 Ry we may now
-- change the total energy NOTE: siesta.state == siesta.ANALYSIS.
Etot = Etot - 0.001 Beginning with implementations of Lua scripts may be cumbersome.
It is recommended to start by using flos, see https://github.com/
-- Return to SIESTA the total energy such that
siesta-project/flos which contains several examples on how to
-- it internally has the "correct" energy.
start implementing your own scripts. Currently flos implements a
siesta.E.total = Etot larger variety of relaxation schemes, for instance:
ret_tbl = {"E.total"} local flos = require "flos"
LBFGS = flos.LBFGS()
siesta.send(ret_tbl) function siesta_comm()
7
This library is implemented by Nick R. Papior to further enhance the inter- 8
Remember that the MeshCutoff defined is the minimum cutoff used.
operability with SIESTA and external contributions.

91
 LBFGS:SIESTA(siesta) /debug Turn on/off debugging information.
end
/show Show the currently collected lines of code.
which is the most minimal example of using the L-BFGS algo-
/clear Clears the currently collected lines of code.
rithm for geometry relaxation. Note that flos reads the parame-
ters MD.MaxCGDispl and MD.MaxForceTol through SIESTA ; Run the currently collected lines of code and continue collecting
automatically. lines.
NOTE: The number of available variables continues to grow and to /run Same as ;.
find which quantities are accessible in Lua you may add this small
code in your Lua script: /cont Run the currently collected lines of code and continue SIESTA.

siesta.print_allowed() /stop Run the currently collected lines of code and stop all future
interactive Lua sessions.
which prints out a list of all accessible variables (note they are not
sorted). Currently this only works if Lua.Script is having a valid Lua file
If there are any variables you require which are not in the list, please (note the file may be empty).
contact the developers.
Remark that since anything may be changed via Lua one may easily 9.1 Examples of Lua programs
make SIESTA crash due to inconsistencies in the internal logic. This
is because SIESTA does not check what has changed, it accepts Please look in the Tests/lua_* folders where examples of basic Lua
everything as is and continues. Hence, one should be careful what is scripts are found. Below is a description of the * examples.
changed.
h2o Changes the mixing weight continuously in the SCF loop. This will
Lua.Debug false (logical) effectively speed up convergence time if one can attain the best
Debug the Lua script mode by printing out (on stdout) information mixing weight per SCF-step.
everytime SIESTA communicates with Lua.
si111 Change the mixing method based on certain convergence criteria.
Lua.Debug.MPI false (logical) I.e. after a certain convergence one can switch to a more aggressive
Debug all nodes (if in a parallel run). mixing method.

Lua.Interactive false (logical)

A combination of the above two examples may greatly improve conver-
Start an interactive Lua session at all the states in the program and gence, however, creating a generic method to adaptively change the mixing
ask for user-input. This is primarily intended for debugging purposes. parameters may be very difficult to implement. If you do create such a
The interactive session is executed just before the siesta_comm func- Lua script, please share it on the mailing list.
tion call (if the script is used).
For serial runs siesta.send may be used. For parallel runs do not
use siesta.send as the code is only executed on the first MPI node. 9.2 External MD/relaxation methods
There are various commands that are caught if they are the only
Using the Lua interface allows a very easy interface for creating external
content on a line:
MD and/or relaxation methods.

92
A public library (flos, https://github.com/siesta-project/flos) al- semi-infinite metallic leads. A finite bias can be applied between both
ready implements a wider range of relaxation methods than intrinsically leads, to drive a finite current. The method is described in detail in
enabled in SIESTA. Secondly, by using external scripting mechanisms Brandbyge et al. [4] ; Papior et al. [10] . In practical terms, calculations us-
one can customize the routines to a much greater extend while simulta- ing TranSIESTA involve the solution of the electronic density from the
neously create custom constraints. DFT Hamiltonian using Greens functions techniques, instead of the usual
You are highly encouraged to try out the flos library (please note that diagonalization procedure. Therefore, TranSIESTA calculations involve
flook is required, see installation instructions above). a SIESTA run, in which a set of routines are invoked to solve the Greens
functions and the charge density for the open system. These routines are
packed in a set of modules, and we will refer to it as the ’TranSIESTA
10 TRANSIESTA module’ in what follows.
TranSIESTA was originally developed by Mads Brandbyge, José-Luis
SIESTA includes the possibility of performing calculations of electronic Mozos, Pablo Ordejón, Jeremy Taylor and Kurt Stokbro [4] . It con-
transport properties using the TranSIESTA method. This Section de- sisted, mainly, in setting up an interface between SIESTA and the (tight-
scribes how to use these capabilities, and a reference guide to the relevant binding) transport codes developed by M. Brandbyge and K. Stokbro.
fdf options. We describe here only the additional options available for Initially everything was written in Fortran-77. As SIESTA started to
TranSIESTA calculations, while the rest of the Siesta functionalities be translated to Fortran-90, so were the TranSIESTA parts of the code.
and variables are described in the previous sections of this User’s Guide. This was accomplished by José-Luis Mozos, who also worked on the paral-
An accompanying Python toolbox is available which will assist with lelization of TranSIESTA. Subsequently Frederico D. Novaes extended
TranSIESTA calculations. Please use (and cite) sisl [11] . TranSIESTA to allow k-point sampling for transverse directions. Addi-
tional extensions was added by Nick R. Papior during 2012.
The current TranSIESTA module has been completely rewritten by Nick
10.1 Source code structure
R. Papior and encompass highly advanced inversion algorithms as well as
In this implementation, the TranSIESTA routines have been grouped allowing N electrode setups among many new features. Furthermore, the
in a set of modules whose file names begin with m_ts or ts. utility TBtrans has also been fully re-coded (by Nick R. Papior) to be a
generic tight-binding code capable of analyzing physics from the Greens
function perspective in N ≥ 1 setups [10] .
10.2 Compilation
• Transport calculations involve electrode (EL) calculations, and
Prior to SIESTA 4.1 TranSIESTA was a separate executable. Now subsequently the Scattering Region (SR) calculation. The elec-
TranSIESTA is fully incorporated into SIESTA. Hence simply com- trode calculations are usual SIESTA calculations, but where a file
pile SIESTA and the full functionality is present. Sec. 2 for details on SystemLabel.TSHS is generated. These files contain the informa-
compiling SIESTA. tion necessary for calculation of the self-energies. If any electrodes
have identical structures (see below) the same SystemLabel.TSHS
10.3 Brief description file can be used to describe those. In general, however, electrodes
can be different and therefore two different SystemLabel.TSHS files
The TranSIESTA method is a procedure to solve the electronic struc- must be generated. The location of these electrode files must be
ture of an open system formed by a finite structure sandwiched between specified in the fdf input file of the SR calculation.

93
• For the SR, TranSIESTA starts with the usual SIESTA pro- may use so-called buffer atoms behind the electrodes to act as ad-
cedure, converging a Density Matrix (DM) with the usual Kohn- ditional screening regions when calculating the initial guess (us-
Sham scheme for periodic systems. It uses this solution as an ing SIESTA) for TranSIESTA. Essentially they may be used to
initial input for the Greens function self consistent cycle. As achieve a better “bulk-like” environment at the electrodes.
it is known, SIESTA stores the DM in a file with extension
SystemLabel.DM. In the case of TranSIESTA, this is done in a file • An important parameter is the lower bound of the energy contours.
named SystemLabel.TSDE. In a rerun of the same system (meaning It is a good practice, to start with a SIESTA calculation for the SR
the same SystemLabel), if the code finds a SystemLabel.TSDE and look at the eigenvalues of the system. The lower bound of the
file in the directory, it will take this DM as the initial input and contours must be well below the lowest eigenvalue.
this is then considered a continuation run. In this case it does not • TranSIESTA assumes periodic boundary conditions in directions
perform an initial SIESTA run. It must be clear that when start- orthogonal to the electrodes semi-infinite directions. If N > 2
ing a calculation from scratch, in the end one will find both files, TranSIESTA does not assume anything and one is required to
SystemLabel.DM and SystemLabel.TSDE. The first one stores the specify the periodicity (via k-points) separately.
SIESTA density matrix (periodic boundary conditions in all direc-
tions and no voltage), and the latter the TranSIESTA solution. • The default algorithm for matrix inversion is the BTD method, be-
fore starting a TranSIESTA calculation please run with the ana-
• When performing several bias calculations, it is heavily ad- lyzation step TS.Analyze.
vised to run different bias’ in different directories. To drasti-
cally improve convergence (and throughput) one should copy the • Importantly(!) the k-point sampling need typically be much higher
SystemLabel.TSDE from the closest, previously, calculated bias to in a TBtrans calculation to achieve a converged transmission func-
the current bias. tion.

• The SystemLabel.TSDE may be read equivalently as the

SystemLabel.DM. Thus, it may be used by fx. denchar to analyze 10.4 Electrodes
the non-equilibrium charge density.
To calculate the electronic structure of a system under external bias,
• As in the case of SIESTA calculations, what TranSIESTA does TranSIESTA attaches the system to semi-infinite electrodes which ex-
is to obtain a converged DM, but for open boundary conditions and tend to their respective semi-infinite directions. Examples of electrodes
possibly a finite bias applied between the electrodes. The corre- would include surfaces, nanowires, nanotubes or even atomic chains. The
sponding Hamiltonian matrix (once self consistency is achieved) of electrode must be large enough (in the semi-infinite direction) so that or-
the SR is also stored in a SystemLabel.TSHS file. Subsequently, bitals within the unit cell only interact with a single nearest neighbor cell
transport properties are obtained in a post-processing procedure in the semi-infinite direction (the size of the unit cell can thus be derived
using the TBtrans code (located in the Util/TS/TBtrans direc- from the range of support for the orbital basis functions). TranSIESTA
tory). It is to be noted that the SystemLabel.TSHS files contain will stop if this is not enforced. The electrodes are generated by a sepa-
all the needed structural information (atomic positions, matrix ele- rate TranSIESTA run on a bulk system. This implies that the proper
ments, . . . ), and so this kind of parameters will not be changed by bulk properties are obtained by a sufficiently high k-point sampling. If
input (fdf) flags once a SystemLabel.TSHS file is read. in doubt, use 100 k-points along the semi-infinite direction. The results
are saved in a file with extension SystemLabel.TSHS which contains a
• When the non-equilibrium calculation uses different electrodes one description of the electrode unit cell, the position of the atoms within the

94
unit cell, as well as the Hamiltonian and overlap matrices that describe When using the Bloch expansion (highly recommended if your system
the electronic structure of the lead. One can generate a variety of elec- allows it) it is advised to follow the tiling method. However both of the
trodes and the typical use of TranSIESTA would involve reusing the below sequences are allowed.
same electrode for several setups. At runtime, the TranSIESTA coor-
dinates are checked against the electrode coordinates and the program
Tile Here the atoms are copied and displaced by the full electrode. Gen-
stops if there is a mismatch to a certain precision (10−4 Bohr). Note that
erally this expansion should be preferred over the repeat expansion due
the atomic coordinates are compared relatively. Hence the input atomic
to faster execution.
coordinates of the electrode and the device need not be the same (see e.g.
the tests in the Tests directory.
iaD = 10 ! as per the above input option
To run an electrode calculation one should do: do iC = 0 , nC - 1
do iB = 0 , nB - 1
siesta --electrode RUN.fdf do iA = 0 , nA - 1
do iaE = 1 , na_u
or define these options in the electrode fdf files: TS.HS.Save and xyz_device(:, iaD) = xyz_elec(:, iaE) + &
cell_elec(:, 1) * iA + &
TS.DE.Save to true (the above –electrode is a shorthand for setting
cell_elec(:, 2) * iB + &
the two options). cell_elec(:, 3) * iC
iaD = iaD + 1
10.4.1 Matching coordinates end do
end do
end do
Here are some rules required to successfully construct the appropriate
end do
coordinates of the scattering region. Contrary to versions prior to 4.1,
the order of atoms is largely irrelevant. One may define all electrodes,
then subsequently the device, or vice versa. Similarly, buffer atoms are Repeat Here the atoms are copied individually. Generally this expan-
not restricted to be the first/last atoms. sion should not be used.
However, atoms in any given electrode must be consecutive in the device
iaD = 10 ! as per the above input option
file. I.e. if an electrode input option is given by: do iaE = 1 , na_u
do iC = 0 , nC - 1
%block TS.Elec.<> do iB = 0 , nB - 1
HS ../elec-<>/siesta.TSHS do iA = 0 , nA - 1
bloch 1 3 1 xyz_device(:, iaD) = xyz_elec(:, iaE) + &
used-atoms 4 cell_elec(:, 1) * iA + &
electrode-position 10 cell_elec(:, 2) * iB + &
... cell_elec(:, 3) * iC
%endblock iaD = iaD + 1
end do
then the atoms from 10 to 10 + 4 ∗ 3 − 1 must coincide with the atoms of end do
the calculation performed in the ../elec-<>/ subdirectory. The above end do
options will be discussed in the coming section. end do

95
As a help if the electrode coordinates does not coincide, TranSIESTA only the usual SIESTA options are relevant. Note that since TranSI-
prints out the expected coordinates as though the first device atom coin- ESTA is a generic N electrode NEGF code the input options are heavily
cides with the first electrode atom. Another means to create this is using changed compared to versions prior to 4.1.
the sisl [11] program and this command line:
sgeom -tx 1 -ty 3 -tz 1 ELEC.fdf DEVICE_ELEC.fdf # Tile 10.5.1 Quick and dirty
sgeom -rz 1 -ry 3 -rx 1 ELEC.fdf DEVICE_ELEC.fdf # Repeat
Since 4.1, TranSIESTA has been fully re-implemented. And so have
and then shift the coordinates according to the placement in the device every input fdf-flag. To accommodate an easy transition between previous
region. Note how repeating has different argument order of tiling. input files and the new version format a small utility called ts2ts. It may
be compiled in Util/TS/ts2ts. It is recommended that you use this tool
10.4.2 Principal layer interactions if you are familiar with previous TranSIESTA versions.
One may input options as in the old TranSIESTA version and then run
It is extremely important that the electrodes only interact with one neigh-
boring supercell due to the self-energy calculation [12] . TranSIESTA will ts2ts OLD.fdf > NEW.fdf
print out a block as this
which translates all keys to the new, equivalent, input format. If you
<> principal cell is perfect! are familiar with the old-style flags this is highly recommendable while
becoming comfortable with the new input format. Please note that some
if the electrode is correctly setup and it only interacts with its neighboring
defaults have changed to more conservative values in the newer release.
supercell. In case the electrode is erroneously setup, something similar to
the following will be shown in the output file. If one does not know the old flags and wish to get a basic example of an
input file, a script Util/TS/tselecs.sh exists that can create the basic
<> principal cell is extending out with 96 elements: input for N electrodes. One may call it like:
Atom 1 connects with atom 3
Orbital 8 connects with orbital 26 tselecs.sh -2 > TWO_ELECTRODE.fdf
Hamiltonian value: |H(8,6587)|@R=-2 = 0.651E-13 eV tselecs.sh -3 > THREE_ELECTRODE.fdf
Overlap : S(8,6587)|@R=-2 = 0.00 tselecs.sh -4 > FOUR_ELECTRODE.fdf
...
It is imperative that you have a perfect electrode as otherwise nonphysical
results will occur. where the first call creates an input fdf for 2 electrode setups, the second
for a 3 electrode setup, and so on. See the help (-h) for the program for
By default TranSIESTA will die if there are connections beyond the additional options.
principal cell. One may control whether this is allowed or not by using
TS.Elecs.Neglect.Principal. Before endeavoring on large scale calculations you are advised to run an
analyzation of the system at hand, you may run your system as

10.5 TranSIESTA Options siesta -fdf TS.Analyze RUN.fdf > analyze.out

The fdf options shown here are only to be used at the input file for the which will analyze the sparsity pattern and print out several different
scattering region. When using TranSIESTA for electrode calculations, pivoting schemes. Please see TS.Analyze for additional information.

96
10.5.2 General options will remove atoms [1–5] from the calculation.

One have to set SolutionMethod to transiesta to enable TranSI- TS.ElectronicTemperature 〈ElectronicTemperature〉 (energy)
ESTA. Define the temperature used for the Fermi distributions for the chem-
ical potentials. See TS.ChemPot.<>.ElectronicTemperature.
TS.SolutionMethod btd|mumps|full (string)
Control the algorithm used for calculating the Green function. Gen- TS.SCF.Initialize diagon|transiesta (string)
erally the BTD method is the fastest and this option need not be Control which initial guess should be used for TranSIESTA. The
changed. general way is the diagon solution method (which is preferred),
however, one can start a TranSIESTA run immediately. If
BTD Use the block-tri-diagonal algorithm for matrix inversion.
you start directly with TranSIESTA please refer to these flags:
This is generally the recommended method. TS.Elecs.DM.Init, DM.Init.Bulk and TS.Fermi.Initial.
MUMPS Use sparse matrix inversion algorithm (MUMPS). This re- NOTE: Setting this to transiesta is highly experimental and con-
quires TranSIESTA to be compiled with MUMPS. vergence may be extremely poor.
full Use full matrix inversion algorithm (LAPACK). Generally only PNE i
TS.Fermi.Initial i EF /NE (energy)
usable for debugging purposes. Manually set the initial Fermi level to a predefined value.
TS.Voltage 0 eV (energy) NOTE: this may also be used to change the Fermi level for calcu-
Define the reference applied bias. For N = 2 electrode calculations lations where you restart calculations. Using this feature is highly
this refers to the actual potential drop between the electrodes, while experimental.
for N 6= 2 this is a reference bias. In the latter case it must be TS.Weight.Method
equivalent to the maximum difference between the chemical potential orb-orb|[[un]correlated+][sum|tr]-atom-[atom|orb]|mean
of any two electrodes. (string)
TS.Atoms.Buffer 〈None〉 (block/list) Control how the NEGF weighting scheme is conducted. Generally
Specify atoms that will be removed in the TranSIESTA SCF. They one should only use the orb-orb while the others are present for
are not considered in the calculation and may be used to improve more advanced usage. They refer to how the weighting coefficients of
the initial guess for the Hamiltonian. Their main usage is to extend the different non-equilibrium contours are performed. In the follow-
electrodes in their semi-infinite directions. ing the weight are denoted in a two-electrode setup while they are
generalized for multiple electrodes.
NOTE: all lines are additive for the buffer atoms and the input
method is similar to that of Geometry.Constraints for the atom Define the normalised geometric mean as ∝|| via
line(s).
|| h·L i
w ∝ h·L i ≡ . (19)
%block TS.Atoms.Buffer h·L i + h·R i
atom [ 1 -- 5 ]
%endblock orb-orb Weight each orbital-density matrix element individually.
# Or equivalently as a list
TS.Atoms.Buffer [1 -- 5] tr-atom-atom Weight according to the trace of the atomic density

97
 matrix sub-blocks none No charge corrections are introduced.
||
sX
Tr
wij ∝ (∆ρL 2
X
(∆ρL 2 buffer Excess/missing electrons are placed in the buffer regions
µµ ) µµ ) (20)
∈{i} ∈{j} (buffer atoms are required to exist)
fermi Correct the filling by calculating a new Fermi-level (reference
tr-atom-orb Weight according to the trace of the atomic density energy).
matrix sub-block times the weight of the orbital weight We approximate the contribution to be constant around the Fermi
Tr ||
q
Tr w
level and find
wij,µν ∝ wij ij,µν (21) Q0 − Q
dEF = , (24)
Q|EF
sum-atom-atom Weight according to the total sum of the atomic
density matrix sub-blocks where Q0 is the charge from a converged TranSIESTA calculation
and Q|EF is the equilibrium charge at the current Fermi level, Q is
||
sX
the supposed charge to reside in the calculation. Fermi correction
X
Σ
wij,µν ∝ (∆ρL
µν )
2 (∆ρL
µν )
2 (22)
∈{i} ∈{j} utilizes Eq. (24) for the first correction and all subsequent cor-
rections are based on a cubic spline interpolation to much faster
sum-atom-orb Weight according to the total sum of the atomic den- converge to the “correct” Fermi level.
sity matrix sub-block times the weight of the orbital weight This method will create a file called TS_FERMI.
||
q
Σ Σw TS.ChargeCorrection.Factor 0.75 (real)
wij,µν ∝ wij ij,µν (23)
Should be between 0 and 1 to lower the charge adjustment. 0 means
mean A standard average. no charge correction. 1 means total charge correction. This will
Each of the methods (except mean) comes in a correlated and un- reduce the fluctuations in the SCF and setting this to 1 may result
correlated variant where
P
is either outside or inside the square, in difficulties in converging.
respectively. TS.ChargeCorrection.Fermi.Tolerance 0.01 (real)
TS.Weight.k.Method correlated|uncorrelated (string) The tolerance at which the charge correction will converge. Any
Control weighting per k-point or the full sum. I.e. if uncorrelated excess/missing charge (|Q0 − Q| > Tol) will result in a correction for
is used it will weight nk times if there are nk k-points in the Brillouin the Fermi level.
zone. TS.ChargeCorrection.Fermi.Max 1.5 eV (energy)
TS.Forces true (logical) The maximally allowed value that the Fermi level will change from
Control whether the forces are calculated. If not TranSIESTA will a charge correction using the Fermi correction method. In case the
use slightly less memory and the performance slightly increased, how- Fermi level lies in between two bands a DOS of 0 at the Fermi level
ever the final forces shown are incorrect. will make the Fermi change equal to ∞. This is not physical and the
user can thus truncate the correction.
TS.ChargeCorrection none|buffer|fermi (string) If you know the band-gab, setting this to 1/4 (or smaller) of the band
Any excess/deficiency of charge can be re-adjusted after each Tran- gab seems like a better value than the rather arbitrarily default one.
SIESTA cycle to reduce charge fluctuations in the cell.

98
TS.HS.Save true (logical) siesta -fdf TS.Analyze RUN.fdf > analyze.out
Must be true for saving the Hamiltonian (SystemLabel.TSHS). Can note that there is little gain on using MPI and it should complete
only be set if SolutionMethod is not transiesta. within a few minutes, no matter the number of orbitals.
The default is false for SolutionMethod different from transiesta Choosing the best one may be difficult. Generally one should choose
and if –electrode has not been passed as a command line argument. the pivoting scheme that uses the least amount of memory. However,
TS.DE.Save true (logical) one should also choose the method with the largest block-size being
as small as possible. As an example:
Must be true for saving the density and energy density matrix for
continuation runs (SystemLabel.TSDE). Can only be set if Solution- TS.BTD.Pivot atom+GPS
Method is not transiesta. ...
BTD partitions (7):
The default is false for SolutionMethod different from transiesta [ 2984, 2776, 192, 192, 1639, 4050, 105 ]
and if –electrode has not been passed as a command line argument. BTD matrix block size [max] / [average]: 4050 / 1705.429
BTD matrix elements in % of full matrix: 47.88707 %
TS.S.Save false (logical)
This is a flag mainly used for the Inelastica code to produce overlap TS.BTD.Pivot atom+GGPS
matrices for Pulay corrections. This should only be used by advanced ...
users. BTD partitions (6):
[ 2880, 2916, 174, 174, 2884, 2910 ]
TS.SIESTA.Only false (logical) BTD matrix block size [max] / [average]: 2916 / 1989.667
Stop TranSIESTA right after the initial diagonalization run in BTD matrix elements in % of full matrix: 48.62867 %
SIESTA. Upon exit it will also create the SystemLabel.TSDE file
which may be used for initialization runs later. Although the GPS method uses the least amount of memory, the
This may be used to start several calculations from the same initial GGPS will likely perform better as the largest block in GPS is 4050
density matrix, and it may also be used to rescale the Fermi level of vs. 2916 for the GGPS method.
electrodes. The rescaling is primarily used for semi-conductors where
TS.Analyze.Graphviz false (logical)
the Fermi levels of the device and electrodes may be misaligned.
depends on: TS.Analyze
TS.Analyze false (logical) If performing the analysis, also create the connectivity graph and
When using the BTD solution method (TS.SolutionMethod) this store it as GRAPHVIZ_atom.gv or GRAPHVIZ_orbital.gv to be post-
will analyze the Hamiltonian and printout an analysis of the sparsity processed in Graphviz9 .
pattern for optimal choice of the BTD partitioning algorithm.
This yields information regarding the TS.BTD.Pivot flag. 10.5.3 Algorithm specific options
NOTE: we advice users to always run an analyzation step prior to
actual calculation and select the best BTD format. This analyzing These options adhere to the specific solution methods available for Tran-
step is very fast and may be performed on small work-station com- SIESTA. For instance the TS.BTD.* options adhere only when using
puters, even on systems of  10, 000 orbitals. TS.SolutionMethod BTD, similarly for options with MUMPS.
To run the analyzing step you may do: 9
www.graphviz.org

99
TS.BTD.Pivot 〈first electrode〉 (string) TS.BTD.Optimize speed|memory (string)
Decide on the partitioning for the BTD matrix. One may denote When selecting the smallest blocks for the BTD matrix there are
either atom+ or orb+ as a prefix which does the analysis on the certain criteria that may change the size of each block. For very
atomic sparsity pattern or the full orbital sparsity pattern, respec- memory consuming jobs one may choose the memory.
tively. If neither are used it will default to atom+. NOTE: often both methods provide exactly the same BTD matrix
Please see TS.Analyze. due to constraints on the matrix.
<elec-name>|CG-<elec-name> The partitioning will be a con- TS.BTD.Guess1.Min 〈empirically determined〉 (int)
nectivity graph starting from the electrode denoted by the name. depends on: TS.BTD.Guess1.Max
This name must be found in the TS.Elecs block. One can append Constructing the blocks for the BTD starts by guessing the first
more than one electrode to simultaneously start from more than 1 block size. One could guess on all different block sizes, but to speed
electrode. This may be necessary for multi-terminal calculations. up the process one can define a smaller range of guesses by defining
rev-CM Use the reverse Cuthill-McKee for pivoting the matrix ele- TS.BTD.Guess1.Min and TS.BTD.Guess1.Max.
ments to reduce bandwidth. One may omit rev- to use the stan- The initial guessed block size will be between the two values.
dard Cuthill-McKee algorithm (not recommended). By default this is 1/4 of the minimum bandwidth for a selected first
This pivoting scheme depends on the initial starting electrodes, ap- set of orbitals.
pend +<elec-name> to start the Cuthill-McKee algorithm from NOTE: setting this to 1 may sometimes improve the final BTD
the specified electrode. matrix blocks.
GPS Use the Gibbs-Poole-Stockmeyer algorithm for reducing the TS.BTD.Guess1.Max 〈empirically determined〉 (int)
bandwidth. depends on: TS.BTD.Guess1.Min
GGPS Use the generalized Gibbs-Poole-Stockmeyer algorithm for re- See TS.BTD.Guess1.Min.
ducing the bandwidth. NOTE: for improved initialization performance setting Min/Max
NOTE: this algorithm does not work on dis-connected graphs. flags to the first block size for a given pivoting scheme will drastically
reduce the search space and make initialization much faster.
PCG Use the perphiral connectivity graph algorithm for reducing the
bandwidth. TS.BTD.Spectral propagation|column (string)
This pivoting scheme may depend on the initial starting elec- How to compute the spectral function (GΓG† ).
trode(s), append +<elec-name> to initialize the PCG algorithm
For N < 4 this defaults to propagation which should be the fastest.
from the specified electrode.
For N ≥ 4 this defaults to column.
Examples are Check which has the best performance for your system if you endeavor
TS.BTD.Pivot atom+GGPS on huge amounts of calculations for the same system.
TS.BTD.Pivot GGPS
TS.BTD.Pivot orb+GGPS TS.MUMPS.Ordering 〈read MUMPS manual〉 (string)
TS.BTD.Pivot orb+PCG+Left One may select from a number of different matrix orderings which
where the first two are equivalent. The 3rd and 4th are more heavy are all described in the MUMPS manual.
on analysis and will typically not improve the bandwidth reduction. The following list of orderings are available (without detailing their

100
 differences): auto, AMD, AMF, SCOTCH, PORD, METIS, calculations but may also be used when an a priori potential profile
QAMD. is know.
The file should contain something similar to this output (ncdump
TS.MUMPS.Memory 20 (integer)
-h):
Specify a factor for the memory consumption in MUMPS. See the
netcdf <file> {
INFOG(9) entry in the MUMPS manual. Generally if TranSI- dimensions:
ESTA dies and INFOG(9)=-9 one should increase this number. one = 1 ;
a = 43 ;
TS.MUMPS.BlockingFactor 112 (integer) b = 451 ;
Specify the number of internal block sizes. Larger numbers increases c = 350 ;
performance at the cost of memory. variables:
NOTE: this option may heavily influence performance. double Vmin(one) ;
Vmin:unit = "Ry" ;
double Vmax(one) ;
10.5.4 Poisson solution for fixed boundary conditions Vmax:unit = "Ry" ;
double V(c, b, a) ;
TranSIESTA requires fixed boundary conditions and forcing this is an V:unit = "Ry" ;
intricate and important detail. }
Note that the units should be in Ry. Vmax/Vmin should contain
TS.Poisson ramp-central|elec-box|〈file〉|ramp-cell (string) the maximum/minimum fixed boundary conditions in the Poisson
Define how the correction of the Poisson equation is superimposed. solution. This is used internally by TranSIESTA to scale the
The default is to apply the linear correction across the central region potential to arbitrary V . This enables the Poisson solution to only
(if there are two semi-infinite aligned electrodes). Otherwise this be solved once independent on subsequent calculations For some
defaults to the box solution which will introduce spurious effects at chemical potential configurations the Poisson solution cannot be
the electrode boundaries. In this case you are encouraged to supply linearly extrapolated, in which case a separate file is required for
a file. each applied bias.
If the input is a file, it should be a NetCDF file containing the grid
elec-box The default potential profile for N > 2, or when the elec-
information which acts as the boundary conditions for the SCF cycle.
trodes does are not aligned (in terms of their transport direction).
The grid information should conform to the grid size of the unit-cell in
NOTE: usage of this Poisson solution is highly discouraged. Please
the simulation. NOTE: the file option is only applicable if compiled
see TS.Poisson <file>.
with CDF4 compliance.
ramp-cell Apply the ramp for the full cell. This option should only
ramp-central Apply the bias-ramp between the leads. For a bulk
be used for testing against older versions of TranSIESTA.
electrode (see TS.Elec.<>.Bulk) the ramp will start at the
electrode-device interface, otherwise it will start at the beginning TS.Hartree.Fix plane|elec-plane|elec-box (string)
of the electrode. As the fixed boundary conditions requires a fixed reference potential.
<file> Specify an external file used as the boundary conditions for For two electrode calculations this defaults to taking the plane at one
the applied bias. This is encouraged to use for N > 2 electrode of the electrodes basal-planes (plane).

101
 For anything but two electrodes this defaults to elec-plane because It may help convergence but should not be so large it extends into
the plane should be at a fixed position in the cell. the scattering region.
NOTE: generally this need not be changed. NOTE: This only affects 2 electrode calculations when TS.Poisson
ramp-central or TS.Poisson ramp-cell.
TS.Hartree.Fix.Elec electrode name (string)
depends on: TS.Hartree.Fix
Specifically select an electrode’s boundary plane to be used as the 10.5.5 Electrode description options
constant potential boundary. The electrode unit-cell plane is inte-
grated and subtracted from all potential grid-points to ensure a con- As TranSIESTA supports N electrodes one needs to specify all elec-
stant potential at the interface between the electrode in the pristine trodes in a generic input format.
calculation and in the device calculation. %block TS.Elecs 〈None〉 (block)
TranSIESTA defaults to select the electrode plane which has the Each line denote an electrode which is queried in TS.Elec.<> for
largest area. its setup.
NOTE: this may be important in N > 2 electrode calculations where
some electrodes may have a huge semi-infinite surface plane but a %block TS.Elec.<> 〈None〉 (block)
limited amount of atoms. It is heavily advised to select the electrode Each line represents a setting for electrode <>. There are a few lines
with the largest number of atoms in a plane-cut perpendicular to the that must be present, HS, semi-inf-dir, electrode-pos, chem-pot.
semi-infinite direction. The remaining options are optional.
NOTE: Options prefixed with tbt are neglected in TranSIESTA
TS.Hartree.Fix.Frac 1. (real)
calculations. In TBtrans calculations these flags has precedence
Fraction of the correction that is applied. over the other options.
NOTE: this is an experimental feature!
HS The Hamiltonian information from the initial electrode calcula-
TS.Hartree.Offset 0 eV (energy) tion. This file retains the geometrical information as well as the
An offset in the Hartree potential to match the electrode potential. Hamiltonian, overlap matrix and the Fermi-level of the electrode.
This value may be useful in certain cases where the Hartree poten- This is a file-path and the electrode SystemLabel.TSHS need not
tials are very different between the electrode and device region cal- be located in the simulation folder.
culations. semi-inf-direction|semi-inf-dir|semi-inf The semi-infinite direc-
tion of the electrode with respect to the electrode unit-cell.
TS.Elec.<>.Hartree.Extend 0. Ang (length)
depends on: TS.Poisson ramp-central, TS.Poisson ramp-cell
NOTE: this direction is not with respect to the scattering region
unit cell. It is with respect to the electrode unit cell. TranSI-
The potential profile will by default be terminated at the interface
ESTA will figure out the alignment of the electrode unit cell and
between the electrode and the device. However, as one requires a
the scattering region unit-cell.
screening region between the electrode and the actual scattering re-
gion one may argue that the electrode potential will extend further chemical-potential|chem-pot|mu The chemical potential that is
into the device. This flag increases the electrode potentials extend associated with this electrode. This is a string that should be
into the device region. present in the TS.ChemPots block.

102
electrode-position|elec-pos The index of the electrode in the scat- Accuracy depends on: TS.Elecs.Accuracy
tering region. This may be given by either elec-pos <idx>, which Control the convergence accuracy required for the self-energy cal-
refers to the first atomic index of the electrode residing at index culation when using the Lopez-Sanchez, Lopez-Sanchez iterative
<idx>. Else the electrode position may be given via elec-pos scheme.
end <idx> where the last index of the electrode will be located NOTE: advanced use only.
at <idx>.
DE Density and energy density matrix file for the electrode. This may
used-atoms Number of atoms from the electrode calculation that is be used to initialize the density matrix elements in the electrode
used in the scattering region as electrode. This may be useful when region by the bulk values. This may be used to increase the bulk-
the periodicity of the electrodes forces extensive electrodes in the like behavior of the electrodes.
semi-infinite direction.
NOTE: this should only be performed on one TranSIESTA cal-
NOTE: do not set this if you use all atoms in the electrode. culation as then the scattering region SystemLabel.TSDE contains
Bulk Logical controlling whether the Hamiltonian of the electrode re- the electrode density matrix.
gion in the scattering region is enforced bulk or whether the Hamil- Bloch 3 integers should be present on this line which each denote
tonian is taken from the scattering region elements. If the number of times bigger the scattering region electrode is com-
DM-update depends on: TS.Elec.<>.Bulk pared to the electrode, in each lattice direction. Remark that these
String of values none, cross-terms or all which controls which expansion coefficients are with regard to the electrode unit-cell.
part of the electrode density matrix elements that are updated. This is denoted “Bloch” because it is an expansion based on Bloch
If all, both the density matrix elements in the electrode and the waves.
coupling elements between the electrode and scattering region are Bloch-A/a1|B/a2|C/a3 Specific Bloch expansions in each of the
updated. If cross-terms (default) only the coupling elements be- electrode unit-cell direction. See Bloch for details.
tween the electrode and the scattering region are updated.
pre-expand String denoting how the expansion of the surface Green
If TS.Elec.<>.Bulk false this is forced to all.
function file will be performed. This only affects the Green function
Gf String with filename of the surface Green function data. This file if Bloch is larger than 1. By default the Green function file
may be used to place a common surface Green function file in a will contain the fully expanded surface Green function, but not
top directory which may then be used in all calculations using Hamiltonian and overlap matrices (Green). One may reduce the
the same electrode and the same contour. If many calculations file size by setting this to Green which only expands the surface
are performed this will heavily increase performance at the cost of Green function. Finally none may be passed to reduce the file size
disk-space. to the bare minimum. For performance reasons all is preferred.
Gf-Reuse Logical deciding whether the surface Green function file out-of-core If true (default) the GF files are created which contain
should be re-used or deleted. If this is false the surface Green the surface Green function. If false the surface Green function
function file is deleted and re-created upon start. will be calculated when needed. Setting this to false will heavily
Eta depends on: TS.Elecs.Eta
degrade performance and it is highly discouraged!
Control the imaginary part of the surface Green function for this check-kgrid For N electrode calculations the k mesh will sometimes
electrode. not be equivalent for the electrodes and the device region calcula-

103
 tions. However, TranSIESTA requires that the device and elec- TS.Elecs.DM.Init diagon|bulk (string)
trode k samplings are commensurate. This flag controls whether The density matrix elements in the electrodes may be forcefully set to
this check is enforced. the bulk values by reading in the DM of the corresponding electrode.
NOTE: only use if fully aware of the implications! This may be set to bulk to forcefully set the bulk values.
NOTE: this will automatically be set to diagon for non-equilibrium
There are several flags which are globally controlling the variables for the
calculations. If bulk density matrix elements are wanted in the elec-
electrodes (with TS.Elec.<> taking precedence).
trodes it is vital to have this option set to bulk when performing the
TS.Elecs.Bulk true (logical) equilibrium calculation.
This globally controls how the Hamiltonian is treated in all elec- TS.Elecs.Coord.EPS 0.001 Ang (length)
trodes. See TS.Elec.<>.Bulk.
When using Bloch expansion of the self-energies one may experience
TS.Elecs.Eta 10−4 eV (energy) difficulties in obtaining perfectly aligned electrode coordinates.
Globally control the imaginary part used for the surface Green func- This parameter controls how strict the criteria for equivalent atomic
tion calculation. See TS.Elec.<>.Eta. coordinates is. If TranSIESTA crashes due to mismatch between
the electrode atomic coordinates and the scattering region calcula-
TS.Elecs.Accuracy 10−13 eV (energy) tion, one may increase this criteria. This should only be done if one
Globally control the accuracy required for convergence of the self- is sure that the atomic coordinates are almost similar and that the
energy. See TS.Elec.<>.Accuracy. difference in electronic structures of the two may be negligible.

TS.Elecs.Neglect.Principal false (logical)

If this is false TranSIESTA dies if there are connections beyond 10.5.6 Chemical potentials
the principal cell.
For N electrodes there will also be Nµ chemical potentials. They are
NOTE: set this to true with care, non-physical results may arise.
defined via blocks similar to TS.Elecs.
Use at your own risk!
%block TS.ChemPots 〈None〉 (block)
TS.Elecs.Gf.Reuse true (logical)
Each line denotes a new chemical potential which is defined in the
Globally control whether the surface Green function files should be
TS.ChemPot.<> block.
re-used (true) or re-created (false). See TS.Elec.<>.Gf-Reuse.
%block TS.ChemPot.<> 〈None〉 (block)
TS.Elecs.Out-of-core true (logical)
Each line defines a setting for the chemical potential named <>.
Whether the electrodes will calculate the self energy at each SCF
step. Using this will not require the surface Green function files but chemical-shift|mu Define the chemical shift (an energy) for this
at the cost of heavily degraded performance. You are not encouraged chemical potential. One may specify the shift in terms of the ap-
to set this to false. See TS.Elec.<>.Out-of-core. plied bias using V/<integer> instead of explicitly typing the
energy.
TS.Elecs.DM.Update cross-terms|all|none (string)
contour.eq A subblock which defines the integration curves for the
This globally controls which parts of the electrode density matrix
equilibrium contour for this equilibrium chemical potential. One
gets updated. See TS.Elec.<>.DM-Update.

104
 may supply as many different contours to create whatever shape %block TS.ChemPots
of the contour Left
Right
Its format is
%endblock
contour.eq %block TS.ChemPot.Left
begin mu V/2
<contour-name-1> contour.eq
<contour-name-2> begin
... C-Left
end T-Left
NOTE: If you do not specify contour.eq in the block one will end
automatically use the continued fraction method and you are en- %endblock
%block TS.ChemPot.Right
couraged to use 50 or more poles [8] .
mu -V/2
ElectronicTemperature|Temp|kT Specify the electronic tem- contour.eq
perature (as an energy or in Kelvin). This defaults to begin
TS.ElectronicTemperature. C-Right
T-Right
One may specify this in units of TS.ElectronicTemperature by end
using the unit kT. %endblock
contour.eq.pole Define the number of poles used via an energy spec-
ification. TranSIESTA will automatically convert the energy to Note that the default is a 2 electrode setup with chemical potentials asso-
the closest number of poles (rounding up). ciated directly with the electrode names “Left”/“Right”. Each chemical
potential has two parts of the equilibrium contour named according to
NOTE: this has precedence
their name.
over TS.ChemPot.<>.contour.eq.pole.N if it is specified and
a positive energy. Set this to a negative energy to directly control
the number of poles. 10.5.7 Complex contour integration options
contour.eq.pole.N Define the number of poles via an integer.
Specifying the contour for N electrode systems is a bit extensive due
NOTE: this will only to the possibility of more than 2 chemical potentials. Please use the
take effect if TS.ChemPot.<>.contour.eq.pole is a negative Util/TS/tselecs.sh as a means to create default input blocks.
energy.
The contours are split in two segments. One, being the equilibrium con-
It is important to realize that the parameterization of the voltage into tour of each of the different chemical potentials. The second for the non-
the chemical potentials enables one to have a single input file which equilibrium contour. The equilibrium contours are shifted according to
is never required to be changed, even when changing the applied bias. their chemical potentials with respect to a reference energy. Note that
These options complicate the input sequence for regular 2 electrode which for TranSIESTA the reference energy is named the Fermi-level, which
is unfortunate. is rather unfortunate (for non-equilibrium but not equilibrium). Fortu-
nately the non-equilibrium contours are defined from different chemical
Using tselecs.sh -only-mu yields this output: potentials Fermi functions, and as such this contour is defined in the

105
window of the minimum and maximum chemical potentials. Because the The parameters may also be given values prev/next which is the
reference energy is the periodic Fermi level it is advised to retain the aver- equivalent of specifying the same energy as the previous contour it
age chemical potentials equal to 0. Otherwise applying different bias will is connected to.
shift transmission curves calculated via TBtrans relative to the average NOTE: that b may be supplied as inf for tail parts.
chemical potential.
points/delta Define the number of integration points/energy sepa-
In this section the equilibrium contours are defined, and in the next section ration. If specifying the number of points an integer should be
the non-equilibrium contours are defined. supplied.
TS.Contours.Eq.Pole 2.5 eV (energy) If specifying the separation between consecutive points an energy
should be supplied.
The imaginary part of the line integral crossing the chemical po-
tential. Note that the actual number of poles may differ between method Specify the numerical method used to conduct the integra-
different calculations where the electronic temperatures are different. tion. Here a number of different numerical integration schemes are
NOTE: if the energy specified is negative, accessible
TS.Contours.Eq.Pole.N takes effect. mid|mid-rule Use the mid-rule for integration.
TS.Contours.Eq.Pole.N 8 (integer) simpson|simpson-mix Use the composite Simpson 3/8 rule (three
Manually select the number poles for the equilibrium contour. point Newton-Cotes).
NOTE: this flag will only take effect if TS.Contours.Eq.Pole is a boole|boole-mix Use the composite Booles rule (five point
negative energy. Newton-Cotes).
%block TS.Contour.<> 〈None〉 (block) G-legendre Gauss-Legendre quadrature.
Specify a contour named <> with options within the block. NOTE: has opt left
The names <> are taken from the TS.ChemPot.<>.contour.eq NOTE: has opt right
block in the chemical potentials. tanh-sinh Tanh-Sinh quadrature.
The format of this block is made up of at least 4 lines, in the following NOTE: has opt precision <>
order of appearance.
NOTE: has opt left
part Specify which part of the equilibrium contour this is: NOTE: has opt right
circle The initial circular part of the contour G-Fermi Gauss-Fermi quadrature (only on tails).
square The initial square part of the contour opt Specify additional options for the method. Only a selected sub-
line The straight line of the contour set of the methods have additional options.
tail The final part of the contour must be a tail which denotes the These options complicate the input sequence for regular 2 electrode which
Fermi function tail. is unfortunate. However, it allows highly customizable contours.
from a to b Define the integration range on the energy axis. Thus Using tselecs.sh -only-c yields this output:
a and b are energies.
TS.Contours.Eq.Pole 2.5 eV

106
 %block TS.Contour.C-Left The bias contour is limited by the Fermi function tails. Numerically
part circle it does not make sense to integrate to infinity. This energy defines
from -40. eV + V/2 to -10 kT + V/2 where the bias integration window is turned into zero. Thus above
points 25 −|V |/2 − E or below |V |/2 + E the DOS is defined as exactly zero.
method g-legendre
%endblock %block TS.Contours.nEq 〈None〉 (block)
%block TS.Contour.T-Left
part tail Each line defines a new contour on the non-equilibrium bias window.
from prev to inf The contours defined must be defined in TS.Contour.nEq.<>.
points 10 These contours must all be part line or part tail.
method g-fermi
%endblock %block TS.Contour.nEq.<> 〈None〉 (block)
%block TS.Contour.C-Right This block is exactly equivalently defined as the TS.Contour.<>.
part circle See page 106.
from -40. eV -V/2 to -10 kT -V/2
points 25 The default options related to the non-equilibrium bias contour are defined
method g-legendre as this:
%endblock
%block TS.Contour.T-Right
%block TS.Contours.nEq
part tail
neq-1
from prev to inf
%endblock TS.Contours.nEq
points 10
%block TS.Contour.nEq.neq-1
method g-fermi
part line
%endblock
from -|V|/2 - 5 kT to |V|/2 + 5 kT
delta 0.01 eV
These contour options refer to input options for the chemical potentials as
method mid-rule
shown in Sec. 10.5.6 (p. 104). Importantly one should note the shift of the %endblock TS.Contour.nEq.neq-1
contours corresponding to the chemical potential (the shift corresponds
to difference from the reference energy used in TranSIESTA). If one chooses a different reference energy than 0, then the lim-
its should change accordingly. Note that here kT refers to
10.5.8 Bias contour integration options TS.ElectronicTemperature.

The bias contour is similarly defined as the equilibrium contours. Please

use the Util/TS/tselecs.sh as a means to create default input blocks.
10.6 Output

TS.Contours.nEq.Eta 0 eV (energy) TranSIESTA generates several output files.

The imaginary part (η) of the device states. Generally this is not
necessary to define as the imaginary part naturally arises from the SystemLabel.DM : The SIESTA density matrix. SIESTA initially per-
self-energies (where η > 0). forms a calculation at zero bias assuming periodic boundary condi-
tions in all directions, and no voltage, which is used as a starting
TS.Contours.nEq.Fermi.Cutoff 5 kB T (energy) point for the TranSIESTA calculation.

107
SystemLabel.TSDE : The TranSIESTA density matrix and energy den- In addition to the shipped utilities SIESTA is also officially supported
sity matrix. During a TranSIESTA run, the SystemLabel.DM by sisl [11] which is a Python library enabling many of most commonly
values are used for the density matrix in the buffer (if used) and encountered things.
electrode regions. The coupling terms may or may not be updated
in a TranSIESTA run, see TS.Elec.<>.DM-Update.
12 SCRIPTING
SystemLabel.TSHS : The Hamiltonian corre-
sponding to SystemLabel.TSDE. This file also contains geometry In the Util/Scripting directory we provide an experimental python
information etc. needed by TranSIESTA and TBtrans. scripting framework built on top of the “Atomic Simulation Environment”
(see https://wiki.fysik.dtu.dk/ase2) by the Campos group at DTU,
SystemLabel.TS.KP : The k-points used in the TranSIESTA calcula- Denmark.
tion. See SIESTA SystemLabel.KP file for formatting information. (NOTE: “ASE version 2”, not the new version 3, is needed)

SystemLabel.TSCCEQ* : The equilibrium complex contour integration There are objects implementing the “Siesta as server/subroutine” feature,
paths. and also hooks for file-oriented-communication usage. This interface is
different from the SIESTA-specific functionality already contained in the
ASE framework.
SystemLabel.TSCCNEQ* : The non-equilibrium complex contour integra-
tion paths. Users can create their own scripts to customize the “outer geometry loop”
in SIESTA, or to perform various repetitive calculations in compact form.
SystemLabel.TSGF* : Self-energy files containing the used self-energies Note that the interfaces in this framework are still evolving and are subject
from the leads. These are very large files used in the SCF loop. Once to change.
completed one can safely delete these files. For heavily increased
Suggestions for improvements can be sent to Alberto Garcia (alber-
throughput these files may be re-used for the same electrode settings
[email protected])
in various calculations.

10.7 Utilities for analysis: TBtrans 13 PROBLEM HANDLING

Please see the separate TBtrans manual (tbtrans.pdf). 13.1 Error and warning messages

chkdim: ERROR: In routine dimension parameter = value. It must be

11 ANALYSIS TOOLS And other similar messages.
Description: Some array dimensions which change infrequently, and
There are a number of analysis tools and programs in the Util directory. do not lead to much memory use, are fixed to oversized values. This
Some of them have been directly or indirectly mentioned in this man- message means that one of this parameters is too small and neads
ual. Their documentation is the appropriate sub-directory of Util. See to be increased. However, if this occurs and your system is not very
Util/README. large, or unusual in some sense, you should suspect first of a mistake

108
 in the data file (incorrect atomic positions or cell dimensions, too the Perdew-Zunger LDA parametrization of xc, is based on routine
large cutoff radii, etc). velect, written by S. Froyen.
Fix: Check again the data file. Look for previous warnings or sus- • The serial version of the multivariate fast fourier transform used to
picious values in the output. If you find nothing unusual, edit the solve Poisson’s equation was written by Clive Temperton.
specified routine and change the corresponding parameter.
• Subroutine iomd.f for writing MD history in files was originally writ-
ten by J. Kohanoff.
14 REPORTING BUGS
We want to thank very specially O. F. Sankey, D. J. Niklewski and
Your assistance is essential to help improve the program. If you find any D. A. Drabold for making the FIREBALL code available to P. Ordejón.
problem, or would like to offer a suggestion for improvement, please follow Although we no longer use the routines in that code, it was essential in
the instructions in the file Docs/REPORTING_BUGS. the initial development of the SIESTA project, which still uses many of
Since SIESTA has moved to Launchpad you are encouraged to follow the the algorithms developed by them.
instructions presented at: https://answers.launchpad.net/siesta/ We thank V. Heine for his support and encouraging us in this project.
+faq/2779.
The SIESTA project is supported by the Spanish DGES through several
contracts. We also acknowledge past support by the Fundación Ramón
15 ACKNOWLEDGMENTS Areces.

We want to acknowledge the use of a small number of routines, written by

other authors, in developing the siesta code. In most cases, these routines
were acquired by now-forgotten routes, and the reported authorships are
based on their headings. If you detect any incorrect or incomplete attri-
bution, or suspect that other routines may be due to different authors,
please let us know.

• The main nonpublic contribution, that we thank thoroughly, are

modified versions of a number of routines, originally written by A.
R. Williams around 1985, for the solution of the radial Schrödinger
and Poisson equations in the APW code of Soler and Williams (PRB
42, 9728 (1990)). Within SIESTA, they are kept in files arw.f and
periodic_table.f, and they are used for the generation of the basis
orbitals and the screened pseudopotentials.

• The exchange-correlation routines contained in file xc.f were written

by J.M.Soler in 1996 and 1997, in collaboration with C. Balbás and
J. L. Martins. Routine pzxc (in the same file), which implements

109
 16 APPENDIX: Physical unit names recognized
by FDF

Magnitude Unit name MKS value

mass kg 1.E0
mass g 1.E-3
mass amu 1.66054E-27
length m 1.E0
length cm 1.E-2
length nm 1.E-9
length Ang 1.E-10
length Bohr 0.529177E-10
time s 1.E0
time fs 1.E-15
time ps 1.E-12
time ns 1.E-9
time mins 60.E0
time hours 3.6E3
time days 8.64E4
energy J 1.E0
energy erg 1.E-7
energy eV 1.60219E-19
energy meV 1.60219E-22
energy Ry 2.17991E-18
energy mRy 2.17991E-21
energy Hartree 4.35982E-18
energy Ha 4.35982E-18
energy K 1.38066E-23
energy kcal/mol 6.94780E-21
energy mHartree 4.35982E-21
energy mHa 4.35982E-21
energy kJ/mol 1.6606E-21
energy Hz 6.6262E-34
energy THz 6.6262E-22
energy cm-1 1.986E-23
energy cm**-1 1.986E-23
energy cmˆ -1 1.986E-23
force N 1.E0
force eV/Ang 1.60219E-9
110
force Ry/Bohr 4.11943E-8
Magnitude Unit name MKS value 17 APPENDIX: XML Output
pressure Pa 1.E0
pressure MPa 1.E6 From version 2.0, SIESTA includes an option to write its output to an
pressure GPa 1.E9 XML file. The XML it produces is in accordance with the CMLComp
pressure atm 1.01325E5 subset of version 2.2 of the Chemical Markup Language. Further infor-
pressure bar 1.E5 mation and resources can be found at http://cmlcomp.org/ and tools for
pressure Kbar 1.E8 working with the XML file can be found in the Util/CMLComp directory.
pressure Mbar 1.E11
pressure Ry/Bohr**3 1.47108E13 The main motivation for standarised XML (CML) output is as a step
pressure eV/Ang**3 1.60219E11 towards standarising formats for uses like the following.
charge C 1.E0
charge e 1.602177E-19 • To have SIESTA communicating with other software, either for
dipole C*m 1.E0 postprocessing or as part of a larger workflow scheme. In such a
dipole D 3.33564E-30 scenario, the XML output of one SIESTA simulation may be easily
dipole debye 3.33564E-30 parsed in order to direct further simulations. Detailed discussion of
dipole e*Bohr 8.47835E-30 this is out of the scope of this manual.
dipole e*Ang 1.602177E-29
• To generate webpages showing SIESTA output in a more accessible,
MomInert Kg*m**2 1.E0
graphically rich, fashion. This section will explain how to do this.
MomInert Ry*fs**2 2.17991E-48
Efield V/m 1.E0
Efield V/nm 1.E9 17.1 Controlling XML output
Efield V/Ang 1.E10
XML.Write true (logical)
Efield V/Bohr 1.8897268E10
Efield Ry/Bohr/e 2.5711273E11 Determine if the main XML file should be created for this run.
Efield Har/Bohr/e 5.1422546E11
Efield Ha/Bohr/e 5.1422546E11 17.2 Converting XML to XHTML
angle deg 1.d0
angle rad 5.72957795E1 The translation of the SIESTA XML output to a HTML-based webpage
torque eV/deg 1.E0 is done using XSLT technology. The stylesheets conform to XSLT-1.0
torque eV/rad 1.745533E-2 plus EXSLT extensions; an xslt processor capable of dealing with this is
torque Ry/deg 13.6058E0 necessary. However, in order to make the system easy to use, a script
torque Ry/rad 0.237466E0 called ccViz is provided in Util/CMLComp that works on most Unix or
torque meV/deg 1.E-3 Mac OS X systems. It is run like so:
torque meV/rad 1.745533E-5
./ccViz SystemLabel.xml
torque mRy/deg 13.6058E-3
torque mRy/rad 0.237466E-3 A new file will be produced. Point your web-browser at
SystemLabel.xhtml to view the output.

111
The generated webpages include support for viewing three-dimensional 18 APPENDIX: Selection of precision for stor-
interactive images of the system. If you want to do this, you will either age
need jMol (http://jmol.sourceforge.net) installed or access to the
internet. As this is a Java applet, you will also need a working Java
Some of the real arrays used in Siesta are by default single-precision,
Runtime Environment and browser plugin - installation instructions for
to save memory. This applies to the array that holds the values of the
these are outside the scope of this manual, though. However, the webpages
basis orbitals on the real-space grid, to the historical data sets in Broyden
are still useful and may be viewed without this plugin.
mixing, and to the arrays used in the O(N) routines. Note that the grid
An online version of this tool is avalable from http://cmlcomp.org/ functions (charge densities, potentials, etc) are now (since mid January
ccViz/, as are updated versions of the ccViz script. 2010) in double precision by default.
The following pre-processing symbols at compile time control the precision
selection

• Add -DGRID_SP to the DEFS variable in arch.make to use single-

precision for all the grid magnitudes, including the orbitals array
and charge densities and potentials. This will cause some numerical
differences and will have a negligible effect on memory consumption,
since the orbitals array is the main user of memory on the grid, and
it is single-precision by default. This setting will recover the default
behavior of versions prior to 4.0.

• Add -DGRID_DP to the DEFS variable in arch.make to use double-

precision for all the grid magnitudes, including the orbitals array.
This will significantly increase the memory used for large problems,
with negligible differences in accuracy.

• Add -DBROYDEN_DP to the DEFS variable in arch.make to use double-

precision arrays for the Broyden historical data sets. (Remember
that the Broyden mixing for SCF convergence acceleration is an
experimental feature.)

• Add -DON_DP to the DEFS variable in arch.make to use double-

precision for all the arrays in the O(N) routines.

112
19 APPENDIX: Data structures and reference
counting

To implement some of the new features (e.g. charge mixing and DM

extrapolation), SIESTA uses new flexible data structures. These are
defined and handled through a combination and extension of ideas already
in the Fortran community:

• Simple templating using the “include file” mechanism, as for ex-

ample in the FLIBS project led by Arjen Markus (http://flibs.
sourceforge.net).

• The classic reference-counting mechanism to avoid memory leaks,

as implemented in the PyF95++ project (http://blockit.
sourceforge.net).

Reference counting makes it much simpler to store data in container ob-

jects. For example, a circular stack is used in the charge-mixing module.
A number of future enhancements depend on this paradigm.

113
References jul 2014. ISSN 0953-8984. doi: 10.1088/0953-8984/26/30/
305503. URL http://stacks.iop.org/0953-8984/26/i=30/a=
[1] T. Auckenthaler, V. Blum, H.-J. Bungartz, T. Huckle, R. Jo- 305503?key=crossref.dd07c5e621546c5e67b1052b8800daca.
hanni, L. KrÃďmer, B. Lang, H. Lederer, and P.R. Willems. Par-
allel solution of partial symmetric eigenvalue problems from elec- [7] A Marek, V Blum, R Johanni, V Havu, B Lang, T Auckenthaler,
tronic structure calculations. Parallel Computing, 37(12):783 – 794, A Heinecke, H-J Bungartz, and H Lederer. The elpa library: scal-
2011. ISSN 0167-8191. doi: http://dx.doi.org/10.1016/j.parco.2011. able parallel eigenvalue solutions for electronic structure theory and
05.002. URL http://www.sciencedirect.com/science/article/ computational science. Journal of Physics: Condensed Matter, 26
pii/S0167819111000494. 6th International Workshop on Parallel (21):213201, 2014. URL http://stacks.iop.org/0953-8984/26/
Matrix Algorithms and Applications (PMAA’10). i=21/a=213201.

[2] Amartya S. Banerjee, Phanish Suryanarayana, and John E. Pask. [8] Taisuke Ozaki, Kengo Nishio, and Hiori Kino. Efficient imple-
Periodic Pulay method for robust and efficient convergence accel- mentation of the nonequilibrium Green function method for elec-
eration of self-consistent field iterations. Chemical Physics Letters, tronic transport calculations. Physical Review B, 81(3):035116, jan
647:31–35, mar 2016. ISSN 00092614. doi: 10.1016/j.cplett.2016. 2010. ISSN 1098-0121. doi: 10.1103/PhysRevB.81.035116. URL
01.033. URL http://linkinghub.elsevier.com/retrieve/pii/ http://link.aps.org/doi/10.1103/PhysRevB.81.035116.
S0009261416000464.
[9] Nick Papior, Tue Gunst, Daniele Stradi, and Mads Brandbyge. Ma-
[3] D.R Bowler and M.J Gillan. An efficient and robust technique nipulating the voltage drop in graphene nanojunctions using a gate
for achieving self consistency in electronic structure calculations. potential. Phys. Chem. Chem. Phys., 18(2):1025–1031, 2016. ISSN
Chemical Physics Letters, 325(4):473–476, jul 2000. ISSN 00092614. 1463-9076. doi: 10.1039/C5CP04613K. URL http://xlink.rsc.
doi: 10.1016/S0009-2614(00)00750-8. URL http://linkinghub. org/?DOI=C5CP04613K.
elsevier.com/retrieve/pii/S0009261400007508.
[10] Nick Papior, Nicolás Lorente, Thomas Frederiksen, Alberto Gar-
[4] Mads Brandbyge, José-Luis Mozos, Pablo Ordejón, Jeremy Tay- cía, and Mads Brandbyge. Improvements on non-equilibrium and
lor, and Kurt Stokbro. Density-functional method for nonequilib- transport Green function techniques: The next-generation TranSi-
rium electron transport. Physical Review B, 65(16):165401, mar esta. Computer Physics Communications, 212:8–24, mar 2017. ISSN
2002. ISSN 0163-1829. doi: 10.1103/PhysRevB.65.165401. URL 00104655. doi: 10.1016/j.cpc.2016.09.022. URL https://doi.org/
http://link.aps.org/doi/10.1103/PhysRevB.65.165401. 10.1016/j.cpc.2016.09.022.
[5] G. Kresse and J. Furthmüller. Efficiency of ab-initio total en- [11] Nick R. Papior. sisl, 2018. URL https://doi.org/10.5281/
ergy calculations for metals and semiconductors using a plane-wave zenodo.597181.
basis set. Computational Materials Science, 6(1):15–50, jul 1996.
ISSN 09270256. doi: 10.1016/0927-0256(96)00008-0. URL http: [12] M P Lopez Sancho, J M Lopez Sancho, and J. Rubio. Highly
//linkinghub.elsevier.com/retrieve/pii/0927025696000080. convergent schemes for the calculation of bulk and surface Green
functions. Journal of Physics F: Metal Physics, 15(4):851–
[6] Lin Lin, Alberto García, Georg Huhs, and Chao Yang. 858, apr 1985. ISSN 0305-4608. doi: 10.1088/0305-4608/15/
SIESTA-PEXSI: massively parallel method for efficient and ac- 4/009. URL http://stacks.iop.org/0305-4608/15/i=4/a=009?
curate ab initio materials simulation without matrix diagonal- key=crossref.8c77f34b0366ff84eaf622609268f5a2.
ization. Journal of Physics: Condensed Matter, 26(30):305503,

114
[13] José M. Soler and Eduardo Anglada. Optimal fourier filtering of
a function that is strictly confined within a sphere. Computer
Physics Communications, 180(7):1134 – 1136, 2009. ISSN 0010-4655.
doi: https://doi.org/10.1016/j.cpc.2009.01.017. URL http://www.
sciencedirect.com/science/article/pii/S0010465509000332.

115
Index
animation, 31 bug reports, 109
antiferromagnetic initial DM, 44 bulk polarization, 69

Backward compatibility, 42, 81 cell relaxation, 82

band structure, 64 Cerius2, 31
basis, 25 Charge confinement, 18, 24
basis set superposition error (BSSE), 24 Charge of the system, 72, 74
Bessel functions, 24 Chebyshev Polynomials, 58
default soft confinement, 21 Chemical Potential, 58
default soft confinement potential, 21 CML, 111
default soft confinement radius, 21 compile
filteret basis set, 24 libraries, 8
filtering, 24, 25 MPI, 7
fix split-valence table, 20 OpenMP, 7
Gen-basis standalone program, 25 pre-processor
Gen-basis standalone program, 25 -DCDF, 9
ghost atoms, 24 -DMPI, 7
minimal, 19 -DMPI_TIMING, 79
new split-valence code, 20 -DNCDF, 10
PAO, 19, 20, 22, 23 -DNCDF_4, 10, 80
per-shell split norm, 23 -DNCDF_PARALLEL, 10
point at infinity, 26 -DSIESTA__DIAG_2STAGE, 53
polarization, 20, 24 -DSIESTA__ELPA, 10
reparametrization of pseudopotential, 26 -DSIESTA__FLOOK, 11
soft confinement potential, 23 -DSIESTA__METIS, 10
split valence, 20 -DSIESTA__MRRR, 53, 54
split valence for H, 20 -DSIESTA__MUMPS, 10
User basis, 25 -DSIESTA__PEXSI, 10
User basis (NetCDF format), 25 Conjugate-gradient history information, 83
Berry phase, 69 constant-volume cell relaxation, 82
Bessel functions, 24 constraints in relaxations, 86
%block, 13 COOP/COHP curves, 68
Born effective charges, 70 Folding in Gamma-point calculations, 51
Broyden mixing, 112 Folding in Gamma-point calculations, 51
Broyden optimization, 83 cutoff radius, 23

116
Data Structures, 113 VV, 35
denchar, 79 WC, 34
density of states, 55, 66 External library
Dielectric function,optical absorption, 69 BLAS, 8
diffuse orbitals, 19 ELPA, 10
Doping, 72, 74 fdict, 9
double-ζ, 19 flook, 10, 81
LAPACK, 9
egg-box effect, 49, 50 Metis, 10
Eig2DOS, 55, 66 MPI, 7
ELPA, 10 MUMPS, 10
exchange-correlation ncdf, 10
AM05, 34 NetCDF, 9
BH, 35 OpenMP, 7
BLYP, 34 PEXSI, 10
C09, 35 ScaLAPACK, 9
CA, 34
DRSLL, 34 fatbands, 65
GGA, 34 FDF, 13
KBM, 35 fdf.log, 12, 13
LDA, 34 ferromagnetic initial DM, 44
LMKLL, 35 finite-range pseudo-atomic orbitals, 19
LSD, 34 fixed spin state, 35, 36
PBE, 34 flook, 10, 81
PBEGcGxHEG, 34 Force Constants Matrix, 81, 89
PBEGcGxLO, 34 fractional program, 15
PBEJsJrHEG, 34
PBEJsJrLO, 34 Gate, 73
PBEsol, 34 bounded plane, 74
PW91, 34 box, 74
PW92, 34 infinite plane, 73
PZ, 34 spheres, 74
revPBE, 34 Gaussians, 19
RPBE, 34 Gen-basis, 16
vdW, 34 Gen-basis, 25
vdW-DF, 34 ghost atoms, 15, 24
vdW-DF1, 34 gnubands, 64
vdW-DF2, 35 grid, 48

117
Grid precision, 112 basis, 25
Ground-state atomic configuration, 20 charge density, 75, 76
charge density and/or wfs for DENCHAR code, 79
Hirshfeld population analysis, 67, 68 customization, 14
dedicated files, 14
input file, 13
density matrix, 45, 46
interatomic distances, 32
density matrix history, 46, 47
isotopes, 15
eigenvalues, 14, 55, 66
JMol, 31 electrostatic potential, 75
JSON timing report, 79 forces, 14, 85
grid ~k points, 14, 34
Kleinman-Bylander projectors, 21 Hamiltonian, 46
Hamiltonian & overlap, 51
Localized Wave Functions, 58 Hamiltonian history, 47
Lower order N memory, 58 Hirshfeld analysis, 67, 68
LSD, 35, 36 HSX file, 51
Makefile, 7 Information for COOP/COHP curves, 68
mesh, 48 ionic charge, 76
Metis, 10 local density of states, 67
minimal basis, 19 long, 14
mixps program, 15 main output file, 14
Molden, 31 molecular dynamics
Mulliken population analysis, 14, 67 Force Constants Matrix, 88
multiple-ζ, 19, 20 history, 85, 86
MUMPS, 10 Mulliken analysis, 14, 67
overlap matrix, 46, 47
NetCDF format, 9, 25 overlap matrix history, 47
3, 9 projected density of states, 66
4, 10 total charge, 76
total potential, 75
output Voronoi analysis, 67, 68
δρ(~r), 75 wave functions, 14, 65
atomic coordinates output of wave functions for bands, 65
in a dynamics step, 14, 85
initial, 85 perturbative polarization, 20
Bader charge, 76 perturbative polarization, 24
band ~k points, 14, 64 PEXSI, 10
band structure, 64 PEXSI solver, 59

118
polarization orbitals, 19 harris energy convergence, 48
Precision selection, 112 Linear, 38
pseudopotential Pulay, 39
example generation, 11 Potential, 73
files, 16 Recomputing H, 42
generation, 16 SCF convergence criteria, 47
Scripting, 81
reading saved data, 79 Sies2arc, 31
all, 79 Sies2arc, 31
CG, 83 SIESTA, 4
charge density, 45 single-ζ, 19
deformation charge density, 45 Slab dipole correction, 73
density matrix, 44 Slabs with net charge, 73
localized wave functions (order-N ), 59 species, 15
XV, 32 spin, 36
ZM, 32 initialization, 44
readwf, 66 split valence, 19
readwfsx, 66 structure input precedence issues, 32
Reference counting, 113 synthetic atoms, 15
relaxation of cell parameters only, 82
removal of intramolecular pressure, 84 TBtrans, 108
Restart of O(N) calculations, 59 Tests, 11, 95
rippling, 49, 50 TranSIESTA, 5
transiesta
scale factor, 24 electrode
SCF, 37 principal layer, 96
compat-pre4-dm-h, 42
Doping, 72, 74 Variational character of E_KS, 37
mixing, 38, 42 VCA, 15
Broyden, 39 VIBRA, 88
Charge, 38, 42, 43 Voronoi population analysis, 67, 68
Density, 38
Density matrix convergence, 47 XML, 111
end of cycle, 42 XMol, 31
energy convergence, 47
energy density matrix convergence, 47
Hamiltonian, 38
Hamiltonian convergence, 47

119
List of SIESTA files
arch.make, 6–10, 53, 112 RhoXC.grid.nc, 75

BaderCharge.grid.nc, 76 Src/m_new_dm.F, 43
BASIS_ENTHALPY, 26, 48 SystemLabel..arc, 31
BASIS_HARRIS_ENTHALPY, 48 SystemLabel..DM, 44
SystemLabel.alloc, 78
Chlocal.grid.nc, 76 SystemLabel.amn, 72
constr.f, 87 SystemLabel.ANI, 31
SystemLabel.arc, 31
DeltaRho.grid.nc, 75
SystemLabel.ATOM.gv, 20
DeltaRho.IN.grid.nc, 45
SystemLabel.BADER, 76
DM-NNNN.nc, 46
SystemLabel.bands, 63, 64
DM.nc, 46
SystemLabel.bands.WFSX, 65
DM_MIXED.blocked, 46
SystemLabel.BC, 71
DM_OUT.blocked, 46
SystemLabel.BONDS, 32
DMHS-NNNN.nc, 47
SystemLabel.BONDS_FINAL, 32
DMHS.nc, 46
SystemLabel.CG, 83
ElectrostaticPotential.grid.nc, 75 SystemLabel.DIM, 79
SystemLabel.DM, 35, 44, 46, 79, 94, 107, 108
GRAPHVIZ_atom.gv, 99 SystemLabel.DMF, 44
GRAPHVIZ_orbital.gv, 99 SystemLabel.DOS, 66
SystemLabel.DRHO, 75
H_DMGEN, 46 SystemLabel.EIG, 55, 63
H_MIXED, 46 SystemLabel.eigW, 72
SystemLabel.EPSIMG, 69
m_new_dm.F, 51
SystemLabel.FA, 85
NEXT_ITER.UCELL.ZMATRIX, 31 SystemLabel.FAC, 85
SystemLabel.FC, 89
OCCS, 52 SystemLabel.FCC, 89
OUT.UCELL.ZMATRIX, 31 SystemLabel.fullBZ.WFSX, 55, 68
SystemLabel.grid.nc, 45
PEXSI_INTDOS, 63 SystemLabel.HS, 51
Rho.grid.nc, 63, 75 SystemLabel.HSX, 51, 68
Rho.IN.grid.nc, 45 SystemLabel.IOCH, 76
RhoInit.grid.nc, 76 SystemLabel.KP, 34, 108

120
SystemLabel.LDOS, 67 SystemLabel.XV, 31, 32, 79, 83, 85
SystemLabel.LDSI, 63 SystemLabel.xyz, 31
SystemLabel.LWF, 59, 79 SystemLabel.ZM, 32
SystemLabel.MD, 31, 85, 86
SystemLabel.MDC, 86 time.json, 79
SystemLabel.MDE, 86 TotalCharge.grid.nc, 76
SystemLabel.MDX, 31, 85, 86 TotalPotential.grid.nc, 75
SystemLabel.mmn, 71 TS_FERMI, 98
SystemLabel.N.TSHS, 47
UNKXXXXX.Y, 72
SystemLabel.nc, 80
SystemLabel.nnkp, 71 Vna.grid.nc, 75
SystemLabel.ORB.gv, 20
SystemLabel.ORB_INDX, 86 WFS.nc, 55, 65
SystemLabel.PDOS, 66, 67
SystemLabel.PDOS.xml, 67
SystemLabel.PLD, 79
SystemLabel.RHO, 75
SystemLabel.RHOINIT, 76
SystemLabel.RHOXC, 75
SystemLabel.selected.WFSX, 65
SystemLabel.STRUCT_IN, 31, 32
SystemLabel.STRUCT_NEXT_ITER, 31
SystemLabel.STRUCT_OUT, 31
SystemLabel.times, 79
SystemLabel.TOCH, 76
SystemLabel.TS.KP, 108
SystemLabel.TSCCEQ*, 108
SystemLabel.TSCCNEQ*, 108
SystemLabel.TSDE, 12, 94, 99, 103, 108
SystemLabel.TSGF*, 108
SystemLabel.TSHS, 12, 93, 94, 99, 102, 108
SystemLabel.VH, 75
SystemLabel.VNA, 75
SystemLabel.VT, 75
SystemLabel.WFS, 66, 68
SystemLabel.WFSX, 65, 66, 68, 79
SystemLabel.xtl, 31

121
List of fdf flags
AllocReportLevel, 78 COOP.Write, 51, 55, 65, 68
AllocReportThreshold, 79
AnalyzeChargeDensityOnly, 76, 77 Debug
AtomCoorFormatOut, 28, 31 DIIS, 43
AtomicCoordinatesAndAtomicSpecies, 15, 27, 28, 45, 86, 87 Diag
AtomicCoordinatesFormat, 27, 28, 31 AbsTol, 54
Ang, 28 Algorithm, 52–54
Bohr, 28 Divide-and-Conquer, 53
Fractional, 28 Divide-and-Conquer-2stage, 53
NotScaledCartesianAng, 28 ELPA-1stage, 53
NotScaledCartesianBohr, 28 ELPA-2stage, 53
ScaledByLatticeVectors, 28 Expert, 53
ScaledCartesian, 28 Expert-2stage, 53
AtomicCoordinatesOrigin, 28, 31 MRRR, 53
AtomicMass, 15 MRRR-2stage, 53
AtomSetupOnly, 25 NoExpert, 53
NoExpert-2stage, 53
BandLines, 54, 64, 65 QR, 53
BandLinesScale, 64 BlockSize, 52, 53
BandPoints, 54, 64, 65 DivideAndConquer, 53, 54
BasisPressure, 26 ELPA, 53, 54
BlockSize, 52, 53, 57, 77 Memory, 54
BornCharge, 70, 89 MRRR, 53, 54
NoExpert, 53, 54
CDF OrFac, 54
Compress, 80 ParallelOverK, 35, 52–54
Grid.Precision, 80 ProcessorY, 52, 53
MPI, 80 UpperLower, 54
Save, 80 Use2D, 52, 53
ChangeKgridInMD, 33 UseNewDiagk, 52, 55, 65
ChemicalSpeciesLabel, 15, 16, 23, 25, 26, 32, 87 DirectPhi, 78
Compat DM
Pre-v4-DM-H, 42 AllowExtrapolation, 45
Pre-v4-Dynamics, 81 AllowReuse, 45
Compat.Matel.NRTAB, 51 FormattedFiles, 44

122
 FormattedInput, 44 KB.New.Reference.Orbitals, 22
FormattedOutput, 44 kgrid
History.Depth, 45 Cutoff, 33
Init.Unfold, 44 MonkhorstPack, 27, 33
InitSpin, 45 kgrid.Cutoff, 66
AF, 44, 45 kgrid.MonkhorstPack, 66, 81
KickMixingWeight, see SF.Mixer.Kick.Weight40
MixingWeight, see SF.Mixer.Weight39, 42 LatticeConstant, 27
UseSaveDM, 38, 44 LatticeParameters, 27
DM.EnergyTolerance, 48 LatticeVectors, 27, 28, 33
DM.Init.Bulk, 97 LDAU.CutoffNorm, 89, 90
DM.InitSpin, 36 LDAU.EnergyShift, 89, 90
DM.MixSCF1, see SF.Mix.First38 LDAU.FirstIteration, 90
DM.Normalization.Tolerance, 47 LDAU.PopTol, 90
DM.NumberBroyden, see SF.Mixer.History39 LDAU.PotentialShift, 90
DM.NumberKick, see SF.Mixer.Kick39 LDAU.Proj, 89, 90
DM.NumberPulay, see SF.Mixer.History39 LDAU.ProjectorGenerationMethod, 89, 90
DM.Require.Harris.Convergence, 48 LDAU.ThresholdTol, 90
DM.RequireEnergyConvergence, 47 LocalDensityOfStates, 67
DM.Tolerance, 47 LongOutput, 14, 34, 85
DM.UseSaveDM, 57, 76 Lua
Debug, 92
EggboxRemove, 50 Debug.MPI, 92
EggboxScale, 50 Interactive, 92
ElectronicTemperature, 36, 55, 59, 97 Script, 91, 92
ExternalElectricField, 73
MaxBondDistance, 32
FilterCutoff, 24, 25 MaxSCFIterations, 37, 38
FilterTol, 25 MaxWalltime, 79
ForceAuxCell, 51 Slack, 79
MD
Geometry TypeOfRun, 32, 91
Charge, 74 UseSaveXV, 32
Constraints, 86, 97 UseSaveZM, 32
Hartree, 73, 74 MD.AnnealOption, 81, 84, 85
Grid.CellSampling, 49 MD.Broyden
Harris Cycle.On.Maxit, 83
Functional, 38 History.Steps, 83

123
 Initial.Inverse.Jacobian, 83 NoseParrinelloRahman, 81
MD.Broyden.Initial.Inverse.Jacobian, 82 ParrinelloRahman, 80
MD.BulkModulus, 85 Verlet, 80
MD.ConstantVolume, 82 MD.UseSaveCG, 83
MD.FCDispl, 89 MD.UseSaveXV, 83
MD.FCFirst, 89 MD.VariableCell, 50, 80, 82, 84
MD.FCLast, 89 MeshCutoff, 25, 36, 48, 81, 91
MD.FinalTimeStep, 84 MeshSubDivisions, 48
MD.FIRE.TimeStep, 83 MinSCFIterations, 37
MD.InitialTemperature, 84 MM, 77
MD.InitialTimeStep, 84 Cutoff, 77
MD.LengthTimeStep, 83, 84 Grimme.D, 77
MD.MaxCGDispl, 82, 83, 92 Grimme.S6, 77
MD.MaxDispl, 82 Potentials, 77
MD.MaxForceTol, 82, 92 UnitsDistance, 77
MD.MaxStressTol, 82 UnitsEnergy, 77
MD.NoseMass, 85 MPI
MD.NumCGsteps, 82 Nprocs.SIESTA, 59
MD.ParrinelloRahmanMass, 85 MullikenInSCF, 67
MD.PreconditionVariableCell, 82 MullikenInScf, 37
MD.RelaxCellOnly, 82
MD.RemoveIntramolecularPressure, 84 NeglNonOverlapInt, 50
MD.Steps, 82, 84 NetCharge, 72, 73, 75
MD.TargetPressure, 82, 84 New
MD.TargetStress, 82, 84 A.Parameter, 26
MD.TargetTemperature, 84 B.Parameter, 26
MD.TauRelax, 85 NumberOfAtoms, 15, 27, 28
MD.TypeOfRun, 80, 83–85, 88, 90 NumberOfEigenStates, 52–54
Anneal, 81, 85 NumberOfSpecies, 15
Broyden, 80, 82
OccupationFunction, 55
CG, 80, 82
OccupationMPOrder, 55
FC, 71, 81
OMM
FIRE, 80
BlockSize, 57
Forces, 81
Diagon, 56
Lua, 80, 81
DiagonFirstStep, 56
Master, 80, 81
Eigenvalues, 57
Nose, 80
LongOutput, 57

124
 Precon, 56 BasisSize, 19, 20, 23
PreconFirstStep, 56 DZ, 19
ReadCoeffs, 57 DZP, 20
RelTol, 57 minimal, 19
TPreconScale, 57 SZ, 19
Use2D, 56, 57 SZP, 20
UseCholesky, 56 BasisSizes, 20
UseSparse, 56 BasisType, 17, 19, 21, 23
WriteCoeffs, 57 filteret, 19
ON nodes, 19
Etol, 57 nonodes, 19
ON.ChemicalPotential, 58 split, 19
ON.ChemicalPotential.Order, 58 splitgauss, 19
ON.ChemicalPotential.Rc, 58 ContractionCutoff, 21
ON.ChemicalPotential.Temperature, 58 EnergyCutoff, 21
ON.ChemicalPotential.Use, 58 EnergyPolCutoff, 21
ON.eta, 56, 58 EnergyShift, 19, 20, 23–26
ON.eta.alpha, 58 FixSplitTable, 20, 21
ON.eta.beta, 58 NewSplitCode, 20, 21
ON.Etol, 57 OldStylePolOrbs, 24
ON.functional, 57 SoftDefault, 18, 21, 23
ON.LowerMemory, 58 SoftInnerRadius, 21
ON.MaxNumIter, 57 SoftPotential, 21
ON.RcLWF, 58 SplitNorm, 19, 20, 23
ON.UseSaveLWF, 59 SplitNormH, 20, 23
Optical.Broaden, 69 SplitTailNorm, 20, 21
Optical.Energy.Maximum, 69 PAO.Basis, 89
Optical.Energy.Minimum, 69 PAO.EnergyShift, 89
Optical.Mesh, 69 PartialChargesAtEveryGeometry, 68
Optical.NumberOfBands, 69 PartialChargesAtEverySCFStep, 68
Optical.OffsetMesh, 69 PDOS.kgrid.Cutoff, 66
Optical.PolarizationType, 69 PDOS.kgrid.MonkhorstPack, 66
Optical.Scissor, 69 PEXSI
Optical.Vector, 69 deltaE, 59
OpticalCalculation, 69 DOS, 63
Ef.Reference, 63
PAO Emax, 63
Basis, 15, 17–20, 22, 24

125
 Emin, 63 RcSpatial, 78
NPoints, 63 Reparametrize.Pseudos, 26
Gap, 59 Restricted.Radial.Grid, 26
Inertia-Counts, 61 Rmax.Radial.Grid, 26
Inertia-energy-width-tolerance, 62
Inertia-max-iter, 62 S.Only, 46
Inertia-min-num-shifts, 62 SaveBaderCharge, 76
Inertia-mu-tolerance, 62 SaveDeltaRho, 75
lateral-expansion-inertia, 62 SaveElectrostaticPotential, 75, 80
LDOS, 63 SaveHS, 51
Broadening, 63 SaveInitialChargeDensity, 76
Energy, 63 SaveIonicCharge, 76
NP-per-pole, 63 SaveNeutralAtomPotential, 75
mu, 61 SaveRho, 75
mu-max, 61 SaveRhoXC, 75
mu-max-iter, 61 SaveTotalCharge, 76
mu-min, 61 SaveTotalPotential, 75
mu-pexsi-safeguard, 61 SCF
NP-per-pole, 59, 60, 63 MonitorForces, 37
NP-symbfact, 60 MustConverge, 37, 38
num-electron-tolerance, 60 RecomputeHAfterSCF, 42
num-electron-tolerance-lower-bound, 60 RecomputeHAfterScf, 42
num-electron-tolerance-upper-bound, 60 Want.Variational.EKS, 37
NumPoles, 59 SCF.DebugRhoGMixing, 43
Ordering, 60 SCF.DM
safe-dDmax-ef-inertia, 62 Converge, 47, 48, 81
safe-dDmax-ef-solver, 62 Tolerance, 47
safe-dDmax-no-inertia, 61 SCF.EDM
safe-width-ic-bracket, 62 Converge, 47
safe-width-solver-bracket, 62 Tolerance, 47
Verbosity, 59, 60 SCF.FreeE
PolarizationGrids, 69–71 Converge, 47, 48
ProcessorY, 78 Tolerance, 48
ProjectedDensityOfStates, 66 SCF.H
PS Converge, 47, 48, 81
lmax, 21, 22 Tolerance, 36, 47
PS.KBprojectors, 22 SCF.Harris
Converge, 48

126
 Tolerance, 48 SCF.RhoGMixingCutoff, 43
SCF.Kerker.q0sq, 43 Siesta2Wannier90.NumberOfBands, 72
SCF.Mix, 36, 38, 42 Siesta2Wannier90.NumberOfBandsDown, 72
AfterConvergence, 37, 42, 46 Siesta2Wannier90.NumberOfBandsUp, 72
First, 38, 42, 73 Siesta2Wannier90.UnkGrid1, 72
Spin, 38 Siesta2Wannier90.UnkGrid2, 72
SCF.MixCharge Siesta2Wannier90.UnkGrid3, 72
SCF1, 43 Siesta2Wannier90.UnkGridBinary, 72
SCF.Mixer Siesta2Wannier90.WriteAmn, 71
History, 39, 40 Siesta2Wannier90.WriteEig, 72
Kick, 39, 40 Siesta2Wannier90.WriteMmn, 71
Kick.Weight, 40 Siesta2Wannier90.WriteUnk, 72
Linear.After, 40 SimulateDoping, 73
Linear.After.Weight, 40 SingleExcitation, 36
Method, 38–40 SlabDipoleCorrection, 73
Restart, 40 SolutionMethod, 33, 52, 55, 56, 97, 99
Restart.Save, 40 Spin, 35–37, 44, 45, 56
Variant, 38–40 Fix, 35, 36, 56
Weight, 39, 40 non-colinear, 35
SCF.Mixer.<>, 40 non-polarized, 35
history, 40 OrbitStrength, 36
iterations, 40 polarized, 35
method, 40 spin-orbit, 35
next, 41 Spiral, 33
next.conv, 41 Total, 35, 36, 56
next.p, 41 SpinInSCF, 67
restart, 40 SuperCell, 27, 33
restart.p, 41 SyntheticAtoms, 15
restart.save, 40 SystemLabel, 12, 15, 31, 94
variant, 40 SystemName, 15
weight, 40
weight.linear, 39, 40 TimeReversalSymmetryForKpoints, 33
SCF.Mixers, 40 TimerReportThreshold, 79
SCF.Read.Charge.NetCDF, 45 TS
SCF.Read.Deformation.Charge.NetCDF, 45 Analyze, 94, 96, 99, 100
SCF.RhoG.DIIS.Depth, 43 Analyze.Graphviz, 99
SCF.RhoG.Metric.Preconditioner.Cutoff, 43 Atoms.Buffer, 97
BTD

127
 Guess1.Max, 100 Bulk, 101, 103, 104
Guess1.Min, 100 check-kgrid, 103
Optimize, 100 chemical-potential, 102
Pivot, 99, 100 DE, 103
Spectral, 100 DM-Update, 103, 104, 108
ChargeCorrection, 98 electrode-position, 102
Factor, 98 Eta, 103, 104
Fermi.Max, 98 Gf, 103
Fermi.Tolerance, 98 Gf-Reuse, 103, 104
ChemPot.<>, 104 Hartree.Extend, 102
chemical-shift, 104 HS, 102
contour.eq, 104, 106 Out-of-core, 103, 104
contour.eq.pole, 105 pre-expand, 103
contour.eq.pole.N, 105 semi-inf-direction, 102
ElectronicTemperature, 97, 105 used-atoms, 103
kT, 105 Elecs, 100, 102, 104
mu, 104 Accuracy, 103, 104
Temp, 105 Bulk, 104
ChemPots, 102, 104 Coord.EPS, 104
Contour.<>, 106, 107 DM.Init, 97, 104
delta, 106 DM.Update, 104
from, 106 Eta, 103, 104
method, 106 Gf.Reuse, 104
opt, 106 Neglect.Principal, 96, 104
part, 106 Out-of-core, 104
points, 106 ElectronicTemperature, 97, 105, 107
Contour.nEq.<>, 107 Fermi.Initial, 97
Contours Forces, 98
Eq.Pole, 106 Hartree.Fix, 101, 102
Eq.Pole.N, 106 Frac, 102
Contours.nEq, 107 Hartree.Fix.Elec, 102
Eta, 107 Hartree.Offset, 102
Fermi.Cutoff, 107 HS.Save, 12, 95, 99
DE.Save, 12, 95, 99 MUMPS
Elec.<>, 102, 104 BlockingFactor, 101
Accuracy, 103, 104 Memory, 101
Bloch, 95, 103 Ordering, 100

128
 Poisson, 101 WFS.Band.Max, 65, 68
<file>, 101 WFS.Band.Min, 65, 68
elec-box, 101 WFS.Energy.Max, 65, 68
ramp-cell, 101, 102 WFS.Energy.Min, 65, 68
ramp-central, 101, 102 WFS.Write.For.Bands, 65
S.Save, 99 Write
SCF.Initialize, 97 Denchar, 79
SIESTA.Only, 99 DM, 46
SolutionMethod, 97, 99 DM.end.of.cycle, 46
BTD, 97, 99 DM.History.NetCDF, 46
full, 97 DM.NetCDF, 46, 47
MUMPS, 97 DMHS.History.NetCDF, 46, 47, 51
Voltage, 97 DMHS.NetCDF, 46, 47, 51
Weight.k.Method, 98 Graphviz, 20
Weight.Method, 97 H, 46
mean, 98 H.end.of.cycle, 46
orb-orb, 97 TSHS.History, 47
sum-atom-atom, 98 Write.OrbitalIndex, 86
sum-atom-orb, 98 WriteBands, 64
tr-atom-atom, 97 WriteCoorCerius, 31
tr-atom-orb, 98 WriteCoorInitial, 85
TS.Voltage, 13 WriteCoorStep, 14, 31, 85
WriteCoorXmol, 31
Use.Blocked.WriteMat, 46 WriteEigenvalues, 14, 55, 66
UseDomainDecomposition, 78 WriteForces, 14, 85
UseParallelTimer, 79 WriteHirshfeldPop, 67
User WriteIonPlotFiles, 25
Basis, 25 WriteKbands, 14, 64
Basis.NetCDF, 25 WriteKpoints, 14, 34
User.Basis, 16 WriteMDHistory, 31, 85, 86
UseSaveData, 32, 79, 83 WriteMDXmol, 31, 86
UseSpatialDecomposition, 78 WriteMullikenPop, 14, 36, 67
UseStructFile, 31, 32 WriteOrbMom, 36, 37
UseTreeTimer, 79 WriteVoronoiPop, 67
WriteWaveFunctions, 14, 65
WarningMinimumAtomicDistance, 32
WaveFuncKPoints, 54, 65, 68 XC
WaveFuncKPointsScale, 65 Authors, 34

129
 Functional, 34
Hybrid, 35
XML
Write, 111

ZM
UnitsAngle, 30
UnitsLength, 30
ZM.ForceTolAngle, 83
ZM.ForceTolLength, 83
ZM.MaxDisplAngle, 83
ZM.MaxDisplLength, 83
Zmatrix, 26, 28, 82, 84

130