SIESTA manual ../version.info

U s e r’ s G u i d e

S I E S T A 4.1.5

January 27, 2021

https://siesta-project.org

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

Contributors to SIESTA

The SIESTA project was initiated by Pablo Ordejon (then at the Univ. de Oviedo), and Jose M.

Soler and Emilio Artacho (Univ. Autonoma de Madrid, UAM). The development team was then

joined by Alberto Garcia (then at Univ. del Pais Vasco, Bilbao), Daniel Sanchez-Portal (UAM),

and Javier Junquera (Univ. de Oviedo and later UAM), and sometime later by Julian Gale (then at

Imperial College, London). In 2007 Jose M. Cela (Barcelona Supercomputing Center, BSC) became

a core developer and member of the Steering Committee.

The original TranSIESTA module was developed by Pablo Ordejon and Jose L. Mozos (then

at ICMAB-CSIC), and Mads Brandbyge, Kurt Stokbro, and Jeremy Taylor (Technical Univ. of

Denmark).

The current TranSIESTA module within SIESTA is developed by Nick R. Papior and Mads Brand-

byge. Nick R. Papior became a core developer and member of the Steering Committee in 2015.

Other contributors (we apologize for any omissions):

Eduardo Anglada, Thomas Archer, Luis C. Balbas, Xavier Blase, Ramon Cuadrado, Michele Ceriotti,

Fabiano Corsetti, Raul de la Cruz, Gabriel Fabricius, Marivi Fernandez-Serra, Jaime Ferrer, Chu-

Chun Fu, Sandra Garcia, Victor M. Garcia-Suarez, Rogeli Grima, Rainer Hoft, Georg Huhs, Jorge

Kohanoﬀ, Richard Korytar, In-Ho Lee, Lin Lin, Nicolas Lorente, Miquel Llunell, Eduardo Machado,

Maider Machado, Jose Luis Martins, Volodymyr Maslyuk, Juana Moreno, Frederico Dutilh Novaes,

Micael Oliveira, Magnus Paulsson, Oscar Paz, Andrei Postnikov, Roberto Robles, Tristana Sondon,

Andrew Walker, Andrew Walkingshaw, Toby White, Francois Willaime, Chao Yang.

O.F. Sankey, D.J. Niklewski and D.A. Drabold made the FIREBALL code available to P. Ordejon.

Although we no longer use the routines in that code, it was essential in the initial development of

SIESTA, which still uses many of the algorithms developed by them.

Contents

Contributors to SIESTA 2

1 INTRODUCTION 8

2 COMPILATION 10

2.1 The build directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.1.1 Multiple-target compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.2 The arch.make ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.3 Debug options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.4 Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.4.1 MPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.4.2 OpenMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.5 Library dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3 EXECUTION OF THE PROGRAM 17

3.1 Speciﬁc execution options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 THE FLEXIBLE DATA FORMAT (FDF) 20

5 PROGRAM OUTPUT 22

5.1 Standard output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.2 Output to dedicated ﬁles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 DETAILED DESCRIPTION OF PROGRAM OPTIONS 23

6.1 General system descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.2 Pseudopotentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.3 Basis set and KB projectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.3.1 Overview of atomic-orbital bases implemented in SIESTA . . . . . . . . . . . 25

6.3.2 Type of basis sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.3.3 Size of the basis set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.3.4 Range of the orbitals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.3.5 Generation of multiple-zeta orbitals . . . . . . . . . . . . . . . . . . . . . . . 30

6.3.6 Soft-conﬁnement options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.3.7 Kleinman-Bylander projectors . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.3.8 The PAO.Basis block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.3.9 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.3.10 Saving and reading basis-set information . . . . . . . . . . . . . . . . . . . . . 37

6.3.11 Tools to inspect the orbitals and KB projectors . . . . . . . . . . . . . . . . . 37

6.3.12 Basis optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.3.13 Low-level options regarding the radial grid . . . . . . . . . . . . . . . . . . . 38

6.4 Structural information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

6.4.1 Traditional structure input in the fdf ﬁle . . . . . . . . . . . . . . . . . . . . . 39

6.4.2 Z-matrix format and constraints . . . . . . . . . . . . . . . . . . . . . . . . . 41

6.4.3 Output of structural information . . . . . . . . . . . . . . . . . . . . . . . . . 45

6.4.4 Input of structural information from external ﬁles . . . . . . . . . . . . . . . 46

6.4.5 Input from a FIFO ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6.4.6 Precedence issues in structural input . . . . . . . . . . . . . . . . . . . . . . . 47

6.4.7 Interatomic distances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6.5 k-point sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6.5.1 Output of k-point information . . . . . . . . . . . . . . . . . . . . . . . . . . 49

6.6 Exchange-correlation functionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

6.7 Spin polarization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

6.8 Spin–Orbit coupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6.9 The self-consistent-ﬁeld loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

6.9.1 Harris functional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

6.9.2 Mixing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

6.9.3 Mixing of the Charge Density . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

6.9.4 Initialization of the density-matrix . . . . . . . . . . . . . . . . . . . . . . . . 63

6.9.5 Initialization of the SCF cycle with charge densities . . . . . . . . . . . . . . 65

6.9.6 Output of density matrix and Hamiltonian . . . . . . . . . . . . . . . . . . . 66

6.9.7 Convergence criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

6.10 The real-space grid and the eggbox-eﬀect . . . . . . . . . . . . . . . . . . . . . . . . 69

6.11 Matrix elements of the Hamiltonian and overlap . . . . . . . . . . . . . . . . . . . . 73

6.11.1 The auxiliary supercell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6.12 Calculation of the electronic structure . . . . . . . . . . . . . . . . . . . . . . . . . . 74

6.12.1 Diagonalization options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

6.12.2 Output of eigenvalues and wavefunctions . . . . . . . . . . . . . . . . . . . . 78

6.12.3 Occupation of electronic states and Fermi level . . . . . . . . . . . . . . . . . 79

6.12.4 Orbital minimization method (OMM) . . . . . . . . . . . . . . . . . . . . . . 79

6.12.5 Order(N) calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

6.13 The PEXSI solver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

6.13.1 Pole handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6.13.2 Parallel environment and control options . . . . . . . . . . . . . . . . . . . . 84

6.13.3 Electron tolerance and the PEXSI solver . . . . . . . . . . . . . . . . . . . . . 86

6.13.4 Inertia-counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

6.13.5 Re-use of µ information accross iterations . . . . . . . . . . . . . . . . . . . . 88

6.13.6 Calculation of the density of states by inertia-counting . . . . . . . . . . . . . 89

6.13.7 Calculation of the LDOS by selected-inversion . . . . . . . . . . . . . . . . . 89

6.14 Band-structure analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

6.14.1 Format of the .bands ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

6.14.2 Output of wavefunctions associated to bands . . . . . . . . . . . . . . . . . . 91

6.15 Output of selected wavefunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

6.16 Densities of states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

6.16.1 Total density of states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

6.16.2 Partial (projected) density of states . . . . . . . . . . . . . . . . . . . . . . . 93

6.16.3 Local density of states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

6.17 Options for chemical analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

6.17.1 Mulliken charges and overlap populations . . . . . . . . . . . . . . . . . . . . 95

6.17.2 Voronoi and Hirshfeld atomic population analysis . . . . . . . . . . . . . . . . 95

6.17.3 Crystal-Orbital overlap and hamilton populations (COOP/COHP) . . . . . . 96

6.18 Optical properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

6.19 Macroscopic polarization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

6.20 Maximally Localized Wannier Functions . . . . . . . . . . . . . . . . . . . . . . . . . 100

6.21 Systems with net charge or dipole, and electric ﬁelds . . . . . . . . . . . . . . . . . . 102

6.22 Output of charge densities and potentials on the grid . . . . . . . . . . . . . . . . . . 106

6.23 Auxiliary Force ﬁeld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

6.24 Parallel options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

6.24.1 Parallel decompositions for O(N) . . . . . . . . . . . . . . . . . . . . . . . . . 110

6.25 Eﬃciency options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

6.26 Memory, CPU-time, and Wall time accounting options . . . . . . . . . . . . . . . . . 111

6.27 The catch-all option UseSaveData . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6.28 Output of information for Denchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6.29 NetCDF (CDF4) output ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

7 STRUCTURAL RELAXATION, PHONONS, AND MOLECULAR DYNAM-

ICS 113

7.1 Compatibility with pre-v4 versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

7.2 Structural relaxation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

7.2.1 Conjugate-gradients optimization . . . . . . . . . . . . . . . . . . . . . . . . . 117

7.2.2 Broyden optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

7.2.3 FIRE relaxation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

7.3 Target stress options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

7.4 Molecular dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

7.5 Output options for dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

7.6 Restarting geometry optimizations and MD runs . . . . . . . . . . . . . . . . . . . . 121

7.7 Use of general constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

7.8 Phonon calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

8 DFT+U 125

9 External control of SIESTA 127

9.1 Examples of Lua programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

9.2 External MD/relaxation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

10 TRANSIESTA 131

10.1 Source code structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

10.2 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

10.3 Brief description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

10.4 Electrodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

10.4.1 Matching coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

10.4.2 Principal layer interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

10.5 Convergence of electrodes and scattering regions . . . . . . . . . . . . . . . . . . . . 136

10.6 TranSIESTA Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

10.6.1 Quick and dirty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

10.6.2 General options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

10.6.3 Algorithm speciﬁc options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

10.6.4 Poisson solution for ﬁxed boundary conditions . . . . . . . . . . . . . . . . . 146

10.6.5 Electrode description options . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

10.6.6 Chemical potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

10.6.7 Complex contour integration options . . . . . . . . . . . . . . . . . . . . . . . 152

10.6.8 Bias contour integration options . . . . . . . . . . . . . . . . . . . . . . . . . 154

10.7 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

10.8 Utilities for analysis: TBtrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

11 ANALYSIS TOOLS 156

12 SCRIPTING 156

13 PROBLEM HANDLING 157

13.1 Error and warning messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

14 REPORTING BUGS 157

15 ACKNOWLEDGMENTS 157

16 APPENDIX: Physical unit names recognized by FDF 159

17 APPENDIX: XML Output 161

17.1 Controlling XML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

17.2 Converting XML to XHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

18 APPENDIX: Selection of precision for storage 162

19 APPENDIX: Data structures and reference counting 163

Bibliography 164

Index 166

1 INTRODUCTION

This Reference Manual contains descriptions of all the input, output and execution features of

SIESTA, but is not really a tutorial introduction to the program. Interested users can ﬁnd tu-

torial material prepared for SIESTA schools and workshops at the project’s web page https:

//siesta-project.org

NOTE: See the description of changes in the logic of the SCF loop

SIESTA (Spanish Initiative for Electronic Simulations with Thousands of Atoms) is both a method

and its computer program implementation, to perform electronic structure calculations and ab initio

molecular dynamics simulations of molecules and solids. Its main characteristics are:

• It uses the standard Kohn-Sham selfconsistent density functional method in the local den-

sity (LDA-LSD) and generalized gradient (GGA) approximations, as well as in a non local

functional that includes van der Waals interactions (VDW-DF).

• It uses norm-conserving pseudopotentials in their fully nonlocal (Kleinman-Bylander) form.

• It uses atomic orbitals as a basis set, allowing unlimited multiple-zeta and angular momenta,

polarization and oﬀ-site orbitals. The radial shape of every orbital is numerical and any shape

can be used and provided by the user, with the only condition that it has to be of ﬁnite support,

i.e., it has to be strictly zero beyond a user-provided distance from the corresponding nucleus.

Finite-support basis sets are the key for calculating the Hamiltonian and overlap matrices in

O(N) operations.

• Projects the electron wavefunctions and density onto a real-space grid in order to calculate the

Hartree and exchange-correlation potentials and their matrix elements.

• Besides the standard Rayleigh-Ritz eigenstate method, it allows the use of localized linear

combinations of the occupied orbitals (valence-bond or Wannier-like functions), making the

computer time and memory scale linearly with the number of atoms. Simulations with several

hundred atoms are feasible with modest workstations.

• It is written in Fortran 2003 and memory is allocated dynamically.

• It may be compiled for serial or parallel execution (under MPI).

It routinely provides:

• Total and partial energies.

• Atomic forces.

• Stress tensor.

• Electric dipole moment.

• Atomic, orbital and bond populations (Mulliken).

• Electron density.

And also (though not all options are compatible):

• Geometry relaxation, ﬁxed or variable cell.

• Constant-temperature molecular dynamics (Nose thermostat).

• Variable cell dynamics (Parrinello-Rahman).

• Spin polarized calculations (colinear or not).

• k-sampling of the Brillouin zone.

• Local and orbital-projected density of states.

• COOP and COHP curves for chemical bonding analysis.

• Dielectric polarization.

• Vibrations (phonons).

• Band structure.

• Ballistic electron transport under non-equilibrium (through TranSIESTA)

Starting from version 3.0, SIESTA includes the TranSIESTA module. TranSIESTA provides

the ability to model open-boundary systems where ballistic electron transport is taking place. Using

TranSIESTA one can compute electronic transport properties, such as the zero bias conductance

and the I-V characteristic, of a nanoscale system in contact with two electrodes at diﬀerent elec-

trochemical potentials. The method is based on using non equilibrium Greens functions (NEGF),

that are constructed using the density functional theory Hamiltonian obtained from a given electron

density. A new density is computed using the NEGF formalism, which closes the DFT-NEGF self

consistent cycle.

Starting from version 4.1, TranSIESTA is an intrinsic part of the SIESTA code. I.e. a separate

executable is not necessary anymore. See Sec. 10 for details.

For more details on the formalism, see the main TranSIESTA reference cited below. A section

has been added to this User’s Guide, that describes the necessary steps involved in doing transport

calculations, together with the currently implemented input options.

References:

• “Unconstrained minimization approach for electronic computations that scales linearly with

system size” P. Ordejón, D. A. Drabold, M. P. Grumbach and R. M. Martin, Phys. Rev. B 48,

14646 (1993); “Linear system-size methods for electronic-structure calculations” Phys. Rev.

B 51 1456 (1995), and references therein.

Description of the order-N eigensolvers implemented in this code.

• “Self-consistent order-N density-functional calculations for very large systems” P. Ordejón, E.

Artacho and J. M. Soler, Phys. Rev. B 53, 10441, (1996).

Description of a previous version of this methodology.

• “Density functional method for very large systems with LCAO basis sets” D. Sánchez-Portal,

P. Ordejón, E. Artacho and J. M. Soler, Int. J. Quantum Chem., 65, 453 (1997).

Description of the present method and code.

• “Linear-scaling ab-initio calculations for large and complex systems” E. Artacho, D. Sánchez-

Portal, P. Ordejón, A. García and J. M. Soler, Phys. Stat. Sol. (b) 215, 809 (1999).

Description of the numerical atomic orbitals (NAOs) most commonly used in the code, and

brief review of applications as of March 1999.

• “Numerical atomic orbitals for linear-scaling calculations” J. Junquera, O. Paz, D. Sánchez-

Portal, and E. Artacho, Phys. Rev. B 64, 235111, (2001).

Improved, soft-conﬁned NAOs.

• “The SIESTA method for ab initio order-N materials simulation” J. M. Soler, E. Artacho,

J.D. Gale, A. García, J. Junquera, P. Ordejón, and D. Sánchez-Portal, J. Phys.: Condens.

Matter 14, 2745-2779 (2002)

Extensive description of the SIESTA method.

• “Computing the properties of materials from ﬁrst principles with SIESTA”, D. Sánchez-Portal,

P. Ordejón, and E. Canadell, Structure and Bonding 113, 103-170 (2004).

Extensive review of applications as of summer 2003.

• “Improvements on non-equilibrium and transport Green function techniques: The next-

generation TranSIESTA”, Nick Papior, Nicolas Lorente, Thomas Frederiksen, Alberto García

and Mads Brandbyge, Computer Physics Communications, 212, 8–24 (2017).

Description of the TranSIESTA method.

• “Density-functional method for nonequilibrium electron transport”, Mads Brandbyge, Jose-

Luis Mozos, Pablo Ordejón, Jeremy Taylor, and Kurt Stokbro, Phys. Rev. B 65, 165401

(2002).

Description of the original TranSIESTA method (prior to 4.1).

• “Siesta: Recent developments and applications”, Alberto García, et al., J. Chem. Phys. 152,

204108 (2020).

Extensive review of applications and developments as of 2020.

For more information you can visit the web page https://siesta-project.org.

2 COMPILATION

2.1 The build directory

Rather than using the top-level Src directory as building directory, the user has to use an ad-hoc

building directory (by default the top-level Obj directory, but it can be any (new) directory in the

top level). The building directory will hold the object ﬁles, module ﬁles, and libraries resulting from

the compilation of the sources in Src. The VPATH mechanism of modern make programs is used.

This scheme has many advantages. Among them:

• The Src directory is kept pristine.

• Many diﬀerent object directories can be used concurrently to compile the program with diﬀer-

ent compilers or optimization levels.

If you just want to compile the program, go to Obj and issue the command:

sh ../Src/obj_setup.sh

to populate this directory with the minimal scaﬀolding of makeﬁles, and then make sure that you

create or generate an appropriate arch.make ﬁle (see below, in Sec. 2.2). Then, type

make

The executable should work for any job. (This is not exactly true, since some of the parameters in

the atomic routines are still hardwired (see Src/atmparams.f), but those would seldom need to be

changed.)

To compile utility programs (those living in Util), you can just simply use the provided makeﬁles,

typing “make” as appropriate.

2.1.1 Multiple-target compilation

The mechanism described here can be repeated in other directories at the same level as Obj, with

diﬀerent names. In this way one can compile as many diﬀerent versions of the SIESTA executable

as needed (for example, with diﬀerent levels of optimization, serial, parallel, debug, etc), by working

in separate building directories.

Simply provide the appropriate arch.make, and issue the setup command above. To compile utility

programs, you need to use the form:

make OBJDIR=ObjName

where ObjName is the name of the object directory of your choice. Be sure to type make clean before

attempting to re-compile a utility program.

(The pristine Src directory should be kept “clean”, without objects, or else the compilation in the

build directories will get confused)

2.2 The arch.make ﬁle

The compilation of the program is done using a Makefile that is provided with the code. This

Makefile will generate the executable for any of several architectures, with a minimum of tuning

required from the user and encapsulated in a separate ﬁle called arch.make.

You are strongly encouraged to look at Obj/DOCUMENTED-TEMPLATE.make for information about the

ﬁne points of the arch.make ﬁle. There are two sample make ﬁles for compilation of SIESTA with

gfortran and ifort named Obj/gfortran.make and Obj/intel.make, respectively. Please use

those as guidelines for creating the ﬁnal arch.make.

NOTE: Intel compilers default to high optimizations which tends to break SIESTA. We advice to

use -fp-model source ﬂag and not compile with higher optimizations than -O2.

NOTE: Since gfortran version 10.x the interfaces are strictly checked. Currently you have to add

-fallow-argument-mismatch to FFLAGS to turn errors into warnings. These warnings are safe to

ignore and will look something like:

.../siesta/Src/fsiesta_mpi.F90:441:18:

440 | call MPI_Bcast( n, 1, MPI_Integer, 0, MPI_Comm_Siesta, error )

| 2

441 | call MPI_Bcast( x, 3*na, MPI_Double_Precision, 0, MPI_Comm_Siesta, error )

| 1

Warning: Type mismatch between actual argument at (1) and actual argument at (2) (REAL(8)/INTEGER(4)).

2.3 Debug options

Being able to build SIESTA in debug mode is crucial for ﬁnding bugs and debugging builds.

When changing build ﬂags in the arch.make ﬁle it is imperative to clean the build directory. Please

do a make clean then do make.

For GFortran, use the following ﬂags:

FFLAGS = -Og -g -pedantic -Wall -fcheck=all -fbacktrace -Warray-bounds -Wunused -Wuninitialized

For Intel, use the following ﬂags:

FFLAGS = -Og -g -check bounds -traceback -fp-model strict

This will make SIESTA run signiﬁcantly slower. Please report any crashes to the developer team

at https://gitlab.com/siesta-project/siesta/-/issues.

2.4 Parallel

To achieve a parallel build of SIESTA one should ﬁrst determine which type of parallelism one

requires. It is advised to use MPI for calculations with moderate number of cores. If one requires

eXa-scale parallelism SIESTA provides hybrid parallelism using both MPI and OpenMP.

2.4.1 MPI

MPI is a message-passing interface which enables communication between equivalently executed

binaries. This library will thus duplicate all non-distributed data such as local variables etc.

To enable MPI in SIESTA the compilation options are required to be changed accordingly, here is

the most basic changes to the arch.make for standard binary names

CC = mpicc

FC = mpifort # or mpif90

MPI_INTERFACE = libmpi_f90.a

MPI_INCLUDE = .

FPPFLAGS += -DMPI

Subsequently one may run SIESTA using the mpirun/mpiexec commands:

mpirun -np <> siesta RUN.fdf

where <> is the number of cores used.

2.4.2 OpenMP

OpenMP is shared memory parallelism. It typically does not infer any memory overhead and may

be used if memory is scarce and the regular MPI compilation is crashing due to insuﬃcient memory.

To enable OpenMP, simply add this to your arch.make

# For GNU compiler

FFLAGS += -fopenmp

LIBS += -fopenmp

# or, for Intel compiler < 16

FFLAGS += -openmp

LIBS += -openmp

# or, for Intel compiler >= 16

FFLAGS += -qopenmp

LIBS += -qopenmp

The above will yield the most basic parallelism using OpenMP. However, the BLAS/LAPACK

libraries which is the most time-consuming part of SIESTA also requires to be threaded, please see

Sec. 2.5 for correct linking.

Subsequently one may run SIESTA using OpenMP through the environment variable

OMP_NUM_THREADS which determine the number of threads/cores used in the execution.

OMP_NUM_THREADS=<> siesta RUN.fdf

# or (bash)

export OMP_NUM_THREADS=<>

siesta RUN.fdf

# or (csh)

setenv OMP_NUM_THREADS <>

siesta RUN.fdf

where <> is the number of threads/cores used.

If SIESTA is also compiled using MPI it is more diﬃcult to obtain a good performance. Please

refer to your local cluster how to correctly call MPI with hybrid parallelism. An example for running

SIESTA with good performance using OpenMPI > 1.8.2 and OpenMP on a machine with 2 sockets

and 8 cores per socket, one may do:

# MPI = 2 cores, OpenMP = 8 threads per core (total=16)

mpirun --map-by ppr:1:socket:pe=8 \

-x OMP_NUM_THREADS=8 \

-x OMP_PROC_BIND=true siesta RUN.fdf

# MPI = 4 cores, OpenMP = 4 threads per core (total=16)

mpirun --map-by ppr:2:socket:pe=4 \

-x OMP_NUM_THREADS=4 \

-x OMP_PROC_BIND=true siesta RUN.fdf

# MPI = 8 cores, OpenMP = 2 threads per core (total=16)

mpirun --map-by ppr:4:socket:pe=2 \

-x OMP_NUM_THREADS=2 \

-x OMP_PROC_BIND=true siesta RUN.fdf

If using only 1 thread per MPI core it is advised to compile SIESTA without OpenMP. As such it

may be advantageous to compile SIESTA in 3 variants; OpenMP-only (small systems), MPI-only

(medium to large systems) and MPI+OpenMP (large> systems).

The variable OMP_PROC_BIND may heavily inﬂuence the performance of the executable! Please per-

form tests for the architecture used.

2.5 Library dependencies

SIESTA makes use of several libraries. Here we list a set of libraries and how each of them may be

added to the compilation step (arch.make).

SIESTA is distributed with scripts that install the most useful libraries. These installation scripts

may be located in the Docs/ folder with names: install_*.bash. Currently SIESTA is shipped

with these installation scripts:

• install_netcdf4.bash; installs NetCDF with full CDF4 support. Thus it installs zlib, hdf5

and NetCDF C and Fortran.

• install_flook.bash; installs flook which enables interaction with Lua and SIESTA.

Note that these scripts are guidance scripts and users are encouraged to check the mailing list for

or seek help there in non-standard. The installation scripts ﬁnishes by telling what to add to the

arch.make ﬁle to correctly link the just installed libraries.

BLAS it is recommended to use a high-performance library (OpenBLAS or MKL library from Intel)

• If you use your *nix distribution package manager to install BLAS you are bound to have

a poor performance. Please try and use performance libraries, whenever possible!

• If you do not have the BLAS library you may use the BLAS library shipped with SIESTA.

To do so simply add libsiestaBLAS.a to the COMP_LIBS variable.

To add BLAS to the arch.make ﬁle you need to add the required linker ﬂags to the LIBS

variable in the arch.make ﬁle.

Example variables

# OpenBLAS:

LIBS += -L/opt/openblas/lib -lopenblas

# or for MKL

LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_blas95_lp64

-lmkl_<>_lp64 ...

where <> is the compiler used (intel or gf for gnu).

To use the threaded (OpenMP) libraries

# OpenBLAS, change the above to:

LIBS += -L/opt/openblas/lib -lopenblasp

# or for MKL, add a single flag:

LIBS += -lmkl_<>_thread

where <> is the compiler used (intel or gnu).

LAPACK it is recommended to use a high-performance library (OpenBLAS

or MKL library from

Intel)

If you do not have the LAPACK library you may use the LAPACK library shipped with

SIESTA. To do so simply add libsiestaLAPACK.a to the COMP_LIBS variable.

Example variables

# OpenBLAS (OpenBLAS will default to build in LAPACK)

LIBS += -L/opt/openblas/lib -lopenblas

# or for MKL

LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_lapack95_lp64 ...

To use the threaded (OpenMP) libraries

# OpenBLAS, change the above to:

LIBS += -L/opt/openblas/lib -lopenblasp

# or for MKL, add a single flag:

LIBS += -lmkl_<>_thread ...

where <> is the compiler used (intel or gnu).

ScaLAPACK Only required for MPI compilation.

Here one may be suﬃcient to rely on the NetLIB

version of ScaLAPACK.

Example variables

# ScaLAPACK

LIBS += -L/opt/scalapack/lib -lscalapack

# or for MKL

LIBS += -L/opt/intel/.../mkl/lib/intel64 -lmkl_scalapack_lp64

-lmkl_blacs_<>_lp64 ...

where <> refers to the MPI version used, (intelmpi, openmpi, sgimpt).

Additionally SIESTA may be compiled with support for several other libraries

fdict This library is shipped with SIESTA and its linking may be enabled by

COMP_LIBS += libfdict.a

OpenBLAS enables the inclusion of the LAPACK routines. This is advised.

ScaLAPACKs performance is mainly governed by BLAS and LAPACK.

NetCDF It is advised to compile NetCDF in CDF4 compliant mode (thus also linking with HDF5)

as this enables more advanced IO. If you only link against a CDF3 compliant library you will

not get the complete feature set of SIESTA.

3 If the CDF3 compliant library is present one may add this to your arch.make:

LIBS += -L/opt/netcdf/lib -lnetcdff -lnetcdf

FPPFLAGS += -DCDF

4 If the CDF4 compliant library is present the HDF5 libraries are also required at link time:

LIBS += -L/opt/netcdf/lib -lnetcdff -lnetcdf \

-lhdf5_fortran -lhdf5 -lz

ncdf This library is shipped with SIESTA and its linking is required to take advantage of the CDF4

library functionalities. To use this library, ensure that you can compile SIESTA with CDF4

support. Then proceed by adding the following to your arch.make

COMP_LIBS += libncdf.a libfdict.a

FPPFLAGS += -DNCDF -DNCDF_4

If the NetCDF library is compiled with parallel support one may take advantage of parallel IO

by adding this to the arch.make

FPPFLAGS += -DNCDF_PARALLEL

To easily install NetCDF please see the installation ﬁle: Docs/install_netcdf4.bash.

Metis The Metis library may be used in the Order-N code.

Add these ﬂags to your arch.make ﬁle to enable Metis

LIBS += -L/opt/metis/lib -lmetis

FPPFLAGS += -DSIESTA__METIS

ELPA The ELPA

[1;8]

library provides faster diagonalization routines.

The version of ELPA must be 2017.05.003 or later, since the new ELPA API is used.

Add these ﬂags to your arch.make ﬁle to enable ELPA

LIBS += -L/opt/elpa/lib -lelpa <>

FPPFLAGS += -DSIESTA__ELPA -I/opt/elpa/include/elpa-<>/modules

where <> are any libraries that ELPA depend on.

NOTE: ELPA can only be used in the parallel version of SIESTA.

MUMPS The MUMPS library may currently be used with TranSIESTA.

Add these ﬂags to your arch.make ﬁle to enable MUMPS

LIBS += -L/opt/mumps/lib -lzmumps -lmumps_common <>

FPPFLAGS += -DSIESTA__MUMPS

where <> are any libraries that MUMPS depend on.

PEXSI The PEXSI library may be used with this version of SIESTA for massively-parallel cal-

culations, see Sec. 6.13. Note however that the PEXSI interface in this version is the original

one, corresponding to PEXSI versions 0.8.X and 0.9.X. In particular, it has been tested for

0.8.0, 0.9.0 and 0.9.2. It is possible that it might work for newer versions of the form 0.9.X,

but, beginning with version 1.0, the PEXSI library is no longer compatible with this interface.

Newer versions of SIESTA (in the Gitlab development site) can use the current PEXSI library

through the ELSI library interface.

To successfully compile SIESTA with PEXSI support one require the PEXSI fortran interface.

When installing PEXSI copy the f_interface.f90 ﬁle to the include directory of PEXSI such

that the module may be found

when compiling SIESTA.

Add these ﬂags to your arch.make ﬁle to enable PEXSI

INCFLAGS += -I/opt/pexsi/include

LIBS += -L/opt/pexsi/lib -lpexsi_linux <>

FPPFLAGS += -DSIESTA__PEXSI

where <> are any libraries that PEXSI depend on. If one experiences linker failures, one

possible solution that may help is

LIBS += -lmpi_cxx -lstdc++

which is due to PEXSI being a C++ library, and the Fortran compiler is the linker. The exact

library name for your MPI vendor may vary.

Additionally the PEXSI linker step may have duplicate objects which can be circumvented by

preﬁxing the PEXSI libraries with

LIBS += -Wl,--allow-multiple-definition -lpexsi_linux <>

ﬂook SIESTA allows external control via the LUA scripting language. Using this library one may

do advanced MD simulations and much more without changing any code in SIESTA.

Add these ﬂags to your arch.make ﬁle to enable flook

LIBS += -L/opt/flook/lib -lflookall -ldl

COMP_LIBS += libfdict.a

FPPFLAGS += -DSIESTA__FLOOK

See Tests/h2o_lua for an example on the LUA interface.

To easily install flook please see the installation ﬁle: Docs/install_flook.bash.

3 EXECUTION OF THE PROGRAM

A fast way to test your installation of SIESTA and get a feeling for the workings of the program

is implemented in directory Tests. In it you can ﬁnd several subdirectories with pre-packaged fdf

ﬁles and pseudopotential references. Everything is automated: after compiling SIESTA you can

just go into any subdirectory and type make. The program does its work in subdirectory work, and

there you can ﬁnd all the resulting ﬁles. For convenience, the output ﬁle is copied to the parent

Optionally the ﬁle may be copied to the Obj directory where the compilation takes place

directory. A collection of reference output ﬁles can be found in Tests/Reference. Please note

that small numerical and formatting diﬀerences are to be expected, depending on the compiler.

(For non-standard execution environments, including queuing systems, have a look at the Scripts in

Tests/Scripts, and see also Sec. 2.4.)

Other examples are provided in the Examples directory. This directory contains basically .fdf ﬁles

and the appropriate pseudopotential generation input ﬁles. Since at some point you will have to

generate your own pseudopotentials and run your own jobs, we describe here the whole process by

means of the simple example of the water-molecule. It is advisable to create independent directories

for each job, so that everything is clean and neat, and out of the SIESTA directory, so that one can

easily update version by replacing the whole SIESTA tree. Go to your favorite working directory

and:

$ mkdir h2o

$ cd h2o

$ cp path-to-package/Examples/H2O/h2o.fdf

You need to make the siesta executable visible in your path. You can do it in many ways, but a

simple one is

$ ln -s path-to-package/Obj/siesta

We need to generate the required pseudopotentials. (We are going to streamline this process for

this time, but you must realize that this is a tricky business that you must master before using

SIESTA responsibly. Every pseudopotential must be thoroughly checked before use. Please refer

to the ATOM program manual for details regarding what follows.)

NOTE: The ATOM program is no longer bundled with SIESTA, but academic users can dowload

it from the SIESTA webpage at www.icmab.es/siesta.

$ cd path/to/atom/package/

(Compile the program following the instructions)

$ cd Tutorial/PS_Generation/O

$ cat O.tm2.inp

This is the input ﬁle, for the oxygen pseudopotential, that we have prepared for you. It is in a

standard (but ancient and obscure) format that you will need to understand in the future:

------------------------------------------------------------

pg Oxygen

tm2 2.0

n=O c=ca

0.0 0.0 0.0 0.0 0.0 0.0

1 4

2 0 2.00 0.00

2 1 4.00 0.00

3 2 0.00 0.00

4 3 0.00 0.00

1.15 1.15 1.15 1.15

------------------------------------------------------------

To generate the pseudopotential do the following;

$ sh ../../Utils/pg.sh O.tm2.inp

Now there should be a new subdirectory called O.tm2 (O for oxygen) and O.tm2.vps (binary) and

O.tm2.psf (ASCII) ﬁles.

$ cp O.tm2.psf path-to-working-dir/h2o/O.psf

copies the generated pseudopotential ﬁle to your working directory. (The unformatted and ASCII

ﬁles are functionally equivalent, but the latter is more transportable and easier to look at, if you so

desire.) The same could be repeated for the pseudopotential for H, but you may as well copy H.psf

from Examples/Vps/ to your h2o working directory.

Now you are ready to run the program:

./siesta < h2o.fdf | tee h2o.out

(If you are running the parallel version you should use some other invocation, such as mpirun -np

2 siesta ..., but we cannot go into that here — see Sec. 2.4).

After a successful run of the program, you should have several ﬁles in your directory including the

following:

• fdf.log (contains all the data used, explicit or chosen by default)

• O.ion and H.ion (complete information about the basis and KB projectors)

• h2o.XV (contains positions and velocities)

• h2o.STRUCT_OUT (contains the ﬁnal cell vectors and positions in “crystallographic” format)

• h2o.DM (contains the density matrix to allow a restart)

• h2o.ANI (contains the coordinates of every MD step, in this case only one)

• h2o.FA (contains the forces on the atoms)

• h2o.EIG (contains the eigenvalues of the Kohn-Sham Hamiltonian)

• h2o.xml (XML marked-up output)

The preﬁx h2o of all these ﬁles is the SystemLabel speciﬁed in the input h2o.fdf ﬁle (see fdf section

below). The standard output of the program, that you have already seen passing on the screen, was

copied to ﬁle h2o.out by the tee command. Have a look at it and refer to the output-explanation

section if necessary. You may also want to look at the fdf.log ﬁle to see all the default values that

siesta has chosen for you, before studying the input-explanation section and start changing them.

Now look at the other data ﬁles in Examples (all with an .fdf suﬃx) choose one and repeat the

process for it.

3.1 Speciﬁc execution options

SIESTA may be executed in diﬀerent forms. The basic execution form is

siesta < RUN.fdf > RUN.out

which uses a pipe statement. SIESTA 4.1 and later does not require one to pipe in the input ﬁle

and the input ﬁle may instead be speciﬁed on the command line.

siesta RUN.fdf > RUN.out

This allows for SIESTA to accept special ﬂags described in what follows. Each ﬂag may be quoted

if it contains spaces, or one may substitute spaces by .

-h print a help instruction and quit

-L Override, temporarily, the SystemLabel ﬂag.

siesta -L Hello.

-out|-o Specify the output ﬁle (instead of printing to the terminal).

siesta -out RUN.out.

-electrode|-elec overwrites: TS.HS.Save, TS.DE.Save

denote this as an electrode calculation which forces the SystemLabel.TSHS and SystemLabel.TSDE

ﬁles to be saved.

NOTE: This is equivalent to specifying TS.HS.Save true and TS.DE.Save true in the input

ﬁle.

-V overwrites: TS.Voltage

specify the bias for the current TranSIESTA run.

siesta -V 0.25:eV or siesta -V "0.25 eV" which sets the applied bias to 0.25 eV.

NOTE: This is equivalent to specifying TS.Voltage in the input ﬁle.

4 THE FLEXIBLE DATA FORMAT (FDF)

The main input ﬁle, which is read as the standard input (unit 5), contains all the physical data of the

system and the parameters of the simulation to be performed. This ﬁle is written in a special format

called FDF, 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 to documentation in ∼/siesta/Src/fdf

for details. Here we oﬀer a glimpse of it through the following rules:

• The fdf syntax is a ’data label’ followed by its value. Values that are not speciﬁed in the

dataﬁle are assigned a default value.

• fdf labels are case insensitive, and characters - _ . in a data label are ignored. Thus,

LatticeConstant and lattice_constant represent the same label.

• All text following the # character is taken as comment.

• Logical values can be speciﬁed as T, true, .true., yes, F, false, .false., no. Blank is also equivalent

to true.

• Character strings should not be in apostrophes.

• Real values which represent a physical magnitude must be followed by its units. Look at

function fdf_convfac in ﬁle ∼/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 distinguish it from an integer,

in order to prevent ambiguities when mixing the types on the same input line.

• Complex data structures are called blocks and are placed between ‘%block label’ and a ‘%end-

block label’ (without the quotes).

• You may ‘include’ other fdf ﬁles and redirect the search for a particular data label to another

ﬁle. If a data label appears more than once, its ﬁrst appearance is used.

• If the same label is speciﬁed twice, the ﬁrst one takes precedence.

• If a label is misspelled it will not be recognized (there is no internal 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 ﬁle.

These are some examples:

SystemName Water molecule # This is a comment

SystemLabel h2o

Spin polarized

SaveRho

NumberOfAtoms 64

LatticeConstant 5.42 Ang

%block LatticeVectors

1.000 0.000 0.000

0.000 1.000 0.000

0.000 0.000 1.000

%endblock LatticeVectors

KgridCutoff < BZ_sampling.fdf

# Reading the coordinates from a file

%block AtomicCoordinatesAndAtomicSpecies < coordinates.data

# Even reading more FDF information from somewhere else

%include mydefaults.fdf

The ﬁle fdf.log contains all the parameters used by SIESTA in a given run, both those speciﬁed in

the input fdf ﬁle and those taken by default. They are written in fdf format, so that you may reuse

them as input directly. Input data blocks are copied to the fdf.log ﬁle only if you specify the dump

option for them.

5 PROGRAM OUTPUT

5.1 Standard output

SIESTA writes a log of its workings to standard output (unit 6), which is usually redirected to an

“output ﬁle”.

A brief description follows. See the example cases in the siesta/Tests directory for illustration.

The program starts writing the version of the code which is used. Then, the input fdf ﬁle is

dumped into the output ﬁle as is (except for empty lines). The program does part of the reading

and digesting of the data at the beginning within the redata subroutine. It prints some of the

information it digests. It is important to note that it is only part of it, some other information being

accessed by the diﬀerent subroutines when they need it during the run (in the spirit of fdf input).

A complete list of the input used by the code can be found at the end in the ﬁle fdf.log, including

defaults used by the code in the run.

After that, the program reads the pseudopotentials, factorizes them into Kleinman-Bylander form,

and generates (or reads) the atomic basis set to be used in the simulation. These stages are docu-

mented in the output ﬁle.

The simulation begins after that, the output showing information of the MD (or CG) steps and the

SCF cycles within. Basic descriptions of the process and results are presented. The user has the

option to customize it, however, by deﬁning diﬀerent options that control the printing of informations

like coordinates, forces,

k points, etc. The options are discussed in the appropriate sections, but

take into account the behavior of the legacy LongOutput option, as in the current implementation

might silently activate output to the main .out ﬁle at the expense of auxiliary ﬁles.

LongOutput false (logical)

SIESTA can write to standard output diﬀerent data sets depending on the values for output

options described below. By default SIESTA will not write most of them. They can be large

for large systems (coordinates, eigenvalues, forces, etc.) and, if written to standard output, they

accumulate for all the steps of the dynamics. SIESTA writes the information in other ﬁles (see

Output Files) in addition to the standard output, and these can be cumulative or not.

Setting LongOutput to true changes the default of some options, obtaining more information

in the output (verbose). In particular, it redeﬁnes the defaults for the following:

• WriteKpoints

• WriteKbands

• WriteCoorStep

• WriteForces

• WriteEigenvalues

• WriteWaveFunctions

• WriteMullikenPop(it sets it to 1)

The speciﬁc changing of any of these options has precedence.

5.2 Output to dedicated ﬁles

SIESTA can produce a wealth of information in dedicated ﬁles, with speciﬁc formats, that can be

used for further analysis. See the appropriate sections, and the appendix on ﬁle formats. Please take

into account the behavior of LongOutput, as in the current implementation might silently activate

output to the main .out ﬁle at the expense of auxiliary ﬁles.

6 DETAILED DESCRIPTION OF PROGRAM OPTIONS

Here follows a description of the variables that you can deﬁne in your SIESTA input ﬁle, with their

data types and default values. For historical reasons the names of the tags do not have an uniform

structure, and can be confusing at times.

Almost all of the tags are optional: SIESTA will assign a default if a given tag is not found when

needed (see fdf.log).

6.1 General system descriptors

SystemLabel siesta (string)

A single word (max. 20 characters without blanks) containing a nickname of the system, used

to name output ﬁles.

SystemName 〈None〉 (string)

A string of one or several words containing a descriptive name of the system (max. 150 charac-

ters).

NumberOfSpecies 〈lines in ChemicalSpeciesLabel〉 (integer)

Number of diﬀerent atomic species in the simulation. Atoms of the same species, but with a

diﬀerent pseudopotential or basis set are counted as diﬀerent species.

NOTE: This is not required to be set.

NumberOfAtoms 〈lines in AtomicCoordinatesAndAtomicSpecies〉 (integer)

Number of atoms in the simulation.

NOTE: This is not required to be set.

%block ChemicalSpeciesLabel 〈None〉 (block)

It speciﬁes the diﬀerent chemical species that are present, assigning them a number for further

identiﬁcation. SIESTA recognizes the diﬀerent atoms by the given atomic number.

%block ChemicalSpecieslabel

1 6 C

2 14 Si

3 14 Si_surface

%endblock ChemicalSpecieslabel

The ﬁrst number in a line is the species number, it is followed by the atomic number, and then by

the desired label. This label will be used to identify corresponding ﬁles, namely, pseudopotential

ﬁle, user basis ﬁle, basis output ﬁle, and local pseudopotential output ﬁle.

This construction allows you to have atoms of the same species but with diﬀerent basis or

pseudopotential, for example.

Negative atomic numbers are used for ghost atoms (see PAO.Basis).

For atomic numbers over 200 or below −200 you should read SyntheticAtoms.

NOTE: This block is mandatory.

%block SyntheticAtoms 〈None〉 (block)

This block is an additional block to complement ChemicalSpeciesLabel for special atomic

numbers.

Atomic numbers over 200 are used to represent synthetic atoms (created for example as a

“mixture” of two real ones for a “virtual crystal” (VCA) calculation). In this special case a

new SyntheticAtoms block must be present to give SIESTA information about the “ground

state” of the synthetic atom.

%block ChemicalSpeciesLabel

1 201 ON-0.50000

%endblock ChemicalSpeciesLabel

%block SyntheticAtoms

1 # Species index

2 2 3 4 # n numbers for valence states with l=0,1,2,3

2.0 3.5 0.0 0.0 # occupations of valence states with l=0,1,2,3

%endblock SyntheticAtoms

Pseudopotentials for synthetic atoms can be created using the mixps and fractional programs

in the Util/VCA directory.

Atomic numbers below −200 represent ghost synthetic atoms.

%block AtomicMass 〈None〉 (block)

It allows the user to introduce the atomic masses of the diﬀerent species used in the calculation,

useful for the dynamics with isotopes, for example. If a species index is not found within the

block, the natural mass for the corresponding atomic number is assumed. If the block is absent

all masses are the natural ones. One line per species with the species index (integer) and the

desired mass (real). The order is not important. If there is no integer and/or no real numbers

within the line, the line is disregarded.

%block AtomicMass

3 21.5

1 3.2

%endblock AtomicMass

The default atomic mass are the natural masses. For ghost atoms (i.e. ﬂoating orbitals) the

mass is 10

a.u.

6.2 Pseudopotentials

SIESTA uses pseudopotentials to represent the electron-ion interaction (as do most plane-wave codes

and in contrast to so-called “all-electron” programs). In particular, the pseudopotentials are of the

“norm-conserving” kind, and can be generated by the Atom program, (see Pseudo/README.ATOM).

Remember that all pseudopotentials should be thoroughly tested before using them. We refer

you to the standard literature on pseudopotentials and to the ATOM manual for more information. A

number of other codes (such as APE) can generate pseudopotentials that SIESTA can use directly

(typically in the .psf format).

The pseudopotentials will be read by SIESTA from diﬀerent ﬁles, one for each deﬁned species

(species deﬁned either in block ChemicalSpeciesLabel). The name of the ﬁles should be:

Chemical_label.vps (unformatted) or Chemical_label.psf (ASCII)

where Chemical_label corresponds to the label deﬁned in the ChemicalSpeciesLabel block.

6.3 Basis set and KB projectors

6.3.1 Overview of atomic-orbital bases implemented in SIESTA

The main advantage of atomic orbitals is their eﬃciency (fewer orbitals needed per electron for

similar precision) and their main disadvantage is the lack of systematics for optimal convergence, an

issue that quantum chemists have been working on for many years. They have also clearly shown

that there is no limitation on precision intrinsic to LCAO. This section provides some information

about how basis sets can be generated for SIESTA.

It is important to stress at this point that neither the SIESTA method nor the program are bound

to the use of any particular kind of atomic orbitals. The user can feed into SIESTA the atomic basis

set he/she choses by 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 ﬁnite support, i.e., each orbital becomes strictly zero beyond some cutoﬀ radius

chosen by the user.

Most users, however, do not have their own basis sets. For these users we have devised some schemes

to generate basis sets within the program with a minimum input from the user. If nothing is speciﬁed

in the input ﬁle, Siesta generates a default basis set of a reasonable quality that might constitute

a good starting point. Of course, depending on the accuracy required in the particular problem,

the user has the degree of freedom to tune several parameters that can be important for quality

and eﬃciency. A description of these basis sets and some performance tests can be found in the

references quoted below.

“Numerical atomic orbitals for linear-scaling calculations”, J. Junquera, O. Paz, D. Sánchez-Portal,

and E. Artacho, Phys. Rev. B 64, 235111, (2001)

An important point here is that the basis set selection is a variational problem and, therefore,

minimizing the energy with respect to any parameters deﬁning the basis is an “ab initio” way to

deﬁne them.

We have also devised a quite simple and systematic way of generating basis sets based on specifying

only one main parameter (the energy shift) besides the basis size. It does not oﬀer the best NAO

results one can get for a given basis size but it has the important advantages mentioned above. More

about it in:

“Linear-scaling ab-initio calculations for large and complex systems”, E. Artacho, D. Sánchez-Portal,

P. Ordejón, A. García and J. M. Soler, Phys. Stat. Sol. (b) 215, 809 (1999).

In addition to SIESTA we provide the program Gen-basis , which reads SIESTA’s input and

generates basis ﬁles for later use. Gen-basis can be found in Util/Gen-basis. It should be run

from the Tutorials/Bases directory, using the gen-basis.sh script. It is limited to a single species.

Of course, as it happens for the pseudopotential, it is the responsibility of the user to check that

the physical results obtained are converged with respect to the basis set used before starting any

production run.

In the following we give some clues on the basics of the basis sets that SIESTA generates. The

starting point is always the solution of Kohn-Sham’s Hamiltonian for the isolated pseudo-atoms,

solved in a radial grid, with the same approximations as for the solid or molecule (the same exchange-

correlation functional and pseudopotential), plus some way of conﬁnement (see below). We describe

in the following three main features of a basis set of atomic orbitals: size, range, and radial shape.

Size: number of orbitals per atom

Following the nomenclature of Quantum Chemistry, we establish a hierarchy of basis sets, from

single-ζ to multiple-ζ with polarization and diﬀuse orbitals, covering from quick calculations of low

quality to high precision, as high as the ﬁnest obtained in Quantum Chemistry. A single-ζ (also

called minimal) basis set (SZ in the following) has one single radial function per angular momentum

channel, and only for those angular momenta with substantial electronic population in the valence

of the free atom. It oﬀers quick calculations and some insight on qualitative trends in the chemical

bonding and other properties. It remains too rigid, however, for more quantitative calculations

requiring both radial and angular ﬂexibilization.

Starting by the radial ﬂexibilization of SZ, a better basis is obtained by adding a second function per

channel: double-ζ (DZ). In Quantum Chemistry, the split valence scheme is widely used: starting

from the expansion in Gaussians of one atomic orbital, the most contracted Gaussians are used

to deﬁne the ﬁrst orbital of the double-ζ and the most extended ones for the second. For strictly

localized functions there was a ﬁrst proposal of using the excited states of the conﬁned atoms, but it

would work only for tight conﬁnement (see PAO.BasisType nodes below). This construction was

proposed and tested in D. Sánchez-Portal et al., J. Phys.: Condens. Matter 8, 3859-3880 (1996).

We found that the basis set convergence is slow, requiring high levels of multiple-ζ to achieve what

other schemes do at the double-ζ level. This scheme is related with the basis sets used in the

OpenMX project [see T. Ozaki, Phys. Rev. B 67, 155108 (2003); T. Ozaki and H. Kino, Phys. Rev.

B 69, 195113 (2004)].

We then proposed an extension of the split valence idea of Quantum Chemistry to strictly localized

NAO which has become the standard and has been used quite successfully in many systems (see

PAO.BasisType split below). It is based on the idea of suplementing the ﬁrst ζ with, instead of a

gaussian, a numerical orbital that reproduces the tail of the original PAO outside a matching radius

, and continues smoothly towards the origin as r

(a − br

), with a and b ensuring continuity and

diﬀerentiability at r

. Within exactly the same Hilbert space, the second orbital can be chosen to

be the diﬀerence between the smooth one and the original PAO, which gives a basis orbital strictly

conﬁned within the matching radius r

(smaller than the original PAO!) continuously diﬀerentiable

throughout.

Extra parameters have thus appeared: one r

per orbital to be doubled. The user can again

introduce them by hand (see PAO.Basis below). Alternatively, all the r

’s can be deﬁned at

once by specifying the value of the tail of the original PAO beyond r

, the so-called split norm.

Variational optimization of this split norm performed on diﬀerent systems shows a very general and

stable performance for values around 15% (except for the ∼ 50% for hydrogen). It generalizes to

multiple-ζ trivially by adding an additional matching radius per new zeta.

Note: What is actually used is the norm of the tail plus the norm of the parabola-like inner function.

Angular ﬂexibility is obtained by adding shells of higher angular momentum. Ways to generate these

so-called polarization orbitals have been described in the literature for Gaussians. For NAOs there

are two ways for SIESTA and Gen-basis to generate them: (i) Use atomic PAO’s of higher angular

momentum with suitable conﬁnement, and (ii) solve the pseudoatom in the presence of an electric

ﬁeld and obtain the l + 1 orbitals from the perturbation of the l orbitals by the ﬁeld. Experience

shows that method (i) tends to give better results.

So-called diﬀuse orbitals, that might be important in the description of open systems such as surfaces,

can be simply added by specifying extra “n” shells. [See S. Garcia-Gil, A. Garcia, N. Lorente, P.

Ordejon, Phys. Rev. B 79, 075441 (2009)]

Finally, the method allows the inclusion of oﬀ-site (ghost) orbitals (not centered around any speciﬁc

atom), useful for example in the calculation of the counterpoise correction for basis-set superposition

errors. Bessel functions for any radius and any excitation level can also be added anywhere to the

basis set.

Range: cutoﬀ radii of orbitals.

Strictly localized orbitals (zero beyond a cutoﬀ radius) are used in order to obtain sparse Hamiltonian

and overlap matrices for linear scaling. One cutoﬀ radius per angular momentum channel has to be

given for each species.

A balanced and systematic starting point for deﬁning all the diﬀerent radii is achieved by giving one

single parameter, the energy shift, i.e., the energy increase experienced by the orbital when conﬁned.

Allowing for system and physical-quantity variablity, as a rule of thumb ∆E

PAO

≈ 100 meV gives

typical precisions within the accuracy of current GGA functionals. The user can, nevertheless,

change the cutoﬀ radii at will.

Shape

Within the pseudopotential framework it is important to keep the consistency between the pseu-

dopotential and the form of the pseudoatomic orbitals in the core region. The shape of the orbitals

at larger radii depends on the cutoﬀ radius (see above) and on the way the localization is enforced.

The ﬁrst proposal (and quite a standard among SIESTA users) uses an inﬁnite square-well potential.

It was originally proposed and has been widely and successfully used by Otto Sankey and collabora-

tors, for minimal bases within the ab initio tight-binding scheme, using the Fireball program, but

also for more ﬂexible bases using the methodology of SIESTA. This scheme has the disadavantage,

however, of generating orbitals with a discontinuous derivative at r

. This discontinuity is more

pronounced for smaller r

’s and tends to disappear for long enough values of this cutoﬀ. It does

remain, however, appreciable for sensible values of r

for those orbitals that would be very wide

in the free atom. It is surprising how small an eﬀect such a kink produces in the total energy of

condensed systems. It is, on the other hand, a problem for forces and stresses, especially if they are

calculated using a (coarse) ﬁnite three-dimensional grid.

Another problem of this scheme is related to its deﬁning the basis starting from the free atoms.

Free atoms can present extremely extended orbitals, their extension being, besides problematic, of

no practical use for the calculation in condensed systems: the electrons far away from the atom can

be described by the basis functions of other atoms.

A traditional scheme to deal with this is one based on the radial scaling of the orbitals by suitable

scale factors. In addition to very basic bonding arguments, it is soundly based on restoring the

virial’s theorem for ﬁnite bases, in the case of Coulombic potentials (all-electron calculations). The

use of pseudopotentials limits its applicability, allowing only for extremely small deviations from

unity (∼ 1%) in the scale factors obtained variationally (with the exception of hydrogen that can

contract up to 25%). This possiblity is available to the user.

Another way of dealing with the above problem and that of the kink at the same time is adding a soft

conﬁnement potential to the atomic Hamiltonian used to generate the basis orbitals: it smoothens

the kink and contracts the orbital as suited. Two additional parameters are introduced for the

purpose, which can be deﬁned again variationally. The conﬁning potential is ﬂat (zero) in the core

region, starts oﬀ at some internal radius r

with all derivatives continuous and diverges at r

ensuring

the strict localization there. It is

V (r) = V

−

−r

r−r

− r

(1)

and both r

and V

can be given to SIESTA together with r

in the input (see PAO.Basis be-

low). The kink is normally well smoothened with the default values for soft conﬁnement by default

(PAO.SoftDefault true), which are r

= 0.9r

and V

= 40 Ry.

When explicitly introducing orbitals in the basis that would be empty in the atom (e.g. polarisation

orbitals) these tend to be extremely extended if not completely unbound. The above procedure

produces orbitals that bulge as far away from the nucleus as possible, to plunge abruptly at r

. Soft

conﬁnement can be used to try to force a more reasonable shape, but it is not ideal (for orbitals

peaking in the right region the tails tend to be far too short). Charge conﬁnement produces very

good shapes for empty orbitals. Essentially a Z/r potential is added to the soft conﬁned potential

above. For ﬂexibility the charge conﬁnement option in SIESTA is deﬁned as

(r) =

−λr

√

+ δ

(2)

where δ is there to avoid the singularity (default δ = 0.01 Bohr), and λ allows to screen the potential

if longer tails are needed. The description on how to introduce this option can be found in the

PAO.Basis entry below.

Finally, the shape of an orbital is also changed by the ionic character of the atom. Orbitals in

cations tend to shrink, and they swell in anions. Introducing a δQ in the basis-generating free-atom

calculations gives orbitals better adapted to ionic situations in the condensed systems.

More information about basis sets can be found in the proposed literature.

There are quite a number of options for the input of the basis-set and KB projector speciﬁcation, and

they are all optional! By default, SIESTA will use a DZP basis set with appropriate choices for the

determination of the range, etc. Of course, the more you experiment with the diﬀerent options, the

better your basis set can get. To aid in this process we oﬀer an auxiliary program for optimization

which can be used in particular to obtain variationally optimal basis sets (within a chosen basis

size). See Util/Optimizer for general information, and Util/Optimizer/Examples/Basis_Optim

for an example. The directory Tutorials/Bases in the main SIESTA distribution contains some

tutorial material for the generation of basis sets and KB projectors.

Finally, some optimized basis sets for particular elements are available at the SIESTA web page.

Again, it is the responsability of the users to test the transferability of the basis set to their problem

under consideration.

6.3.2 Type of basis sets

PAO.BasisType split (string)

The kind of basis to be generated is chosen. All are based on ﬁnite-range pseudo-atomic orbitals

[PAO’s of Sankey and Niklewsky, PRB 40, 3979 (1989)]. The original PAO’s were described

only for minimal bases. SIESTA generates extended bases (multiple-ζ, polarization, and diﬀuse

orbitals) applying diﬀerent schemes of choice:

- Generalization of the PAO’s: uses the excited orbitals of the ﬁnite-range pseudo-atomic

problem, both for multiple-ζ and for polarization [see Sánchez-Portal, Artacho, and Soler,

JPCM 8, 3859 (1996)]. Adequate for short-range orbitals.

- Multiple-ζ in the spirit of split valence, decomposing the original PAO in several pieces of

diﬀerent range, either deﬁning more (and smaller) conﬁning radii, or introducing Gaussians

from known bases (Huzinaga’s book).

All the remaining options give the same minimal basis. The diﬀerent options and their fdf

descriptors are the following:

split Split-valence scheme for multiple-zeta. The split is based on diﬀerent radii.

splitgauss Same as split but using gaussian functions e

−(x/α

)

. The gaussian widths α

are

read instead of the scale factors (see below). There is no cutting algorithm, so that a large

enough r

should be deﬁned for the gaussian to have decayed suﬃciently.

nodes Generalized PAO’s.

nonodes The original PAO’s are used, multiple-zeta is generated by changing the scale-factors,

instead of using the excited orbitals.

ﬁlteret Use the ﬁlterets as a systematic basis set. The size of the basis set is controlled by the

ﬁlter cut-oﬀ for the orbitals.

Note that, for the split and nodes cases the whole basis can be generated by SIESTA with

no further information required. SIESTA will use default values as deﬁned in the following

(PAO.BasisSize, PAO.EnergyShift, and PAO.SplitNorm, see below).

6.3.3 Size of the basis set

PAO.BasisSize DZP (string)

It deﬁnes usual basis sizes. It has eﬀect only if there is no block PAO.Basis present.

SZ|minimal Use single-ζ basis.

DZ Double zeta basis, in the scheme deﬁned by PAO.BasisType.

SZP Single-zeta basis plus polarization orbitals.

DZP|standard Like DZ plus polarization orbitals. Polarization orbitals are constructed from

perturbation theory, and they are deﬁned so they have the minimum angular momentum l

such that there are not occupied orbitals with the same l in the valence shell of the ground-

state atomic conﬁguration. They polarize the corresponding l − 1 shell.

NOTE: The ground-state atomic conﬁguration used internally by SIESTA is deﬁned in the

source ﬁle Src/periodic_table.f. For some elements (e.g., Pd), the conﬁguration might

not be the standard one.

%block PAO.BasisSizes 〈None〉 (block)

Block which allows to specify a diﬀerent value of the variable PAO.BasisSize for each species.

For example,

%block PAO.BasisSizes

Si DZ

H DZP

O SZP

%endblock PAO.BasisSizes

6.3.4 Range of the orbitals

PAO.EnergyShift 0.02 Ry (energy)

A standard for orbital-conﬁning cutoﬀ radii. It is the excitation energy of the PAO’s due to

the conﬁnement to a ﬁnite-range. It oﬀers a general procedure for deﬁning the conﬁning radii

of the original (ﬁrst-zeta) PAO’s for all the species guaranteeing the compensation of the basis.

It only has an eﬀect when the block PAO.Basis is not present or when the radii speciﬁed in

that block are zero for the ﬁrst zeta.

Write.Graphviz none|atom|orbital|atom+orbital (string)

Write out the sparsity pattern after having determined the basis size overlaps. This will generate

SystemLabel.ATOM.gv or SystemLabel.ORB.gv which both may be converted to a graph using

Graphviz’s program neato:

neato -x -Tpng siesta.ATOM.gv -o siesta_ATOM.png

The resulting graph will list each atom as i(j) where i is the atomic index and j is the number

of other atoms it is connected to.

6.3.5 Generation of multiple-zeta orbitals

PAO.SplitNorm 0.15 (real)

A standard to deﬁne sensible default radii for the split-valence type of basis. It gives the amount

of norm that the second-ζ split-oﬀ piece has to carry. The split radius is deﬁned accordingly.

If multiple-ζ is used, the corresponding radii are obtained by imposing smaller fractions of the

SplitNorm (1/2, 1/4 ...) value as norm carried by the higher zetas. It only has an eﬀect when

the block PAO.Basis is not present or when the radii speciﬁed in that block are zero for zetas

higher than one.

PAO.SplitNormH 〈PAO.SplitNorm〉 (real)

This option is as per PAO.SplitNorm but allows a separate default to be speciﬁed for hydrogen

which typically needs larger values than those for other elements.

PAO.NewSplitCode false (logical)

Enables a new, simpler way to match the multiple-zeta radii.

If an old-style (tail+parabola) calculation is being done, perform a scan of the tail+parabola

norm in the whole range of the 1st-zeta orbital, and store that in a table. The construction of

the 2nd-zeta orbital involves simply scanning the table to ﬁnd the appropriate place. Due to

the idiosyncracies of the old algorithm, the new one is not guaranteed to produce exactly the

same results, as it might settle on a neighboring grid point for the matching.

PAO.FixSplitTable false (logical)

After the scan of the allowable split-norm values, apply a damping function to the tail to make

sure that the table goes to zero at the radius of the ﬁrst-zeta orbital.

PAO.SplitTailNorm false (logical)

Use the norm of the tail instead of the full tail+parabola norm. This is the behavior described

in the JPC paper. (But note that, for numerical reasons, the square root of the tail norm is

used in the algorithm.) This is the preferred mode of operation for automatic operation, as in

non-supervised basis-optimization runs.

As a summary of the above options:

• For complete backwards compatibility, do nothing.

• To exercise the new code, set PAO.NewSplitCode.

• To maintain the old split-norm heuristic, but making sure that the program ﬁnds a solution

(even if not optimal, in the sense of producing a second-ζ r

very close to the ﬁrst-ζ one), set

PAO.FixSplitTable (this will automatically set PAO.NewSplitCode).

• If the old heuristic is of no interest (for example, if only a robust way of mapping split-norms to

radii is needed), set PAO.SplitTailNorm (this will set PAO.NewSplitCode automatically).

PAO.EnergyCutoﬀ 20 Ry (energy)

If the multiple zetas are generated using ﬁlterets then only the ﬁlterets with an energy lower

than this cutoﬀ are included. Increasing this value leads to a richer basis set (provided the

cutoﬀ is raised above the energy of any ﬁlteret that was previously not included) but a more

expensive calculation. It only has an eﬀect when the option PAO.BasisType is set to ﬁlteret.

PAO.EnergyPolCutoﬀ 20 Ry (energy)

If the multiple zetas are generated using ﬁlterets then only the ﬁlterets with an energy lower

than this cutoﬀ are included for the polarisation functions. Increasing this value leads to a

richer basis set (provided the cutoﬀ is raised above the energy of any ﬁlteret that was previ-

ously not included) but a more expensive calculation. It only has an eﬀect when the option

PAO.BasisType is set to ﬁlteret.

PAO.ContractionCutoﬀ 0|0 − 1 (real)

If the multiple zetas are generated using ﬁlterets then any ﬁlterets that have a coeﬃcient less

than this threshold within the original PAO will be contracted together to form a single ﬁlteret.

Increasing this value leads to a smaller basis set but allows the underlying basis to have a higher

kinetic energy cut-oﬀ for ﬁltering. It only has an eﬀect when the option PAO.BasisType is

set to ﬁlteret.

6.3.6 Soft-conﬁnement options

PAO.SoftDefault false (logical)

If set to true then this option causes soft conﬁnement to be the default form of potential during

orbital generation. The default potential and inner radius are set by the commands given below.

PAO.SoftInnerRadius 0.9 (real)

For default soft conﬁnement, the inner radius is set at a fraction of the outer conﬁnement radius

determined by the energy shift. This option controls the fraction of the conﬁnement radius to

be used.

PAO.SoftPotential 40 Ry (energy)

For default soft conﬁnement, this option controls the value of the potential used for all orbitals.

NOTE: Soft-conﬁnement options (inner radius, prefactor) have been traditionally used to op-

timize the basis set, even though formally they are just a technical necessity to soften the decay

of the orbitals at rc. To achieve this, it might be enough to use the above global options.

6.3.7 Kleinman-Bylander projectors

%block PS.lmax 〈None〉 (block)

Block with the maximum angular momentum of the Kleinman-Bylander projectors, lmxkb. This

information is optional. If the block is absent, or for a species which is not mentioned inside

it, SIESTA will take lmxkb(is) = lmxo(is) + 1, where lmxo(is) is the maximum angular

momentum of the basis orbitals of species is. However, the value of lmxkb is actually limited

by the highest-l channel in the pseudopotential ﬁle.

%block Ps.lmax

Al_adatom 3

H 1

O 2

%endblock Ps.lmax

By default lmax is the maximum angular momentum plus one, limited by the highest-l channel

in the pseudopotential ﬁle.

%block PS.KBprojectors 〈None〉 (block)

This block provides information about the number of Kleinman-Bylander projectors per angular

momentum, and for each species, that will used in the calculation. This block is optional. If

the block is absent, or for species not mentioned in it, only one projector will be used for

each angular momentum (except for l-shells with semicore states, for which two projectors will

be constructed). The projectors will be constructed using the eigenfunctions of the respective

pseudopotentials.

This block allows to specify the number of projector for each l, and also the reference energies of

the wavefunctions used to build them. The speciﬁcation of the reference energies is optional. If

these energies are not given, the program will use the eigenfunctions with an increasing number

of nodes (if there is not bound state with the corresponding number of nodes, the “eigenstates”

are taken to be just functions which are made zero at very long distance of the nucleus). The

units for the energy can be optionally speciﬁed; if not, the program will assumed that they are

given in Rydbergs. The data provided in this block must be consistent with those read from

the block PS.lmax. For example,

%block PS.KBprojectors

Si 3

2 1

-0.9 eV

0 2

-0.5 -1.0d4 Hartree

1 2

Ga 1

1 3

-1.0 1.0d5 -6.0

%endblock PS.KBprojectors

The reading is done this way (those variables in brackets are optional, therefore they are only

read if present):

From is = 1 to nspecies

read: label(is), l_shells(is)

From lsh=1 to l_shells(is)

read: l, nkbl(l,is)

read: {erefKB(izeta,il,is)}, from ikb = 1 to nkbl(l,is), {units}

All angular momentum shells should be speciﬁed. Default values are assigned to missing shells

with l below lmax, where lmax is the highest angular momentum present in the block for that

particular species. High-l shells (beyond lmax) not speciﬁed in the block will also be assigned

default values.

Care should be taken for l-shells with semicore states. For them, two KB projectors should be

generated. This is not checked while processing this block.

When a very high energy, higher that 1000 Ry, is speciﬁed, the default is taken instead. On

the other hand, very low (negative) energies, lower than -1000 Ry, are used to indicate that

the energy derivative of the last state must be used. For example, in the block given above,

two projectors will be used for the s pseudopotential of Si. One generated using a reference

energy of -0.5 Hartree, and the second one using the energy derivative of this state. For the p

pseudopotential of Ga, three projectors will be used. The second one will be constructed from

an automatically generated wavefunction with one node, and the other projectors from states

at -1.0 and -6.0 Rydberg.

The analysis looking for possible ghost states is only performed when a single projector is used.

Using several projectors some attention should be paid to the “KB cosine” (kbcos), given in the

output of the program. The KB cosine gives the value of the overlap between the reference state

and the projector generated from it. If these numbers are very small ( < 0.01, for example) for

all the projectors of some angular momentum, one can have problems related with the presence

of ghost states.

The default is one KB projector from each angular momentum, constructed from the nodeless

eigenfunction, used for each angular momentum, except for l-shells with semicore states, for

which two projectors will be constructed. Note that the value of lmxkb is actually limited by

the highest-l channel in the pseudopotential ﬁle.

KB.New.Reference.Orbitals false (logical)

If true, the routine to generate KB projectors will use slightly diﬀerent parameters for the

construction of the reference orbitals involved (Rmax=60 Bohr both for integration and nor-

malization).

6.3.8 The PAO.Basis block

%block PAO.Basis 〈None〉 (block)

Block with data to deﬁne explicitly the basis to be used. It allows the deﬁnition by hand

of all the parameters that are used to construct the atomic basis. There is no need to enter

information for all the species present in the calculation. The basis for the species not men-

tioned in this block will be generated automatically using the parameters PAO.BasisSize,

PAO.BasisType, PAO.EnergyShift, PAO.SplitNorm (or PAO.SplitNormH), and the

soft-conﬁnement defaults, if used (see PAO.SoftDefault).

Some parameters can be set to zero, or left out completely. In these cases the values will

be generated from the magnitudes deﬁned above, or from the appropriate default values. For

example, the radii will be obtained from PAO.EnergyShift or from PAO.SplitNorm if they

are zero; the scale factors will be put to 1 if they are zero or not given in the input. An example

block for a two-species calculation (H and O) is the following (opt means optional):

%block PAO.Basis # Define Basis set

O 2 nodes 1.0 # Label, l_shells, type (opt), ionic_charge (opt)

n=2 0 2 E 50.0 2.5 # n (opt if not using semicore levels),l,Nzeta,Softconf(opt)

3.50 3.50 # rc(izeta=1,Nzeta)(Bohr)

0.95 1.00 # scaleFactor(izeta=1,Nzeta) (opt)

1 1 P 2 # l, Nzeta, PolOrb (opt), NzetaPol (opt)

3.50 # rc(izeta=1,Nzeta)(Bohr)

H 2 # Label, l_shells, type (opt), ionic_charge (opt)

0 2 S 0.2 # l, Nzeta, Per-shell split norm parameter

5.00 0.00 # rc(izeta=1,Nzeta)(Bohr)

1 1 Q 3. 0.2 # l, Nzeta, Charge conf (opt): Z and screening

5.00 # rc(izeta=1,Nzeta)(Bohr)

%endblock PAO.Basis

The reading is done this way (those variables in brackets are optional, therefore they are only

read if present) (See the routines in Src/basis_specs.f for detailed information):

From js = 1 to nspecies

read: label(is), l_shells(is), { type(is) }, { ionic_charge(is) }

From lsh=1 to l_shells(is)

read:

{ n }, l(lsh), nzls(lsh,is), { PolOrb(l+1) }, { NzetaPol(l+1) },

{SplitNormfFlag(lsh,is)}, {SplitNormValue(lsh,is)}

{SoftConfFlag(lsh,is)}, {PrefactorSoft(lsh,is)}, {InnerRadSoft(lsh,is)},

{FilteretFlag(lsh,is)}, {FilteretCutoff(lsh,is)}

{ChargeConfFlag(lsh,is)}, {Z(lsh,is)}, {Screen(lsh,is)}, {delta(lsh,is}

read: rcls(izeta,lsh,is), from izeta = 1 to nzls(l,is)

read: { contrf(izeta,il,is) }, from izeta = 1 to nzls(l,is)

And here is the variable description:

- Label: Species label, this label determines the species index is according to the block

ChemicalSpeciesLabel

- l_shells(is): Number of shells of orbitals with diﬀerent angular momentum for species

- type(is): Optional input. Kind of basis set generation procedure for species is. Same

options as PAO.BasisType

- ionic_charge(is): Optional input. Net charge of species is. This is only used for basis set

generation purposes. Default value: 0.0 (neutral atom). Note that if the pseudopotential

was generated in an ionic conﬁguration, and no charge is speciﬁed in PAO.Basis, the ionic

charge setting will be that of pseudopotential generation.

- n: Principal quantum number of the shell. This is an optional input for normal atoms,

however it must be speciﬁed when there are semicore states (i.e. when states that usually

are not considered to belong to the valence shell have been included in the calculation)

- l: Angular momentum of basis orbitals of this shell

- nzls(lsh,is): Number of “zetas” for this shell. For a ﬁlteret basis this number is ignored

since the number is controlled by the cutoﬀ. For bessel-ﬂoating orbitals, the diﬀerent ’zetas’

map to increasingly excited states with the same angular momentum (with increasing

number of nodes).

- PolOrb(l+1): Optional input. If set equal to P, a shell of polarization functions (with an-

gular momentum l+1) will be constructed from the ﬁrst-zeta orbital of angular momentum

l. Default value: ’ ’ (blank = No polarization orbitals).

- NzetaPol(l+1): Optional input. Number of “zetas” for the polarization shell (generated

automatically in a split-valence fashion). For a ﬁlteret basis this number is ignored since

the number is controlled by the cutoﬀ. Only active if PolOrb = P. Default value: 1

- SplitNormFlag(lsh,is): Optional input. If set equal to S, the following number sets the

split-norm parameter for that shell.

- SoftConfFlag(l,is): Optional input. If set equal to E, the soft conﬁnement potential

proposed in equation (1) of the paper by J. Junquera et al., Phys. Rev. B 64, 235111

(2001), is used instead of the Sankey hard-well potential.

- PrefactorSoft(l,is): Optional input. Prefactor of the soft conﬁnement potential (V

the formula). Units in Ry. Default value: 0 Ry.

- InnerRadSoft(l,is): Optional input. Inner radius where the soft conﬁnement potential

starts oﬀ (r

in the formula). If negative, the inner radius will be computed as the given

fraction of the PAO cutoﬀ radius. Units in bohrs. Default value: 0 bohrs.

- FilteretFlag(l,is): Optional input. If set equal to F, then an individual ﬁlter cut-oﬀ

can be speciﬁed for the shell.

- FilteretCutoff(l,is): Optional input. Shell-speciﬁc value for the ﬁlteret basis cutoﬀ.

Units in Ry. Default value: The same as the value given by FilterCutoﬀ.

- ChargeConfFlag(lsh,is): Optional input. If set equal to Q, the charge conﬁnement po-

tential in equation (2) above is added to the conﬁning potential. If present it requires at

least one number after it (Z), but it can be followed by two or three numbers.

- Z(lhs,is): Optional input, needed if Q is set. Z charge in equation (2) above for charge

conﬁnement (units of e).

- Screen(lhs,is): Optional input. Yukawa screening parameter λ in equation (2) above

for charge conﬁnement (in Bohr

−1

- delta(lhs,is): Optional input. Singularity regularisation parameter δ in equation (2)

above for charge conﬁnement (in Bohr).

- rcls(izeta,l,is): Cutoﬀ 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 ﬁrst

zeta’s rc. If the number of rc’s for a given shell is less than the number of ’zetas’, the

program will assign the last rc value to the remaining zetas, rather than stopping with an

error. This is particularly useful for Bessel suites of orbitals.

- contrf(izeta,l,is): Optional input. Contraction factor of each “zeta” for this shell.

If the number of entries for a given shell is less than the number of ’zetas’, the program

will assign the last contraction value to the remaining zetas, rather than stopping with an

error. Default value: 1.0

Polarization orbitals are generated by solving the atomic problem in the presence of a polarizing

electric ﬁeld. The orbitals are generated applying perturbation theory to the ﬁrst-zeta orbital

of lower angular momentum. They have the same cutoﬀ radius as the orbitals from which they

are constructed.

Note: The perturbative method has traditionally used the ’l’ component of the pseudopotential.

It can be argued that it should use the ’l+1’ component. By default, for backwards compatibility,

the traditional method is used, but the alternative one can be activated by setting the logical

PAO.OldStylePolOrbs variable to false.

There is a diﬀerent possibility for generating polarization orbitals: by introducing them ex-

plicitly in the PAO.Basis block. It has to be remembered, however, that they sometimes

correspond to unbound states of the atom, their shape depending very much on the cutoﬀ ra-

dius, not converging by increasing it, similarly to the multiple-zeta orbitals generated with the

nodes option. Using PAO.EnergyShift makes no sense, and a cut oﬀ radius diﬀerent from

zero must be explicitly given (the same cutoﬀ radius as the orbitals they polarize is usually a

sensible choice).

A species with atomic number = -100 will be considered by SIESTA as a constant-

pseudopotential atom, i.e., the basis functions generated will be spherical Bessel functions with

the speciﬁed r

. In this case, r

has to be given, as PAO.EnergyShift will not calculate it.

Other negative atomic numbers will be interpreted by SIESTA as ghosts of the corresponding

positive value: the orbitals are generated and put in position as determined by the coordinates,

but neither pseudopotential nor electrons are considered for that ghost atom. Useful for BSSE

correction.

Use: This block is optional, except when Bessel functions or semicore states are present.

Default: Basis characteristics deﬁned by global deﬁnitions given above.

6.3.9 Filtering

FilterCutoﬀ 0 eV (energy)

Kinetic energy cutoﬀ of plane waves used to ﬁlter all the atomic basis functions, the pseudo-

core densities for partial core corrections, and the neutral-atom potentials. The basis functions

(which must be squared to obtain the valence density) are really ﬁltered with a cutoﬀ reduced

by an empirical factor 0.7

' 0.5. The FilterCutoﬀ should be similar or lower than the

Mesh.Cutoﬀ to avoid the eggbox eﬀect on the atomic forces. However, one should not try to

converge Mesh.Cutoﬀ while simultaneously changing FilterCutoﬀ, since the latter in fact

changes the used basis functions. Rather, ﬁx a suﬃciently large FilterCutoﬀ and converge

only Mesh.Cutoﬀ. If FilterCutoﬀ is not explicitly set, its value is calculated from FilterTol.

FilterTol 0 eV (energy)

Residual kinetic-energy leaked by ﬁltering each basis function. While FilterCutoﬀ sets a

common reciprocal-space cutoﬀ for all the basis functions, FilterTol sets a speciﬁc cutoﬀ for

each basis function, much as the PAO.EnergyShift sets their real-space cutoﬀ. Therefore,

it is reasonable to use similar values for both parameters. The maximum cutoﬀ required to

meet the FilterTol, among all the basis functions, is used (multiplied by the empirical factor

1/0.7

' 2) to ﬁlter the pseudo-core densities and the neutral-atom potentials. FilterTol is

ignored if FilterCutoﬀ is present in the input ﬁle. If neither FilterCutoﬀ nor FilterTol

are present, no ﬁltering is performed. See Soler and Anglada

[15]

, for details of the ﬁltering

procedure.

Warning: If the value of FilterCutoﬀ is made too small (or FilterTol too large) some of the

ﬁltered basis orbitals may be meaningless, leading to incorrect results or even a program crash.

To be implemented: If Mesh.Cutoﬀ is not present in the input ﬁle, it can be set using

the maximum ﬁltering cutoﬀ used for the given FilterTol (for the time being, you can use

AtomSetupOnly true to stop the program after basis generation, look at the maximum

ﬁltering cutoﬀ used, and set the mesh-cutoﬀ manually in a later run.)

6.3.10 Saving and reading basis-set information

SIESTA (and the standalone program Gen-basis) always generate the ﬁles Atomlabel.ion, where

Atomlabel is the atomic label speciﬁed in block ChemicalSpeciesLabel. Optionally, if NetCDF

support is compiled in, the programs generate NetCDF ﬁles Atomlabel.ion.nc (except for ghost

atoms). See an Appendix for information on the optional NetCDF package.

These ﬁles can be used to read back information into SIESTA.

User.Basis false (logical)

If true, the basis, KB projector, and other information is read from ﬁles Atomlabel.ion, where

Atomlabel is the atomic species label speciﬁed in block ChemicalSpeciesLabel. These ﬁles can

be generated by a previous SIESTA run or (one by one) by the standalone program Gen-basis.

No pseudopotential ﬁles are necessary.

User.Basis.NetCDF false (logical)

If true, the basis, KB projector, and other information is read from NetCDF ﬁles Atom-

label.ion.nc, where Atomlabel is the atomic label speciﬁed in block ChemicalSpeciesLa-

bel. These ﬁles can be generated by a previous SIESTA run or by the standalone program

Gen-basis. No pseudopotential ﬁles are necessary. NetCDF support is needed. Note that ghost

atoms cannot yet be adequately treated with this option.

6.3.11 Tools to inspect the orbitals and KB projectors

The program ioncat in Util/Gen-basis can be used to extract orbital, KB projector, and other

information contained in the .ion ﬁles. The output can be easily plotted with a graphics program.

If the option WriteIonPlotFiles is enabled, SIESTA will generate and extra set of ﬁles that can

be plotted with the gnuplot scripts in Tutorials/Bases. The stand-alone program gen-basis sets

that option by default, and the script Tutorials/Bases/gen-basis.sh can be used to automate

the process. See also the NetCDF-based utilities in Util/PyAtom.

6.3.12 Basis optimization

There are quite a number of options for the input of the basis-set and KB projector speciﬁcation, and

they are all optional! By default, SIESTA will use a DZP basis set with appropriate choices for the

determination of the range, etc. Of course, the more you experiment with the diﬀerent options, the

better your basis set can get. To aid in this process we oﬀer an auxiliary program for optimization

which can be used in particular to obtain variationally optimal basis sets (within a chosen basis

size). See Util/Optimizer for general information, and Util/Optimizer/Examples/Basis_Optim

for an example.

BasisPressure 0.2 GPa (pressure)

SIESTA will compute and print the value of the “eﬀective basis enthalpy” constructed by

adding a term of the form p

basis

orbs

to the total energy. Here p

basis

is a ﬁctitious basis pressure

and V

orbs

is the volume of the system’s orbitals. This is a useful quantity for basis optimization

(See Anglada et al.). The total basis enthalpy is also written to the ASCII ﬁle BASIS_ENTHALPY.

6.3.13 Low-level options regarding the radial grid

For historical reasons, the basis-set and KB projector code in SIESTA uses a logarithmic radial

grid, which is taken from the pseudopotential ﬁle. Any “interesting” radii have to fall on a grid

point, which introduces a certain degree of coarseness that can limit the accuracy of the results and

the faithfulness of the mapping of input parameters to actual operating parameters. For example,

the same orbital will be produced by a ﬁnite range of PAO.EnergyShift values, and any user-

deﬁned cutoﬀs will not be exactly reﬂected in the actual cutoﬀs. This is particularly troublesome for

automatic optimization procedures (such as those implemented in Util/Optimizer), as the engine

might be confused by the extra level of indirection. The following options can be used to ﬁne-tune

the mapping. They are not enabled by default, as they change the numerical results apreciably (in

eﬀect, they lead to diﬀerent basis orbitals and projectors).

Reparametrize.Pseudos false (logical)

By changing the a and b parameters of the logarithmic grid, a new one with a more adequate

grid-point separation can be used for the generation of basis sets and projectors. For example,

by using a = 0.001 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 r’s of the order of a hundred bohrs,

but the extra computational eﬀort is negligible. The net eﬀect of this option (notably when

coupled to Restricted.Radial.Grid false) is a closer mapping of any user-speciﬁed cutoﬀ radii

and of the radii implicitly resulting from other input parameters to the actual values used by

the program. (The small grid-point separation near r=0 is still needed to avoid instabilities for

s channels that occurred with the previous (reparametrized) default spacing of 0.005 bohr. This

eﬀect is not yet completely understood. )

New.A.Parameter 0.001 (real)

New setting for the pseudopotential grid’s a parameter

New.B.Parameter 0.01 (real)

New setting for the pseudopotential grid’s b parameter

Rmax.Radial.Grid 50.0 (real)

New setting for the maximum value of the radial coordinate for integration of the atomic

Schrodinger equation.

If Reparametrize.Pseudos is false this will be the maximum radius in the pseudopotential

ﬁle.

Restricted.Radial.Grid true (logical)

In normal operation of the basis-set and projector generation code the various cutoﬀ radii are

restricted to falling on an odd-numbered grid point, shifting then accordingly. This restriction

can be lifted by setting this parameter to false.

6.4 Structural information

There are many ways to give SIESTA structural information.

• Directly from the fdf ﬁle in traditional format.

• Directly from the fdf ﬁle in the newer Z-Matrix format, using a Zmatrix block.

• From an external data ﬁle

Note that, regardless of the way in which the structure is described, the ChemicalSpeciesLabel

block is mandatory.

In the following sections we document the diﬀerent structure input methods, and provide a guide to

their precedence.

6.4.1 Traditional structure input in the fdf ﬁle

Firstly, the size of the cell itself should be speciﬁed, using some combination of the options Lat-

ticeConstant, LatticeParameters, and LatticeVectors, and SuperCell. If nothing is speciﬁed,

SIESTA will construct a cubic cell in which the atoms will reside as a cluster.

Secondly, the positions of the atoms within the cells must be speciﬁed, using either the traditional

SIESTA input format (a modiﬁed xyz format) which must be described within a AtomicCoordi-

natesAndAtomicSpecies block.

LatticeConstant 〈None〉 (length)

Lattice constant. This is just to deﬁne the scale of the lattice vectors.

Default value: Minimum size to include the system (assumed to be a molecule) without intercell

interactions, plus 10%.

NOTE: A LatticeConstant value, even if redundant, might be needed for other options, such as

the units of the k-points used for band-structure calculations. This mis-feature will be corrected

in future versions.

%block LatticeParameters 〈None〉 (block)

Crystallographic way of specifying the lattice vectors, by giving six real numbers: the three

vector modules, a, b, and c, and the three angles α (angle between

b and ~c), β, and γ. The

three modules are in units of LatticeConstant, the three angles are in degrees.

This defaults to a square cell with side-lengths equal to LatticeConstant.

1.0 1.0 1.0 90. 90. 90.

%block LatticeVectors 〈None〉 (block)

The cell vectors are read in units of the lattice constant deﬁned above. They are read as a

matrix CELL(ixyz,ivector), each vector being one line.

This defaults to a square cell with side-lengths equal to LatticeConstant.

1.0 0.0 0.0

0.0 1.0 0.0

0.0 0.0 1.0

If the LatticeConstant default is used, the default of LatticeVectors is still diagonal but not

necessarily cubic.

%block SuperCell 〈None〉 (block)

Integer 3x3 matrix deﬁning a supercell in terms of the unit cell. Any values larger than 1 will

expand the unitcell (plus atoms) along that lattice vector direction (if possible).

%block SuperCell

M(1,1) M(2,1) M(3,1)

M(1,2) M(2,2) M(3,2)

M(1,3) M(2,3) M(3,3)

%endblock SuperCell

and the supercell is deﬁned as SuperCell(ix, i) =

CELL(ix, j) ∗ M(j, i). Notice that the

matrix indexes are inverted: each input line speciﬁes one supercell vector.

Warning: SuperCell is disregarded if the geometry is read from the XV ﬁle, which can happen

inadvertently.

Use: The atomic positions must be given only for the unit cell, and they are ’cloned’ automat-

ically in the rest of the supercell. The NumberOfAtoms given must also be that in a single

unit cell. However, all values in the output are given for the entire supercell. In fact, CELL is

immediately redeﬁned as the whole supercell and the program no longer knows the existence of

an underlying unit cell. All other input (apart from NumberOfAtoms and atomic positions),

including kgrid.MonkhorstPack must refer to the supercell (this is a change over previous

versions). Therefore, to avoid confusions, we recommend to use SuperCell only to generate

atomic positions, and then to copy them from the output to a new input ﬁle with all the atoms

speciﬁed explicitly and with the supercell given as a normal unit cell.

AtomicCoordinatesFormat Bohr (string)

Character string to specify the format of the atomic positions in input. These can be expressed

in four forms:

Bohr|NotScaledCartesianBohr atomic positions are given directly in Bohr, in Cartesian co-

ordinates

Ang|NotScaledCartesianAng atomic positions are given directly in Ångström, in Cartesian

coordinates

ScaledCartesian atomic positions are given in Cartesian coordinates, in units of the lattice

constant

Fractional|ScaledByLatticeVectors atomic positions are given referred to the lattice vectors

AtomCoorFormatOut 〈AtomicCoordinatesFormat〉 (string)

Character string to specify the format of the atomic positions in output.

Same possibilities as for input AtomicCoordinatesFormat.

%block AtomicCoordinatesOrigin 〈None〉 (block)

Vector specifying a rigid shift to apply to the atomic coordinates, given in the same format and

units as these. Notice that the atomic positions (shifted or not) need not be within the cell

formed by LatticeVectors, since periodic boundary conditions are always assumed.

This defaults to the origo:

0.0 0.0 0.0

%block AtomicCoordinatesAndAtomicSpecies 〈None〉 (block)

Block specifying the position and species of each atom. One line per atom, the reading is done

this way:

From ia = 1 to natoms

read: xa(ix,ia), isa(ia)

where xa(ix,ia) is the ix coordinate of atom iai in the format (units) speciﬁed by Atomic-

CoordinatesFormat, and isa(ia) is the species index of atom ia.

NOTE: This block must be present in the fdf ﬁle. If NumberOfAtoms is not speciﬁed,

NumberOfAtoms will be defaulted to the number of atoms in this block.

NOTE: Zmatrix has precedence if speciﬁed.

6.4.2 Z-matrix format and constraints

The advantage of the traditional format is that it is much easier to set up a system. However, when

working on systems with constraints, there are only a limited number of (very simple) constraints

that may be expressed within this format, and recompilation is needed for each new constraint.

For any more involved set of constraints, a full Zmatrix formulation should be used - this oﬀers

much more control, and may be speciﬁed fully at run time (thus not requiring recompilation) - but

it is more work to generate the input ﬁles for this form.

%block Zmatrix 〈None〉 (block)

This block provides a means for inputting the system geometry using a Z-matrix format, as

well as controlling the optimization variables. This is particularly useful when working with

molecular systems or restricted optimizations (such as locating transition states or rigid unit

movements). The format also allows for hybrid use of Z-matrices and Cartesian or fractional

blocks, as is convenient for the study of a molecule on a surface. As is always the case for a Z-

matrix, the responsibility falls to the user to chose a sensible relationship between the variables

to avoid triads of atoms that become linear.

Below is an example of a Z-matrix input for a water molecule:

%block Zmatrix

molecule fractional

1 0 0 0 0.0 0.0 0.0 0 0 0

2 1 0 0 HO1 90.0 37.743919 1 0 0

2 1 2 0 HO2 HOH 90.0 1 1 0

variables

HO1 0.956997

HO2 0.956997

HOH 104.4

%endblock Zmatrix

The sections that can be used within the Zmatrix block are as follows:

Firstly, all atomic positions must be speciﬁed within either a “molecule” block or a “cartesian”

block. Any atoms subject to constraints more complicated than “do not change this coordinate

of this atom” must be speciﬁed within a “molecule” block.

molecule There must be one of these blocks for each independent set of constrained atoms

within the simulation.

This speciﬁes the atoms that make up each molecule and their geometry. In addition, an

option of “fractional” or “scaled” may be passed, which indicates that distances are spec-

iﬁed in scaled or fractional units. In the absence of such an option, the distance units are

taken to be the value of “ZM.UnitsLength”.

A line is needed for each atom in the molecule; the format of each line should be:

Nspecies i j k r a t ifr ifa ift

Here the values Nspecies, i, j, k, ifr, ifa, and ift are integers and r, a, and t are double

precision reals.

For most atoms, Nspecies is the species number of the atom, r is distance to atom number

i, a is the angle made by the present atom with atoms j and i, while t is the torsional

angle made by the present atom with atoms k, j, and i. The values ifr, ifa and ift are

integer ﬂags that indicate whether r, a, and t, respectively, should be varied; 0 for ﬁxed, 1

for varying.

The ﬁrst three atoms in a molecule are a special case. Because there are insuﬃcient atoms

deﬁned to specify a distance/angle/torsion, the values are set diﬀerently. For atom 1, r, a,

and t, are the Cartesian coordinates of the atom. For the second atom, r, a, and t are the

coordinates in spherical form of the second atom relative to the ﬁrst: ﬁrst the radius, then the

polar angle (angle between the z-axis and the displacement vector) and then the azimuthal

angle (angle between the x-axis and the projection of the displacement vector on the x-y

plane). Finally, for the third atom, the numbers take their normal form, but the torsional

angle is deﬁned relative 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 of constraints may be

speciﬁed in one of the following three ways, according to the units used to specify their

coordinates:

cartesian This section speciﬁes a block of atoms whose coordinates are to be speciﬁed in Carte-

sian coordinates. Again, an option of “fractional” or “scaled” may be added, to specify

the units used; and again, in their absence, the value of “ZM.UnitsLength” is taken.

The format of each atom in the block will look like:

Nspecies x y z ix iy iz

Here Nspecies, ix, iy, and iz are integers and x, y, z are reals. Nspecies is the species

number of the atom being speciﬁed, while x, y, and z are the Cartesian coordinates of the

atom in whichever units are being used. The values ix, iy and iz are integer ﬂags that

indicate whether the x, y, and z coordinates, respectively, should be varied or not. A value of

0 implies that the coordinate is ﬁxed, while 1 implies that it should be varied. NOTE: When

performing “variable cell” optimization while using a Zmatrix format for input, the algorithm

will not work if some of the coordinates of an atom in a cartesian block are variables and

others are not (i.e., ix iy iz above must all be 0 or 1). This will be ﬁxed in future versions

of the program.

A Zmatrix block may also contain the following, additional, sections, which are designed to

make it easier to read.

constants Instead of specifying a numerical value, it is possible to specify a symbol within the

above geometry deﬁnitions. This section allows the user to deﬁne the value of the symbol as

a constant. The format is just a symbol followed by the value:

HOH 104.4

variables Instead of specifying a numerical value, it is possible to specify a symbol within the

above geometry deﬁnitions. This section allows the user to deﬁne the value of the symbol as

a variable. The format is just a symbol followed by the value:

HO1 0.956997

Finally, constraints must be speciﬁed in a constraints block.

constraint This sub-section allows the user to create constraints between symbols used in a

Z-matrix:

constraint

var1 var2 A B

Here var1 and var2 are text symbols for two quantities in the Z-matrix deﬁnition, and AandB

are real numbers. The variables are related by var1 = A ∗var2 + B.

An example of a Z-matrix input for a benzene molecule over a metal surface is:

%block Zmatrix

molecule

2 0 0 0 xm1 ym1 zm1 0 0 0

2 1 0 0 CC 90.0 60.0 0 0 0

2 2 1 0 CC CCC 90.0 0 0 0

2 3 2 1 CC CCC 0.0 0 0 0

2 4 3 2 CC CCC 0.0 0 0 0

2 5 4 3 CC CCC 0.0 0 0 0

1 1 2 3 CH CCH 180.0 0 0 0

1 2 1 7 CH CCH 0.0 0 0 0

1 3 2 8 CH CCH 0.0 0 0 0

1 4 3 9 CH CCH 0.0 0 0 0

1 5 4 10 CH CCH 0.0 0 0 0

1 6 5 11 CH CCH 0.0 0 0 0

fractional

3 0.000000 0.000000 0.000000 0 0 0

3 0.333333 0.000000 0.000000 0 0 0

3 0.666666 0.000000 0.000000 0 0 0

3 0.000000 0.500000 0.000000 0 0 0

3 0.333333 0.500000 0.000000 0 0 0

3 0.666666 0.500000 0.000000 0 0 0

3 0.166667 0.250000 0.050000 0 0 0

3 0.500000 0.250000 0.050000 0 0 0

3 0.833333 0.250000 0.050000 0 0 0

3 0.166667 0.750000 0.050000 0 0 0

3 0.500000 0.750000 0.050000 0 0 0

3 0.833333 0.750000 0.050000 0 0 0

3 0.000000 0.000000 0.100000 0 0 0

3 0.333333 0.000000 0.100000 0 0 0

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

3 0.666666 0.500000 0.100000 0 0 0

3 0.166667 0.250000 0.150000 0 0 0

3 0.500000 0.250000 0.150000 0 0 0

3 0.833333 0.250000 0.150000 0 0 0

3 0.166667 0.750000 0.150000 0 0 0

3 0.500000 0.750000 0.150000 0 0 0

3 0.833333 0.750000 0.150000 0 0 0

constants

ym1 3.68

variables

zm1 6.9032294

CC 1.417

CH 1.112

CCH 120.0

CCC 120.0

constraints

xm1 CC -1.0 3.903229

%endblock Zmatrix

Here the species 1, 2 and 3 represent H, C, and the metal of the surface, respectively.

(Note: the above example shows the usefulness of symbolic names for the relevant coordinates,

in particular for those which are allowed to vary. The current output options for Zmatrix

information work best when this approach is taken. By using a “ﬁxed” symbolic Zmatrix block

and specifying the actual coordinates in a “variables” section, one can monitor the progress

of the optimization and easily reconstruct the coordinates of intermediate steps in the original

format.)

ZM.UnitsLength Bohr (string)

Parameter that speciﬁes the units of length used during Z-matrix input.

Specify Bohr or Ang for the corresponding unit of length.

ZM.UnitsAngle rad (string)

Parameter that speciﬁes the units of angles used during Z-matrix input.

Specify rad or deg for the corresponding unit of angle.

6.4.3 Output of structural information

SIESTA is able to generate several kinds of ﬁles containing structural information (maybe too

many).

• SystemLabel.STRUCT_OUT:Siesta always produces a .STRUCT_OUT ﬁle with cell vectors in Å

and atomic positions in fractional coordinates. This ﬁle, renamed to .STRUCT_IN can be used

for crystal-structure input. Note that the geometry reported is the last one for which forces

and stresses were computed. See UseStructFile

• SystemLabel.STRUCT_NEXT_ITER:This ﬁle is always written, in the same format as

.STRUCT_OUT ﬁle. The only diﬀerence is that it contains the structural information after

it has been updated by the relaxation or the molecular-dynamics algorithms, and thus it could

be used as input (renamed as .STRUCT_IN) for a continuation run, in the same way as the .XV

ﬁle.

See UseStructFile

• SystemLabel.XV:The coordinates are always written in the .XV ﬁle, and overriden at every

step.

• OUT.UCELL.ZMATRIX:This ﬁle is produced if the Zmatrix format is being used for input. (Please

note that SystemLabel is not used as a preﬁx.) It contains the structural information in fdf

form, with blocks for unit-cell vectors and for Zmatrix coordinates. The Zmatrix block is in a

“canonical” form with the following characteristics:

1. No symbolic variables or constants are used.

2. The position coordinates of the first atom in each molecule

are absolute Cartesian coordinates.

3. Any coordinates in ‘‘cartesian’’ blocks are also absolute Cartesians.

4. There is no provision for output of constraints.

5. The units used are those initially specified by the user, and are

noted also in fdf form.

Note that the geometry reported is the last one for which forces and stresses were computed.

• NEXT_ITER.UCELL.ZMATRIX:A ﬁle with the same format as OUT.UCELL.ZMATRIX but with a

possibly updated geometry.

• The coordinates can be also accumulated in the SystemLabel.MD or SystemLabel.MDX ﬁles

depending on WriteMDHistory.

• Additionally, several optional formats are supported:

WriteCoorXmol false (logical)

If true it originates the writing of an extra ﬁle named SystemLabel.xyz containing the

ﬁnal atomic coordinates in a format directly readable by XMol.

Coordinates come

out in Ångström independently of what speciﬁed in AtomicCoordinatesFormat and

in AtomCoorFormatOut. There is a present Java implementation of XMol called

JMol.

XMol is under © copyright of Research Equipment Inc., dba Minnesota Supercomputer Center Inc.

WriteCoorCerius false (logical)

If trueit originates the writing of an extra ﬁle named SystemLabel.xtl containing the

ﬁnal atomic coordinates in a format directly readable by Cerius.

Coordinates come out

in Fractional format (the same as ScaledByLatticeVectors) independently of what

speciﬁed in AtomicCoordinatesFormat and in AtomCoorFormatOut. If negative

coordinates are to be avoided, it has to be done from the start by shifting all the co-

ordinates rigidly to have them positive, by using AtomicCoordinatesOrigin. See the

Sies2arc utility in the Util/ directory for generating ..arc ﬁles for CERIUS animation.

WriteMDXmol false (logical)

If true it causes the writing of an extra ﬁle named SystemLabel.ANI containing all

the atomic coordinates of the simulation in a format directly readable by XMol for

animation. Coordinates come out in Ångström independently of what is speciﬁed in

AtomicCoordinatesFormat and in AtomCoorFormatOut. This ﬁle is accumulative

even for diﬀerent runs.

There is an alternative for animation by generating a .arc ﬁle for CERIUS. It is through

the Sies2arc postprocessing utility in the Util/ directory, and it requires the coordinates

to be accumulated in the output ﬁle, i.e., WriteCoorStep true.

6.4.4 Input of structural information from external ﬁles

The structural information can be also read from external ﬁles. Note that ChemicalSpeciesLabel

is mandatory in the fdf ﬁle.

MD.UseSaveXV false (logical)

Logical variable which instructs SIESTA to read the atomic positions and velocities stored in

ﬁle SystemLabel.XV by a previous run.

If the ﬁle does not exist, a warning is printed but the program does not stop. Overrides

UseSaveData, but can be implicitly set by it.

UseStructFile false (logical)

Controls whether the structural information is read from an external ﬁle of name

SystemLabel.STRUCT_IN. If true, all other structural information in the fdf ﬁle will be ig-

nored.

The format of the ﬁle is implied by the following code:

read(*,*) ((cell(ixyz,ivec),ixyz=1,3),ivec=1,3) ! Cell vectors, in Angstroms

read(*,*) na

do ia = 1,na

read(iu,*) isa(ia), dummy, xfrac(1:3,ia) ! Species number

! Dummy numerical column

! Fractional coordinates

enddo

Warning: Note that the resulting geometry could be clobbered if an .XV ﬁle is read after this

ﬁle. It is up to the user to remove any .XV ﬁles.

Cerius is under © copyright of Molecular Simulations Inc.

MD.UseSaveZM false (logical)

Instructs to read the Zmatrix information stored in ﬁle .ZM by a previous run.

If the required ﬁle does not exist, a warning is printed but the program does not stop. Overrides

UseSaveData, but can be implicitly set by it.

Warning: Note that the resulting geometry could be clobbered if an .XV ﬁle is read after this

ﬁle. It is up to the user to remove any .XV ﬁles.

6.4.5 Input from a FIFO ﬁle

See the “Forces” option in MD.TypeOfRun. Note that ChemicalSpeciesLabel is still mandatory

in the fdf ﬁle.

6.4.6 Precedence issues in structural input

• If the “Forces” option is active, it takes precedence over everything (it will overwrite all other

input with the information it gets from the FIFO ﬁle).

• If MD.UseSaveXV is active, it takes precedence over the options below.

• If UseStructFile (or MD.UseStructFile) is active, it takes precedence over the options

below.

• For atomic coordinates, the traditional and Zmatrix formats in the fdf ﬁle are mutually exclu-

sive. If MD.UseSaveZM is active, the contents of the ZM ﬁle, if found, take precedence over

the Zmatrix information in the fdf ﬁle.

6.4.7 Interatomic distances

WarningMinimumAtomicDistance 1 Bohr (length)

Fixes a threshold interatomic distance below which a warning message is printed.

MaxBondDistance 6 Bohr (length)

SIESTA prints the interatomic distances, up to a range of MaxBondDistance,

to ﬁle SystemLabel.BONDS upon ﬁrst reading the structural information, and to ﬁle

SystemLabel.BONDS_FINAL after the last geometry iteration. The reference atoms are all the

atoms in the unit cell. The routine now prints the real location of the neighbor atoms in space,

and not, as in earlier versions, the location of the equivalent representative in the unit cell.

6.5 k-point sampling

These are options for the k-point grid used in the SCF cycle. For other specialized grids, see the

Macroscopic Polarization and Density of States sections.

kgrid.Cutoﬀ 0. Bohr (length)

Parameter which determines the ﬁneness of the k-grid used for Brillouin zone sampling. It is half

the length of the smallest lattice vector of the supercell required to obtain the same sampling

precision with a single k point. Ref: Moreno and Soler, PRB 45, 13891 (1992).

Use: If it is zero, only the gamma point is used. The resulting k-grid is chosen in an optimal way,

according to the method of Moreno and Soler (using an eﬀective supercell which is as spherical as

possible, thus minimizing the number of k-points for a given precision). The grid is displaced for

even numbers of eﬀective mesh divisions. This parameter is not used if kgrid.MonkhorstPack

is speciﬁed. If the unit cell changes during the calculation (for example, in a cell-optimization

run, the k-point grid will change accordingly (see ChangeKgridInMD for the case of variable-

cell molecular-dynamics runs, such as Parrinello-Rahman). This is analogous to the changes in

the real-space grid, whose ﬁneness is speciﬁed by an energy cutoﬀ. If sudden changes in the

number of k-points are not desired, then the Monkhorst-Pack data block should be used instead.

In this case there will be an implicit change in the quality of the sampling as the cell changes.

Both methods should be equivalent for a well-converged sampling.

%block kgrid.MonkhorstPack Γ-point (block)

Real-space supercell, whose reciprocal unit cell is that of the k-sampling grid, and grid displace-

ment for each grid coordinate. Speciﬁed as an integer matrix and a real vector:

%block kgrid.MonkhorstPack

Mk(1,1) Mk(2,1) Mk(3,1) dk(1)

Mk(1,2) Mk(2,2) Mk(3,2) dk(2)

Mk(1,3) Mk(2,3) Mk(3,3) dk(3)

%endblock

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 not optimal). The k-grid supercell is deﬁned from Mk as in

block SuperCell above, i.e.: KgridSuperCell(ix, i) =

CELL(ix, j) ∗ Mk(j, i). Note again

that the matrix indexes are inverted: each input line gives the decomposition of a supercell

vector in terms of the unit cell vectors.

Use: Used only if SolutionMethod diagon. The k-grid supercell is compatible and unrelated

(except for the default value, see below) with the SuperCell speciﬁer. Both supercells are

given in terms of the CELL speciﬁed by the LatticeVectors block. If Mk is the identity matrix

and dk is zero, only the Γ point of the unit cell is used. Overrides kgrid.Cutoﬀ

ChangeKgridInMD false (logical)

If true, the k-point grid is recomputed at every iteration during MD runs that potentially

change the unit cell: Parrinello-Rahman, Nose-Parrinello-Rahman, and Anneal. Regardless of

the setting of this ﬂag, the k-point grid is always updated at every iteration of a variable-cell

optimization and after each step in a “siesta-as-server” run.

It is defaulted to false for historical reasons. The rationale was to avoid sudden jumps in some

properties when the sampling changes, but if the calculation is well-converged there should be

no problems if the update is enabled.

TimeReversalSymmetryForKpoints true (logical)

If true, the k-points in the BZ generated by the methods above are paired as (k, −k) and only

one member of the pair is retained. This symmetry is valid in the absence of external magnetic

ﬁelds or non-colinear/spin-orbit interaction.

This ﬂag should be used with care, as the code will produce wrong results if there is no support

for the appropriate symmetrization.

The default value is trueunless: a) the option Spin.Spiral is used. In this case time-reversal-

symmetry is broken explicitly. b) non-colinear/spin-orbit calculations. This case is less clear

cut, but the time-reversal symmetry is not used to avoid possible breakings due to subtle

implementation details, and to make the set of wavefunctions compatible with spin-orbit case

in analysis tools.

6.5.1 Output of k-point information

The coordinates of the

k points used in the sampling are always stored in the ﬁle SystemLabel.KP.

WriteKpoints false (logical)

If true it writes the coordinates of the

k vectors used in the grid for k-sampling, into the main

output ﬁle.

Default depends on LongOutput.

6.6 Exchange-correlation functionals

XC.Functional LDA (string)

Exchange-correlation functional type. May be LDA (local density approximation, equivalent

to LSD), GGA (Generalized Gradient Approximation), or VDW (van der Waals).

XC.Authors PZ (string)

Particular parametrization of the exchange-correlation functional. Options are:

• CA (equivalent to PZ): (Spin) local density approximation (LDA/LSD). Quantum Monte

Carlo calculation of the homogeneous electron gas by D. M. Ceperley and B. J. Alder, Phys.

Rev. Lett. 45,566 (1980), as parametrized by J. P. Perdew and A. Zunger, Phys. Rev B

23, 5075 (1981)

• PW92: LDA/LSD, as parametrized by J. P. Perdew and Y. Wang, Phys. Rev B, 45,

13244 (1992)

• PW91: Generalized gradients approximation (GGA) of Perdew and Wang. Ref: P&W,

J. Chem. Phys., 100, 1290 (1994)

• PBE: GGA of J. P. Perdew, K. Burke and M. Ernzerhof, Phys. Rev. Lett. 77, 3865

(1996)

• revPBE: Modiﬁed GGA-PBE functional of Y. Zhang and W. Yang, Phys. Rev. Lett. 80,

890 (1998)

• RPBE: Modiﬁed GGA-PBE functional of B. Hammer, L. B. Hansen and J. K. Norskov

Phys. Rev. B 59, 7413 (1999)

• WC: Modiﬁed GGA-PBE functional of Z. Wu and R. E. Cohen, Phys. Rev. B 73, 235116

(2006)

• AM05: Modiﬁed GGA-PBE functional of R. Armiento and A. E. Mattsson, Phys. Rev.

B 72, 085108 (2005)

• PBEsol: Modiﬁed GGA-PBE functional of J. P. Perdew et al, Phys. Rev. Lett. 100,

136406 (2008)

• PBEJsJrLO: GGA-PBE functional with parameters β, µ, and κ ﬁxed by the jellium

surface (Js), jellium response (Jr), and Lieb-Oxford bound (LO) criteria, respectively, as

described by 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, and S. B. Trickey, J. Chem. Theory Comput.

5, 798 (2009)

• PBEJsJrHEG: Same as PBEJsJrLO, with parameter κ ﬁxed by the Lieb-Oxford bound

for the low density limit of the homogeneous electron gas (HEG)

• PBEGcGxLO: Same as PBEJsJrLO, with parameters β and µ ﬁxed by the gradient

expansion of correlation (Gc) and exchange (Gx), respectively

• PBEGcGxHEG: Same as previous ones, with parameters β, µ, and κ ﬁxed by the Gc,

Gx, and HEG criteria, respectively.

• BLYP (equivalent to LYP): GGA with Becke exchange (A. D. Becke, Phys. Rev. A 38,

3098 (1988)) and Lee-Yang-Parr correlation (C. Lee, W. Yang, R. G. Parr, Phys. Rev.

B 37, 785 (1988)), as modiﬁed by B. Miehlich, A. Savin, H. Stoll, and H. Preuss, Chem.

Phys. Lett. 157, 200 (1989). See also B. G. Johnson, P. M. W. Gill and J. A. Pople, J.

Chem. Phys. 98, 5612 (1993). (Some errors were detected in this last paper, so not all of

their expressions correspond exactly to those implemented in SIESTA)

• DRSLL (equivalent to DF1): van der Waals density functional (vdW-DF) of M. Dion, H.

Rydberg, E. Schröder, D. C. Langreth, and B. I. Lundqvist, Phys. Rev. Lett. 92, 246401

(2004), with the eﬃcient implementation of G. Román-Pérez and J. M. Soler, Phys. Rev.

Lett. 103, 096102 (2009)

• LMKLL (equivalent to DF2): vdW-DF functional of Dion et al (same as DRSLL)

reparametrized by K. Lee, E. Murray, L. Kong, B. I. Lundqvist and D. C. Langreth,

Phys. Rev. B 82, 081101 (2010)

• KBM: vdW-DF functional of Dion et al (same as DRSLL) with exchange modiﬁed by J.

Klimes, D. R. Bowler, and A. Michaelides, J. Phys.: Condens. Matter 22, 022201 (2010)

(optB88-vdW version)

• C09: vdW-DF functional of Dion et al (same as DRSLL) with exchange modiﬁed by V.

R. Cooper, Phys. Rev. B 81, 161104 (2010)

• BH: vdW-DF functional of Dion et al (same as DRSLL) with exchange modiﬁed by K.

Berland and P. Hyldgaard, Phys. Rev. B 89, 035412 (2014)

• VV: vdW-DF functional of O. A. Vydrov and T. Van Voorhis, J. Chem. Phys. 133,

244103 (2010)

%block XC.Hybrid 〈None〉 (block)

This data block allows the user to create a “cocktail” functional by mixing the desired amounts

of exchange and correlation from each of the functionals described under XC.authors. Note that

these “mixed” functionals do not have the exact Hartree-Fock exchange which is a key ingredient

of the true “hybrid” functionals. The use of the word “hybrid” in the label is unfortunate in

this regard, and might be deprecated in a future version.

The ﬁrst line of the block must contain the number of functionals to be mixed. On the subse-

quent lines the values of XC.functl and XC.authors must be given and then the weights for the

exchange and correlation, in that order. If only one number is given then the same weight is

applied to both exchange and correlation.

The following is an example in which a 75:25 mixture of Ceperley-Alder and PBE correlation

is made, with an equal split of the exchange energy:

%block XC.hybrid

LDA CA 0.5 0.75

GGA PBE 0.5 0.25

%endblock XC.hybrid

XC.Use.BSC.CellXC false (logical)

If true, the version of cellXC from the BSC’s mesh suite is used instead of the default SiestaXC

version. BSC’s version might be slightly better for GGA operations. SiestaXC’s version is

mandatory when dealing with van der Waals functionals.

6.7 Spin polarization

Spin non-polarized (string)

deprecates: SpinPolarized, NonCollinearSpin, SpinOrbit

Choose the spin-components in the simulation.

NOTE: This ﬂag has precedence over SpinOrbit, NonCollinearSpin and SpinPolarized

while these deprecated ﬂags may still be used.

non-polarized Perform a calculation with spin-degeneracy (only one component).

polarized Perform a calculation with colinear spin (two spin components).

non-colinear Perform a calculation with non-colinear spin (4 spin components), up-down and

angles.

Refs: T. Oda et al, PRL, 80, 3622 (1998); V. M. García-Suárez et al, Eur. Phys. Jour. B

40, 371 (2004); V. M. García-Suárez et al, Journal of Phys: Cond. Matt 16, 5453 (2004).

spin-orbit Perform a calculation with spin-orbit coupling. This requires the pseudopotentials

to be relativistic.

See Sect. 6.8.

SIESTA can read a .DM with diﬀerent spin structure by adapting the information to the cur-

rently selected spin multiplicity, averaging or splitting the spin components equally, as needed.

This may be used to greatly increase convergence.

Certain options may not be used together with speciﬁc parallelization routines.

Spin.Fix false (logical)

If true, the calculation is done with a ﬁxed value of the spin of the system, deﬁned by variable

Spin.Total. This option can only be used for colinear spin polarized calculations.

Spin.Total 0 (real)

Value of the imposed total spin polarization of the system (in units of the electron spin, 1/2).

It is only used if Spin.Fix true.

%block Spin.Spiral 〈None〉 (block)

depends on: Spin

Specify the spiral q vector for the non-collinear spin.

Spin.Spiral.Scale ReciprocalLatticeVectors

%block Spin.Spiral

0. 0. 0.5

%endblock

NOTE: this option only applies for non-collinear spin (not for spin-orbit).

NOTE: this part of the code has not been tested, we would welcome any person who could

assert its correctness and provide tests. Use with extreme care.

Spin.Spiral.Scale 〈None〉 (string)

depends on: Spin.Spiral

Speciﬁes the scale of the spiral vector q vectors given in Spin.Spiral. The options are:

pi/a vector is given in Cartesian coordinates, in units of π/a, where a is the lattice constant

(LatticeConstant)

ReciprocalLatticeVectors vector is given in reciprocal-lattice-vector coordinates

SingleExcitation false (logical)

If true, SIESTA calculates a very rough approximation to the lowest excited state by swapping

the populations of the HOMO and the LUMO. If there is no spin polarisation, it is half swap

only. It is done for the ﬁrst spin component (up) and ﬁrst k vector.

6.8 Spin–Orbit coupling

SIESTA includes the possibility to perform fully relativistic calculations by including in the total

Hamiltonian not only the Darwin and velocity correction terms (Scalar–Relativistic calculations),

but also the spin-orbit (SO) contribution. (See Spin for how to turn on the spin-orbit coupling.)

The SO implementation in this version is based on the “on-site” approximation, in which only the

matrix elements corresponding to orbitals on the same atom are taken into account for the SO

part of the Hamiltonian. The implementation has been coded by Dr. Ramón Cuadrado based on

the original on-site SO formalism and implementation developed by Prof. Jaime Ferrer, et al (L

Fernández–Seivane, M Oliveira, S Sanvito, and J Ferrer, Journal of Physics: Condensed Matter,

2006 vol. 18 pp. 7999; L Fernández–Seivane and Jaime Ferrer, Phys. Rev. Lett. 99, 2007, 183401).

It should be noted that this approximation, while based on the physically reasonable idea of the

short-range of the SO interaction, might not be completely appropriate in all cases. Newer versions

of SIESTA (in the Gitlab development site) implement a spin–orbit–coupling formalism that does

not involve the “on-site” approximation and keeps all the SO matrix elements

[5]

. Users might want

to use the latter scheme to check the soundness of the “on-site” approximation for the system of

interest. In fact, since the full scheme is not more expensive than the approximate one, we would

recommend the use of the newer approach, unless there is a concern about employing an as-yet

unreleased version of the code.

The inclusion of the SO term in the Hamiltonian means that the two components of the spin are

coupled, and the calculation is of the “non-collinear” type with a doubling of the size of the matrices

involved (as opposed to the “collinear” spin case in which two diﬀerent spin blocks could be treated

independently). Hence a SO calculation using cube-scaling diagonalization would typically be four-

times more expensive (2

/2) than a collinear-spin one.

Apart from the study of eﬀects of the spin–orbit interaction in the band structure, a feature enabled

by a SO formalism is the computation of the Magnetic Anisotropy Energy (MAE): it can be obtained

as the diﬀerence in the total selfconsistent energy in two diﬀerent spin orientations, usually along

the easy axis and the hard axis. In SIESTA it is possible to perform calculations for diﬀerent

magnetization orientations using the block DM.InitSpin in the fdf ﬁle. In doing so one will be

able to include the initial orientation angles of the magnetization for each atom, as well as an initial

value of their net magnetic moments.

Note: Due to the small contribution of the spin–orbit interaction to the total energy, the level of

precision required is quite high. The following parameters should be carefully checked for each

speciﬁc system to assure that the results are converged and accurate enough: SCF.H.Tolerance

during the selfconsistency (typically <10

−5

eV), ElectronicTemperature, k-point sampling, and

Mesh.Cutoﬀ (speciﬁcally for extended solids). In general, one can say that a good calculation will

have a high number of k–points, low ElectronicTemperature, very small SCF.H.Tolerance and

high values of Mesh.Cutoﬀ. We encourage the user to test carefully these options for each system.

An additional point to take into account when the spin–orbit contribution is included is the mixing

scheme to use. You are encouraged to use the option to mix the Hamiltonian (SCF.Mix hamil-

tonian) instead of the density matrix to speed up convergence. In addition, the pseudopotentials

have to be well tested for each speciﬁc system. They have to be generated in their fully relativistic

form, and should use non-linear core corrections.

Spin.OrbitStrength 1.0 (real)

It allows to vary the strength of the spin-orbit interaction from zero to any positive value,

including the physical value. This ﬂag is only active when Spin is set to spin-orbit.

WriteOrbMom false (logical)

If true, a table is provided in the main output ﬁle, which includes an estimation of the vector

orbital magnetic moments, in units of the Bohr magneton, projected onto each orbital and also

onto each atom. The estimation for the orbital moments is based on a two-center approximation,

and makes use of the Mulliken population analysis.

If MullikenInScf is true, this information is printed at every scf step.

6.9 The self-consistent-ﬁeld loop

IMPORTANT NOTE: Convergence of the Kohn-Sham energy and forces

In versions prior to 4.0 of the program, the Kohn-Sham energy was computed using the “in” DM.

The typical DM used as input for the calculation of H was not directly computed from a set of

wave-functions (it was either the product of mixing or of the initialization from atomic values). In

this case, the “kinetic energy” term in the total energy computed in the way stated in the Siesta

paper had an error which decreased with the approach to self-consistency, but was non-zero. The

net result was that the Kohn-Sham energy converged more slowly than the “Harris” energy (which

is correctly computed).

When mixing H (see below under “Mixing Options”), the KS energy is in eﬀect computed from

DM(out), so this error vanishes.

As a related issue, the forces and stress computed after SCF convergence were calculated using the

DM coming out of the cycle, which by default was the product of a ﬁnal mixing. This also introduced

errors which grew with the degree of non-selfconsistency.

The current version introduces several changes:

• When mixing the DM, the Kohn-Sham energy may be corrected to make it variational. This

involves an extra call to dhscf (although with neither forces nor matrix elements being cal-

culated, i.e. only calls to rhoofd, poison, and cellxc), and is turned on by the option

SCF.Want.Variational.EKS.

• The program now prints a new column labeled “dHmax” for the self-consistent cycle. The

value represents the maximum absolute value of the changes in the entries of H, but its actual

meaning depends on whether DM or H mixing is in eﬀect: if mixing the DM, dHmax refers to

the change in H(in) with respect to the previous step; if mixing H, dHmax refers to H(out)-

H(in) in the current step.

• When achieving convergence, the loop might be exited without a further mixing of the DM,

thus preserving DM(out) for further processing (including the calculation of forces and the

analysis of the electronic structure) (see the SCF.Mix.AfterConvergence option).

• It remains to be seen whether the forces, being computed “right” on the basis of DM(out),

exhibit somehow better convergence as a function of the scf step. In order to gain some

more data and heuristics on this we have implemented a force-monitoring option, activated by

setting to true the variable SCF.MonitorForces. The program will then print the maximum

absolute value of the change in forces from one step to the next. Other statistics could be

implemented.

• While the (mixed) DM is saved at every SCF step, as was standard practice, the ﬁnal DM(out)

overwrites the SystemLabel.DM ﬁle at the end of the SCF cycle. Thus it is still possible to use

a “mixed” DM for restarting an interrupted loop, but a “good” DM will be used for any other

post-processing.

MinSCFIterations 0 (integer)

Minimum number of SCF iterations per time step. In MD simulations this can with beneﬁt be

set to 3.

MaxSCFIterations 1000 (integer)

Maximum number of SCF iterations per time step.

SCF.MustConverge true (logical)

Deﬁnes the behaviour if convergence is not reached in the maximum number of SCF iterations.

The default is to stop on the ﬁrst SCF convergence failure. Increasing MaxSCFIterations to

a large number may be advantageous when this is true.

6.9.1 Harris functional

Harris.Functional false (logical)

Logical variable to choose between self-consistent Kohn-Sham functional or non self-consistent

Harris functional to calculate energies and forces.

• false: Fully self-consistent Kohn-Sham functional.

• true: Non self consistent Harris functional. Cheap but pretty crude for some systems. The

forces are computed within the Harris functional in the ﬁrst SCF step. Only implemented

for LDA in the Perdew-Zunger parametrization. It really only applies to starting densities

which are superpositions of atomic charge densities.

When this option is choosen, the values of DM.UseSaveDM, SCF.MustConverge and

SCF.Mix.First are automatically set falseand MaxSCFIterations is set to 1, no matter

whatever other speciﬁcation are in the INPUT ﬁle.

6.9.2 Mixing options

Whether a calculation reaches self-consistency in a moderate number of steps depends strongly on

the mixing parameters used. The available mixing options should be carefully tested for a given

calculation type. This search for optimal parameters can repay itself handsomely by potentially

saving many self-consistency steps in production runs.

SCF.Mix Hamiltonian|density|charge (string)

Control what physical quantity to mix in the self-consistent cycle.

The default is mixing the Hamiltonian, which may typically perform better than density matrix

mixing.

Hamiltonian Mix the Hamiltonian matrix (default).

density Mix the density matrix.

charge Mix the real-space charge density. Note this is an experimental feature.

NOTE: Real-space charge density does not follow the regular options that adhere to density-

matrix or Hamiltonian mixing. Also it is not recommended to use real-space charge density

mixing with TranSIESTA.

SCF.Mix.Spin all|spinor|sum|sum+diﬀ (string)

Controls how the mixing is performed when carrying out spin-polarized calculations.

all Use all spin-components in the mixing

spinor Estimate mixing coeﬃcients using the spinor components

sum Estimate mixing coeﬃcients using the sum of the spinor components

sum+diﬀ Estimate mixing coeﬃcients using the sum and the diﬀerence between the spinor

components

NOTE: This option only inﬂuences density-matrix (ρ) or Hamiltonian (H) mixing when using

anything but the linear mixing scheme. And it does not inﬂuence not charge (ρ) mixing.

SCF.Mix.First true (logical)

deprecates: DM.MixSCF1

depends on: SCF.Mix.First.Force

This ﬂag is used to decide whether mixing (of the DM or H) should be done in the ﬁrst SCF

step. If mixing is not performed the output DM or H generated in the ﬁrst SCF step is used

as input in the next SCF step. When mixing the DM, this “reset” has the eﬀect of avoiding

potentially undesirable memory eﬀects: for example, a DM read from ﬁle which corresponds to

a diﬀerent structure might not satisfy the correct symmetry, and mixing will not ﬁx it. On the

other hand, when reusing a DM for a restart of an interrupted calculation, a full reset might

not be advised.

The value of this ﬂag is one of the ingredients used by SIESTA to decide what to do. If true

(the default), mixing will be performed in all cases, except when a DM has been read from ﬁle

and the sparsity pattern of the DM on ﬁle is diﬀerent from the current one. To ensure that a

ﬁrst-step mixing is done even in this case, SCF.Mix.First.Force should be set to true.

If the ﬂag is false, no mixing in the ﬁrst step will be performed, except if overridden by

SCF.Mix.First.Force.

NOTE: that the default value for this ﬂag has changed from the old (pre-version 4) setting in

SIESTA. The new setting is most appropriate for the case of restarting calculations. On the

other hand, it means that mixing in the ﬁrst SCF step will also be performed for the standard

case in which the initial DM is built as a (diagonal) superposition of atomic orbital occupation

values. In some cases (e.g. spin-orbit calculations) better results might be obtained by avoiding

this mixing.

SCF.Mix.First.Force false (logical)

Force the mixing (of DM or H) in the ﬁrst SCF step, regardless of what SIESTA may heuris-

tically decide.

This overrules SCF.Mix.First.

In the following the density matrix (ρ) will be used in the equations, while for Hamiltonian mixing,

ρ, should be replaced by the Hamiltonian matrix. Also we deﬁne R[i] = ρ

out

− ρ

and ∆R[i] =

R[i] −R[i − 1].

SCF.Mixer.Method Pulay|Broyden|Linear (string)

Choose the mixing algorithm between diﬀerent methods. Each method may have diﬀerent

variants, see SCF.Mixer.Variant.

Linear A simple linear extrapolation of the input matrix as

n+1

= ρ

+ w R[n]. (3)

Pulay Using the Pulay mixing method corresponds using the Kresse and Furthmüller

[6]

variant.

It relies on the previous N steps and uses those for estimating an optimal input ρ

n+1

for the

following iteration. The equation can be written as

n+1

= ρ

+ G R[n] +

N−1

i=n−N+1

(R[i] + G ∆R[i]), (4)

where G is the damping factor of the Pulay mixing (also known as the mixing weight). The

values α

are calculated using this formula

= −

N−1

j=1

−1

h∆R[j]|R[N]i, (5)

with A

= h∆R[j]|∆R[i]i.

In SIESTA G is a constant, and not a matrix.

NOTE: Pulay mixing is a special case of Broyden mixing, see the Broyden method.

Broyden The Broyden mixing is mixing method relying on the previous N steps in the history

for calculating an optimum input ρ

n+1

for the following iteration. The equation can be

written as

n+1

= ρ

+ G R[n] −

N−1

i=n−N+1

N−1

j=n−N+1

(R[i] + G ∆R[i]), (6)

where G is the damping factor (also known as the mixing weight). The values weights may

be expressed by

= 1 , for i > 0 (7)

= h∆R[i]|R[n]i, (8)



I + A



−1

(9)

= w

h∆R[i]|∆R[j]i. (10)

It should be noted that w

for i > 0 may be chosen arbitrarily. Comparing with the Pulay

mixing scheme it is obvious that Broyden and Pulay are equivalent for a suitable set of

parameters.

SCF.Mixer.Variant original (string)

Choose the variant of the mixing method.

Pulay This is implemented in two variants:

original|kresse The original

Pulay mixing scheme, as implemented in Kresse and Furth-

müller

[6]

GR The “guaranteed-reduction” variant of Pulay

[3]

. This variant has a special convergence

path. It interchanges between linear and Pulay mixing thus using the exact gradient at

each ρ

. For relatively simple systems this may be advantageous to use. However, for

complex systems it may be worse until it reaches a convergence basin.

To obtain the

original guaranteed-reduction variant one should set SCF.Mixer.<>.weight.linear to

SCF.Mixer.Weight 0.25 (real)

deprecates: DM.MixingWeight

The mixing weight used to mix the quantity. In the linear mixing case this refers to

n+1

= ρ

+ w R[n]. (11)

For details regarding the other methods please see SCF.Mixer.Method.

NOTE: the older keyword DM.MixingWeight is used if this key is not found in the input.

SCF.Mixer.History 2 (integer)

deprecates: DM.NumberPulay, DM.NumberBroyden

Number of previous SCF steps used in estimating the following input. Increasing this number,

typically, increases stability and a number of around 6 or above may be advised.

As such the “original” version is a variant it-self. But this is more stable in the far majority of cases.

NOTE: the older keyword DM.NumberPulay/DM.NumberBroyden is used if this key is

not found in the input.

SCF.Mixer.Kick 0 (integer)

After every N SCF steps a linear mix is inserted to kick the SCF cycle out of a possible local

minimum.

The mixing weight for this linear kick is determined by SCF.Mixer.Kick.Weight.

SCF.Mixer.Kick.Weight 〈SCF.Mixer.Weight〉 (real)

The mixing weight for the linear kick (if used).

SCF.Mixer.Restart 0 (integer)

When using advanced mixers (Pulay/Broyden) the mixing scheme may periodically restart the

history. This may greatly improve the convergence path as local constraints in the minimiza-

tion process are periodically removed. This method has similarity to the method proposed in

Banerjee et al.

[2]

and is a special case of the SCF.Mixer.Kick method.

Please see SCF.Mixer.Restart.Save which is advised to be set simultaneously.

SCF.Mixer.Restart.Save 1 (integer)

When restarting the history of saved SCF steps one may choose to save a subset of the latest

history steps. When using SCF.Mixer.Restart it is encouraged to also save a couple of

previous history steps.

SCF.Mixer.Linear.After -1 (integer)

After reaching convergence one may run additional SCF cycles using a linear mixing scheme. If

this has a value ≥ 0 SIESTA will perform linear mixing after it has converged using the regular

mixing method (SCF.Mixer.Method).

The mixing weight for this linear mixing is controlled by SCF.Mixer.Linear.After.Weight.

SCF.Mixer.Linear.After.Weight 〈SCF.Mixer.Weight〉 (real)

After reaching convergence one may run additional SCF cycles using a linear mixing scheme. If

this has a value ≥ 0 SIESTA will perform linear mixing after it has converged using the regular

mixing method (SCF.Mixer.Method).

The mixing weight for this linear mixing is controlled by SCF.Mixer.Linear.After.Weight.

In conjunction with the above simple settings controlling the SCF cycle SIESTA employs a very

conﬁgurable mixing scheme. In essence one may switch mixing methods, arbitrarily, during the SCF

cycle via control commands. This can greatly speed up convergence.

%block SCF.Mixers 〈None〉 (block)

Each line in this block deﬁnes a separate mixer that is deﬁned in a subsequent SCF.Mixer.<>

block.

The ﬁrst line is the initial mixer used.

See the following options for controlling individual mixing methods.

NOTE: If this block is deﬁned you must deﬁne all mixing parameters individually.

%block SCF.Mixer.<> 〈None〉 (block)

This block controls the mixer named <>.

method Deﬁne the method for the mixer, see SCF.Mixer.Method for possible values.

variant Deﬁne the variant of the method, see SCF.Mixer.Variant for possible values.

weight|w Deﬁne the mixing weight for the mixing scheme, see SCF.Mixer.Weight.

history Deﬁne number of previous history steps used in the minimization process, see

SCF.Mixer.History.

weight.linear|w.linear Deﬁne the linear mixing weight for the mixing scheme. This only has

meaning for Pulay or Broyden mixing. It deﬁnes the initial linear mixing weight.

To obtain the original Pulay Guarenteed-Reduction variant one should set this to 1.

restart Deﬁne the periodic restart of the saved history, see SCF.Mixer.Restart.

restart.save Deﬁne number of latest history steps retained when restarting the history, see

SCF.Mixer.Restart.Save.

iterations Deﬁne the maximum number of iterations this mixer should run before changing to

another mixing method.

NOTE: This must be used in conjunction with the next setting.

next <> Specify the name of the next mixing scheme after having conducted iterations SCF

cycles using this mixing method.

next.conv <> If SCF convergence is reached using this mixer, switch to the mixing scheme

via <>. Then proceed with the SCF cycle.

next.p If the relative diﬀerence between the latest two residuals is below this quantity, the mixer

will switch to the method given in next. Thus if

hR[i]|R[i]i− hR[i − 1]|R[i − 1]i

hR[i −1]|R[i − 1]i

< next.p (12)

is fulﬁlled it will skip to the next mixer.

restart.p If the relative diﬀerence between the latest two residuals is below this quantity, the

mixer will restart the history. Thus if

hR[i]|R[i]i− hR[i − 1]|R[i − 1]i

hR[i −1]|R[i − 1]i

< restart.p (13)

is fulﬁlled it will reset the history.

The options covered now may be exempliﬁed in these examples. If the input ﬁle contains:

SCF.Mixer.Method pulay

SCF.Mixer.Weight 0.05

SCF.Mixer.History 10

SCF.Mixer.Restart 25

SCF.Mixer.Restart.Save 4

SCF.Mixer.Linear.After 0

SCF.Mixer.Linear.After.Weight 0.1

This may be equivalently setup using the more advanced input blocks:

%block SCF.Mixers

init

final

%endblock

%block SCF.Mixer.init

method pulay

weight 0.05

history 10

restart 25

restart.save 4

next.conv final

%endblock

%block SCF.Mixer.final

method linear

weight 0.1

%endblock

This advanced setup may be used to change mixers during the SCF to change certain parameters

of the mixing method, or fully change the method for mixing. For instance it may be advantageous

to increase the mixing weight once a certain degree of self-consistency has been reached. In the

following example we change the mixing method to a diﬀerent scheme by increasing the weight and

decreasing the history steps:

%block SCF.Mixers

init

final

%endblock

%block SCF.Mixer.init

method pulay

weight 0.05

history 10

next final

# Switch when the relative residual goes below 5%

next.p 0.05

%endblock

%block SCF.Mixer.final

method pulay

weight 0.1

history 6

%endblock

In essence, very complicated schemes of convergence may be created using the block’s input.

The following options refer to the global treatment of how/when mixing should be performed.

Compat.Pre-v4-DM-H false (logical)

This

controls the default values of SCF.Mix.AfterConvergence, SCF.RecomputeHAfterScf

and SCF.Mix.First.

In versions prior to v4 the two former options where defaulted to true while the latter option

was defaulted to false.

SCF.Mix.AfterConvergence false (logical)

Indicate whether mixing is done in the last SCF cycle (after convergence has been achieved) or

not. Not mixing after convergence improves the quality of the ﬁnal Kohn-Sham energy and of

the forces when mixing the DM.

NOTE: See Compat.Pre-v4-DM-H.

SCF.RecomputeHAfterSCF false (logical)

Indicate whether the Hamiltonian is updated after the scf cycle, while computing the ﬁnal

energy, forces, and stresses. Not recomputing H makes further analysis tasks (such as the

computation of band structures) more consistent, as they will be able to use the same H used

to generate the last density matrix.

NOTE: See Compat.Pre-v4-DM-H.

6.9.3 Mixing of the Charge Density

See SCF.Mix on how to enable charge density mixing. If charge density mixing is enabled the

fourier components of the charge density are 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.)

The charge mixing is implemented roughly as follows:

• The charge density computed in dhscf is fourier-transformed and stored in a new module. This

is done both for “ρ(G)(in)” and “ρ(G)(out)” (the “out” charge is computed during the extra

call to dhscf for correction of the variational character of the Kohn-Sham energy)

• The “in” and “out” charges are mixed (see below), and the resulting “in” fourier components

are used by dhscf in successive iterations to reconstruct the charge density.

• The new arrays needed and the processing of most new options is done in the new module

m_rhog.F90. The fourier-transforms are carried out by code in rhoﬀt.F.

• Following standard practice, two options for mixing are oﬀered:

– A simple Kerker mixing, with an optional Thomas-Fermi wavevector to damp the contri-

butions for small G’s. The overall mixing weight is the same as for other kinds of mixing,

read from DM.MixingWeight.

– A DIIS (Pulay) procedure that takes into account a sub-set of the G vectors (those within

a smaller cutoﬀ). Optionally, the scalar product used for the construction of the DIIS

matrix from the residuals uses a weight factor.

The DIIS extrapolation is followed by a Kerker mixing step.

The code is m_diis.F90. The DIIS history is kept in a circular stack, implemented using

the new framework for reference-counted types. This might be overkill for this particular

use, and there are a few rough edges, but it works well.

The default convergence criteria remains based on the diﬀerences in the density matrix, but in this

case the diﬀerences are from step to step, not the more fundamental DM_out-DM_in. Perhaps some

other criterion should be made the default (max |∆rho(G)|, convergence of the free-energy...)

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 zeroes in the Harris energy ﬁeld.

Note that the KS energy is correctly computed throughout the scf cycle, as there is an extra step for

the calculation of the charge stemming from DM_out, which also updates the energies. Forces and

ﬁnal energies are correctly computed with the ﬁnal DM_out, regardless of the setting of the option

for mixing after scf convergence.

Initial tests suggest that charge mixing has some desirable properties and could be a drop-in re-

placement for density-matrix mixing, but many more tests are needed to calibrate its eﬃciency for

diﬀerent kinds of systems, and the heuristics for the (perhaps too many) parameters:

SCF.Kerker.q0sq 0 Ry (energy)

Determines the parameter q

featuring in the Kerker preconditioning, which is always performed

on all components of ρ(G), even those treated with the DIIS scheme.

SCF.RhoGMixingCutoﬀ 9 Ry (energy)

Determines the sub-set of G vectors which will undergo the DIIS procedure. Only those with

kinetic energies below this cutoﬀ will be considered. The optimal extrapolation of the ρ(G)

elements will be replaced in the fourier series before performing the Kerker mixing.

SCF.RhoG.DIIS.Depth 0 (integer)

Determines the maximum number of previous steps considered in the DIIS procedure.

NOTE: The information from the ﬁrst scf step is not included in the DIIS history. There is no

provision yet for any other kind of “kick-starting” procedure. The logic is in m_rhog (rhog_mixing

routine).

SCF.RhoG.Metric.Preconditioner.Cutoﬀ 〈None〉 (energy)

Determines the value of q

in the weighing of the diﬀerent G components in the scalar products

among residuals in the DIIS procedure. Following the KF ansatz, this parameter is chosen so

that the smallest (non-zero) G has a weight 20 times larger than that of the smallest G vector

in the DIIS set.

The default is the result of the KF prescription.

SCF.DebugRhoGMixing false (logical)

Controls the level of debugging output in the mixing procedure (basically whether the ﬁrst few

stars worth of Fourier components are printed). Note that this feature will only display the

components in the master node.

Debug.DIIS false (logical)

Controls the level of debugging output in the DIIS procedure. If set, the program prints the

DIIS matrix and the extrapolation coeﬃcients.

SCF.MixCharge.SCF1 false (logical)

Logical variable to indicate whether or not the charge is mixed in the ﬁrst SCF cycle. Anecdotal

evidence indicates that it might be advantageous, at least for calculations started from scratch,

to avoid that ﬁrst mixing, and retain the “out” charge density as “in” for the next step.

6.9.4 Initialization of the density-matrix

NOTE: The conditions and options for density-matrix re-use are quite varied and not completely

orthogonal at this point. For further information, see routine Src/m_new_dm.F. What follows is a

summary.

The Density matrix can be:

1. Synthesized directly from atomic occupations.

(See the options below for spin considerations)

2. Read from a .DM file (if the appropriate options are set)

3. Extrapolated from previous geometry steps

(this includes as a special case the re-use of the DM

of the previous geometry iteration)

In cases 2 and 3, the structure of the read or extrapolated DM

is automatically adjusted to the current sparsity pattern.

In what follows, "Initialization" of the DM means that the DM is

either read from file (if available) or synthesized from atomic

data. This is confusing, and better terminology should be used.

Special cases:

Harris functional: The matrix is always initialized

Force calculation: The DM should be written to disk

at the time of the "no displacement"

calculation and read from file at

every subsequent step.

Variable-cell calculation:

If the auxiliary cell changes, the DM is forced to be

synthesized (conceivably one could rescue some important

information from an old DM, but it is too much trouble

for now). NOTE that this is a change in policy with respect

to previous versions of the program, in which a (blind?)

re-use was allowed, except if ’ReInitialiseDM’ was ’true’.

Now ’ReInitialiseDM’ is ’true’ by default. Setting it to

’false’ is not recommended.

In all other cases (including "server operation"), the

default is to allow DM re-use (with possible extrapolation)

from previous geometry steps.

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.

The fdf variables ’DM.AllowReuse’ and ’DM.AllowExtrapolation’

can be used to turn off DM re-use and extrapolation.

DM.UseSaveDM false (logical)

Instructs to read the density matrix stored in ﬁle SystemLabel..DM by a previous run.

SIESTA will continue even if .DM is not found.

NOTE: That if the spin settings has changed SIESTA allows reading a .DM from a similar cal-

culation with diﬀerent Spin option. This may be advantageous when going from non-polarized

calculations to polarized, and beyond, see Spin for details.

DM.Init.Unfold true (logical)

depends on: DM.UseSaveDM

When reading the DM from a previous calculation there may be inconsistencies in the auxiliary

supercell. E.g. if the previous calculation did not use an auxiliary supercell and the current

calculation does (adding k-point sampling). SIESTA will automatically unfold the Γ-only DM

to the auxiliary supercell elements (if true).

For false the DM elements are assumed to originate from an auxiliary supercell calculation and

the sparse elements are not unfolded but directly copied.

NOTE: Generally this shouldn’t not be touched, however, if the initial DM is generated using

sisl

[13]

and only on-site DM elements are set, this should be set to false.

DM.FormattedFiles false (logical)

Setting this alters the default for DM.FormattedInput and DM.FormattedOutput. In-

structs to use formatted ﬁles for reading and writing the density matrix. In this case, the ﬁles

are labelled SystemLabel.DMF.

Only usable if one has problems transferring ﬁles from one computer to another.

DM.FormattedInput false (logical)

Instructs to use formatted ﬁles for reading the density matrix.

DM.FormattedOutput false (logical)

Instructs to use formatted ﬁles for writing the density matrix.

DM.InitSpin.AF false (logical)

It deﬁnes the initial spin density for a spin polarized calculation. The spin density is initially

constructed with the maximum possible spin polarization for each atom in its atomic conﬁgu-

ration. This variable deﬁnes the relative orientation of the atomic spins:

If false the initial spin-conﬁguration is a ferromagnetic order (all spins up). If true all odd

atoms are initialized to spin-up, all even atoms are initialized to spin-down.

%block DM.InitSpin 〈None〉 (block)

Deﬁne the initial spin density for a spin polarized calculation atom by atom. In the block

there is one line per atom to be spin-polarized, containing the atom index (integer, ordinal in

the block AtomicCoordinatesAndAtomicSpecies) and the desired initial spin-polarization

(real, positive for spin up, negative for spin down). A value larger than possible will be reduced

to the maximum possible polarization, keeping its sign. Maximum polarization can also be

given by introducing the symbol + or - instead of the polarization 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 be given non-polarized initialization.

For non-collinear spin, the spin direction may be speciﬁed for each atom by the polar angle θ and

the azimuthal angle φ (using the physics ISO convention), given as the last two arguments in

degrees. If not speciﬁed, θ = 0 is assumed (z-polarized). Spin must be set to use non-collinear

or spin-orbit for the directions to have eﬀect.

Example:

%block DM.InitSpin

5 -1. 90. 0. # Atom index, spin, theta, phi (deg)

3 + 45. -90.

7 -

%endblock DM.InitSpin

In the above example, atom 5 is polarized in the x-direction.

If this block is deﬁned, but empty, all atoms are not polarized. This block has precedence over

DM.InitSpin.AF.

DM.AllowReuse true (logical)

Controls whether density matrix information from previous geometry iterations is re-used to

start the new geometry’s SCF cycle.

DM.AllowExtrapolation true (logical)

Controls whether the density matrix information from several previous geometry iterations

is extrapolated to start the new geometry’s SCF cycle. This feature is useful for molecular

dynamics simulations and possibly also for geometry relaxations. The number of geometry

steps saved is controlled by the variable DM.History.Depth.

This is default true for molecular-dynamics simulations, but false, for now, for geometry-

relaxations (pending further tests which users are kindly requested to perform).

DM.History.Depth 1 (integer)

Sets the number of geometry steps for which density-matrix information is saved for extrapola-

tion.

6.9.5 Initialization of the SCF cycle with charge densities

SCF.Read.Charge.NetCDF false (logical)

Instructs SIESTA to read the charge density stored in the netCDF ﬁle Rho.IN.grid.nc. This

feature allows the easier re-use of electronic-structure information from a previous run. It is not

necessary that the basis sets are “similar” (a requirement if density-matrices are to be read in).

NOTE: This is an experimental feature. Until robust checks are implemented, care must be

taken to make sure that the FFT grids in the .grid.nc ﬁle and in SIESTA are the same.

SCF.Read.Deformation.Charge.NetCDF false (logical)

Instructs Siesta to read the deformation charge density stored in the netCDF ﬁle

DeltaRho.IN.grid.nc. This feature allows the easier re-use of electronic-structure informa-

tion from a previous run. It is not necessary that the basis sets are “similar” (a requirement

if density-matrices are to be read in). The deformation charge is particularly useful to give a

good starting point for slightly diﬀerent geometries.

NOTE: This is an experimental feature. Until robust checks are implemented, care must be

taken to make sure that the FFT grids in the .grid.nc ﬁle and in Siesta are the same.

6.9.6 Output of density matrix and Hamiltonian

Performance Note: For large-scale calculations, writing the DM at every scf step can have a severe

impact on performance. The sparse-matrix I/O is undergoing a re-design, to facilitate the analysis

of data and to increase the eﬃciency.

Use.Blocked.WriteMat false (logical)

By using blocks of orbitals (according to the underlying default block-cyclic distribution), the

sparse-matrix I/O can be speeded-up signiﬁcantly, both by saving MPI communication and by

reducing the number of ﬁle accesses. This is essential for large systems, for which the I/O could

take a signiﬁcant fraction of the total computation time.

To enable this “blocked format” (recommended for large-scale calculations) use the option

Use.Blocked.WriteMat true. Note that it is oﬀ by default.

The new format is not backwards compatible. A

converter program (Util/DensityMatrix/dmUnblock.F90) has been written to post-process

those ﬁles intended for further analysis or re-use in Siesta. This is the best option for now, since

it allows liberal checkpointing with a much smaller time consumption, and only incurs costs

when re-using or analyzing ﬁles.

Note that TranSIESTA will continue to produce SystemLabel.DM ﬁles, in the old format (See

save_density_matrix.F)

To test the new features, the option S.Only true can be used. It will produce three ﬁles: a

standard one, another one with optimized MPI communications, and a third, blocked one.

Write.DM true (logical)

Control the creation of the current iterations density matrix to a ﬁle for restart purposes and

post-processing. If false nothing will be written.

If Use.Blocked.WriteMat is false the SystemLabel.DM ﬁle will be written. Otherwise these

density matrix ﬁles will be created; DM_MIXED.blocked and DM_OUT.blocked which are the

mixed and the diagonalization output, respectively.

Write.DM.end.of.cycle 〈Write.DM〉 (logical)

Equivalent to Write.DM, but will only write at the end of each SCF loop.

NOTE: The ﬁle generated depends on SCF.Mix.AfterConvergence.

Write.H false (logical)

Whether restart Hamiltonians should be written (not intrinsically supported in 4.1).

If true these ﬁles will be created; H_MIXED or H_DMGEN which is the mixed or the generated

Hamiltonian from the current density matrix, respectively. If Use.Blocked.WriteMat the

just mentioned ﬁles will have the additional suﬃx .blocked.

Write.H.end.of.cycle 〈Write.H〉 (logical)

Equivalent to Write.H, but will only write at the end of each SCF loop.

NOTE: The ﬁle generated depends on SCF.Mix.AfterConvergence.

The following options control the creation of netCDF ﬁles. The relevant routines have not been

optimized yet for large-scale calculations, so in this case the options should not be turned on (they

are oﬀ by default).

Write.DM.NetCDF true (logical)

It determines whether the density matrix (after the mixing step) is output as a DM.nc netCDF

ﬁle or not.

The ﬁle is overwritten at every SCF step. Use the Write.DM.History.NetCDF option if a

complete history is desired.

The DM.nc and standard DM ﬁle formats can be converted at will with the programs in

Util/DensityMatrix directory. Note that the DM values in the DM.nc ﬁle are in single preci-

sion.

Write.DMHS.NetCDF true (logical)

If true, the input density matrix, Hamiltonian, and output density matrix, are stored in a

netCDF ﬁle named DMHS.nc. The ﬁle also contains the overlap matrix S.

The ﬁle is overwritten at every SCF step. Use the Write.DMHS.History.NetCDF option if

a complete history is desired.

Write.DM.History.NetCDF false (logical)

If true, a series of netCDF ﬁles with names of the form DM-NNNN.nc is created to hold the

complete history of the density matrix (after mixing). (See also Write.DM.NetCDF). Each

ﬁle corresponds to a geometry step.

Write.DMHS.History.NetCDF false (logical)

If true, a series of netCDF ﬁles with names of the form DMHS-NNNN.nc is created to hold

the complete history of the input and output density matrix, and the Hamiltonian. (See also

Write.DMHS.NetCDF). Each ﬁle corresponds to a geometry step. The overlap matrix is

stored only once per SCF cycle.

Write.TSHS.History false (logical)

If true, a series of TSHS ﬁles with names of the form SystemLabel.N.TSHS is created to hold the

complete history of the Hamiltonian and overlap matrix. Each ﬁle corresponds to a geometry

step. The overlap matrix is stored only once per SCF cycle. This option only works with

TranSIESTA.

6.9.7 Convergence criteria

NOTE: The older options with a DM preﬁx is still working for backwards compatibility. However,

the following ﬂags has precedence.

Note that all convergence criteria are additive and may thus be used simultaneously for complete

control.

SCF.DM.Converge true (logical)

Logical variable to use the density matrix elements as monitor of self-consistency.

SCF.DM.Tolerance 10

−4

(real)

depends on: SCF.DM.Converge

Tolerance of Density Matrix. When the maximum diﬀerence between 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 achieved.

NOTE: DM.Tolerance is the actual default for this ﬂag.

DM.Normalization.Tolerance 10

−5

(real)

Tolerance for unnormalized density matrices (typically the product of solvers such as PEXSI

which have a built-in electron-count tolerance). If this tolerance is exceeded, the program stops.

It is understood as a fractional tolerance. For example, the default will allow an excess or shorfall

of 0.01 electrons in a 1000-electron system.

SCF.H.Converge true (logical)

Logical variable to use the Hamiltonian matrix elements as monitor of self-consistency: this is

considered achieved when the maximum absolute change (dHmax) in the H matrix elements is

below SCF.H.Tolerance. The actual meaning of dHmax depends on whether DM or H mixing

is in eﬀect: if mixing the DM, dHmax refers to the change in H(in) with respect to the previous

step; if mixing H, dHmax refers to H(out)-H(in) in the previous(?) step.

SCF.H.Tolerance 10

−3

eV (energy)

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 is below this value.

SCF.EDM.Converge true (logical)

Logical variable to use the energy density matrix elements as monitor of self-consistency: this is

considered achieved when the maximum absolute change (dEmax) in the energy density matrix

elements is below SCF.EDM.Tolerance. The meaning of dEmax is equivalent to that of

SCF.DM.Tolerance.

SCF.EDM.Tolerance 10

−3

eV (energy)

depends on: SCF.EDM.Converge

If SCF.EDM.Converge is true, then self-consistency is achieved when the maximum absolute

change in the energy density matrix elements is below this value.

SCF.FreeE.Converge false (logical)

Logical variable to request an additional requirement for self-consistency: it is considered

achieved when the change in the total (free) energy between cycles of the SCF procedure is

below SCF.FreeE.Tolerance and the density matrix change criterion is also satisﬁed.

SCF.FreeE.Tolerance 10

−4

eV (energy)

depends on: SCF.FreeE.Converge

If SCF.FreeE.Converge is true, then self-consistency is achieved when the change in the total

(free) energy between cycles of the SCF procedure is below this value and the density matrix

change criterion is also satisﬁed.

SCF.Harris.Converge false (logical)

Logical variable to use the Harris energy as monitor of self-consistency: this is considered

achieved when the change in the Harris energy between cycles of the SCF procedure is below

SCF.Harris.Tolerance. This is useful if only energies are needed, as the Harris energy tends

to converge faster than the Kohn-Sham energy. The user is responsible for using the correct

energies in further processing, e.g., the Harris energy if the Harris criterion is used.

To help in basis-optimization tasks, a new ﬁle BASIS_HARRIS_ENTHALPY is provided, holding the

same information as BASIS_ENTHALPY but using the Harris energy instead of the Kohn-Sham

energy.

NOTE: Setting this to true makes SCF.DM.Converge SCF.H.Converge default to false.

SCF.Harris.Tolerance 10

−4

eV (energy)

depends on: SCF.Harris.Converge

If SCF.Harris.Converge is true, then self-consistency is achieved when the change in the

Harris energy between cycles of the SCF procedure is below this value. This is useful if only

energies are needed, as the Harris energy tends to converge faster than the Kohn-Sham energy.

6.10 The real-space grid and the eggbox-eﬀect

SIESTA uses a ﬁnite 3D grid for the calculation of some integrals and the representation of

charge densities and potentials. Its ﬁneness is determined by its plane-wave cutoﬀ, as given by

the Mesh.Cutoﬀoption. It means that all periodic plane waves with kinetic energy lower than this

cutoﬀ can be represented in the grid without aliasing. In turn, this implies that if a function (e.g.

the density or the eﬀective potential) is an expansion of only these plane waves, it can be Fourier

transformed back and forth without any approximation.

The existence of the grid causes the breaking of translational symmetry (the egg-box eﬀect, due to

the fact that the density and potential do have plane wave components above the mesh cutoﬀ). This

symmetry breaking is clear when moving one single atom in an otherwise empty simulation cell.

The total energy and the forces oscillate with the grid periodicity when the atom is moved, as if the

atom were moving on an eggbox. In the limit of inﬁnitely ﬁne grid (inﬁnite mesh cutoﬀ) this eﬀect

disappears.

For reasonable values of the mesh cutoﬀ, the eﬀect of the eggbox on the total energy or on the relaxed

structure is normally unimportant. However, it can aﬀect substantially the process of relaxation, by

increasing the number of steps considerably, and can also spoil the calculation of vibrations, usually

much more demanding than relaxations.

The Util/Scripting/eggbox_checker.py script can be used to diagnose the eggbox eﬀect to be

expected for a particular pseudopotential/basis-set combination.

Apart from increasing the mesh cutoﬀ (see the Mesh.Cutoﬀ option), the following options might

help in lessening a given eggbox problem. But note also that a ﬁltering of the orbitals and the

relevant parts of the pseudopotential and the pseudocore charge might be enough to solve the issue

(see Sec. 6.3.9).

Mesh.Cutoﬀ 300 Ry (energy)

Deﬁnes the plane wave cutoﬀ for the grid.

Mesh.Sizes 〈Mesh.Cutoﬀ〉 (list)

Manual deﬁnition of grid size along each lattice vector. The value must be divisible by

Mesh.SubDivisions, otherwise the program will die. The numbers should also be divisible

with 2, 3 and 5 due to the FFT algorithms.

This option may be speciﬁed as a block, or a list:

%block Mesh.Sizes

100 202 210

%endblock

# Or equivalently:

Mesh.Sizes [100 202 210]

By default the grid size is determined via Mesh.Cutoﬀ. This option has precedence if both

are speciﬁed.

Mesh.SubDivisions 2 (integer)

Deﬁnes the number of sub-mesh points in each direction used to save index storage on the mesh.

It aﬀects the memory requirements and the CPU time, but not the results.

NOTE: The default value might be a bit conservative. Users might experiment with higher

values, 4 or 6, to lower the memory and cputime usage.

%block Grid.CellSampling 〈None〉 (block)

It speciﬁes points within the grid cell for a symmetrization sampling.

For a given grid the grid-cutoﬀ convergence can be improved (and the eggbox lessened) by

recovering the lost symmetry: by symmetrizing the sensitive quantities. The full symmetrization

implies an integration (averaging) over the grid cell. Instead, a ﬁnite sampling can be performed.

It is a sampling of rigid displacements of the system with respect to the grid. The original

grid-system setup (one point of the grid at the origin) is always calculated. It is the (0,0,0)

displacement. The block Grid.CellSampling gives the additional displacements wanted for

the sampling. They are given relative to the grid-cell vectors, i.e., (1,1,1) would displace to the

next grid point across the body diagonal, giving an equivalent grid-system situation (a useless

displacement for a sampling).

Examples: Assume a cubic cell, and therefore a (smaller) cubic grid cell. If there is no block or

the block is empty, then the original (0,0,0) will be used only. The block:

%block Grid.CellSampling

0.5 0.5 0.5

%endblock Grid.CellSampling

would use the body center as a second point in the sampling. Or:

%block Grid.CellSampling

0.5 0.5 0.0

0.5 0.0 0.5

0.0 0.5 0.5

%endblock Grid.CellSampling

gives an fcc kind of sampling, and

%block Grid.CellSampling

0.5 0.0 0.0

0.0 0.5 0.0

0.0 0.0 0.5

0.0 0.5 0.5

0.5 0.0 0.5

0.5 0.5 0.0

0.5 0.5 0.5

%endblock Grid.CellSampling

gives again a cubic sampling with half the original side length. It is not trivial to choose a

right set of displacements so as to maximize the new ’eﬀective’ cutoﬀ. It depends on the kind

of cell. It may be automatized in the future, but it is now left to the user, who introduces the

displacements manually through this block.

The quantities which are symmetrized are: (i) energy terms that depend on the grid, (ii) forces,

(iii) stress tensor, and (iv) electric dipole.

The symmetrization is performed at the end of every SCF cycle. The whole cycle is done for the

(0,0,0) displacement, and, when the density matrix is converged, the same (now ﬁxed) density

matrix is used to obtain the desired quantities at the other displacements (the density matrix

itself is not symmetrized as it gives a much smaller egg-box eﬀect). The CPU time needed for

each displacement in the Grid.CellSampling block is of the order of one extra SCF iteration.

This may be required in systems where very precise forces are needed, and/or if partial cores

are used. It is advantageous to test whether the forces are sampled suﬃciently by sampling one

point.

Additionally this may be given as a list of 3 integers which corresponds to a “Monkhorst-Pack”

like grid sampling. I.e.

Grid.CellSampling [2 2 2]

is equivalent to

%block Grid.CellSampling

0.5 0.0 0.0

0.0 0.5 0.0

0.5 0.5 0.0

0.0 0.0 0.5

0.5 0.0 0.5

0.0 0.5 0.5

0.5 0.5 0.5

%endblock Grid.CellSampling

This is an easy method to see if the ﬂag is important for your system or not.

%block EggboxRemove 〈None〉 (block)

For recovering translational invariance in an approximate way.

It works by substracting from Kohn-Sham’s total energy (and forces) an approximation to

the eggbox energy, sum of atomic contributions. Each atom has a predeﬁned eggbox energy

depending on where it sits on the cell. This atomic contribution is species dependent and is

obviously invariant under grid-cell translations. Each species contribution is thus expanded in

the appropriate Fourier series. It is important to have a smooth eggbox, for it to be represented

by a few Fourier components. A jagged egg-box (unless very small, which is then unimportant)

is often an indication of a problem with the pseudo.

In the block there is one line per Fourier component. The ﬁrst integer is for the atomic species

it is associated with. The other three represent the reciprocal lattice vector of the grid cell (in

units of the basis vectors of the reciprocal cell). The real number is the Fourier coeﬃcient in

units of the energy scale given in EggboxScale (see below), normally 1 eV.

The number and choice of Fourier components is free, as well as their order in the block. One

can choose to correct only some species and not others if, for instance, there is a substantial

diﬀerence in hardness of the cores. The 0 0 0 components will add a species-dependent constant

energy per atom. It is thus irrelevant except if comparing total energies of diﬀerent calculations,

in which case they have to be considered with care (for instance by putting them all to zero,

i.e. by not introducing them in the list). The other components average to zero representing

no bias in the total energy comparisons.

If the total energies of the free atoms are put as 0 0 0 coeﬃcients (with spin polarisation if

adequate etc.) the corrected total energy will be the cohesive energy of the system (per unit

cell).

Example: For a two species system, this example would give a quite suﬃcent set in many

instances (the actual values of the Fourier coeﬃcients are not realistic).

%block EggBoxRemove

1 0 0 0 -143.86904

1 0 0 1 0.00031

1 0 1 0 0.00016

1 0 1 1 -0.00015

1 1 0 0 0.00035

1 1 0 1 -0.00017

2 0 0 0 -270.81903

2 0 0 1 0.00015

2 0 1 0 0.00024

2 1 0 0 0.00035

2 1 0 1 -0.00077

2 1 1 0 -0.00075

2 1 1 1 -0.00002

%endblock EggBoxRemove

It represents an alternative to grid-cell sampling (above). It is only approximate, but once the

Fourier components for each species are given, it does not represent any computational eﬀort

(neither memory nor time), while the grid-cell sampling requires CPU time (roughly one extra

SCF step per point every MD step).

It will be particularly helpful in atoms with substantial partial core or semicore electrons.

NOTE: This should only be used for ﬁxed cell calculations, i.e. not with MD.VariableCell.

For the time being, it is up to the user to obtain the Fourier components to be introduced. They

can be obtained by moving one isolated atom through the cell to be used in the calculation (for

a give cell size, shape and mesh), once for each species. The Util/Scripting/eggbox_checker.py

script can be used as a starting point for this.

EggboxScale 1 eV (energy)

Deﬁnes the scale in which the Fourier components of the egg-box energy are given in the

EggboxRemove block.

6.11 Matrix elements of the Hamiltonian and overlap

NeglNonOverlapInt false (logical)

Logical variable to neglect or compute interactions between orbitals which do not overlap. These

come from the KB projectors. Neglecting them makes the Hamiltonian more sparse, and the

calculation faster.

NOTE: Use with care!

SaveHS false (logical)

Instructs to write the Hamiltonian and overlap matrices, as well as other data required to

generate bands and density of states, in ﬁle SystemLabel.HSX. The .HSX format is more compact

than the traditional .HS, and the Hamiltonian, overlap matrix, and relative-positions array

(which is always output, even for gamma-point only calculations) are in single precision.

The program hsx2hs in Util/HSX can be used to generate an old-style .HS ﬁle if needed.

SIESTA produces also an .HSX ﬁle if the COOP.Write option is active.

See also the Write.DMHS.NetCDF and Write.DMHS.History.NetCDF options.

Compat.Matel.NRTAB false (logical)

Internally the two-center integrals involved in some matrix element calculations are tabulated

with a preset number of elements. In versions 4.0.1 and prior this was 128. Since 4.0.2 the

number of table elements has been increased to 1024, which translates to more accurate matrix

element calculations.

This compatibility option should only be used when preservation of the (lower accuracy) nu-

merical results of 4.0.1 or prior versions is required for reproducibility purposes.

6.11.1 The auxiliary supercell

When using k-points, this auxiliary supercell is needed to compute properly the matrix elements

involving orbitals in diﬀerent unit cells. It is computed automatically by the program at every

geometry step.

Note that for gamma-point-only calculations there is an implicit “folding” of matrix elements corre-

sponding to the images of orbitals outside the unit cell. If information about the speciﬁc values of

these matrix elements is needed (as for COOP/COHP analysis), one has to make sure that the unit

cell is large enough, or force the use of an aunxiliary supercell.

ForceAuxCell false (logical)

If true, the program uses an auxiliary cell even for gamma-point-only calculations. This might

be needed for COOP/COHP calculations, as noted above, or in degenerate cases, such as

when the cell is so small that a given orbital “self-interacts” with its own images (via direct

overlap or through a KB projector). In this case, the diagonal value of the overlap matrix

S for this orbital is diﬀerent from 1, and an initialization of the DM via atomic data would

be faulty. The program corrects the problem to zeroth-order by dividing the DM value by the

corresponding overlap matrix entry, but the initial charge density would exhibit distortions from

a true atomic superposition (See routine m_new_dm.F). The distortion of the charge density is

a serious problem for Harris functional calculations, so this option must be enabled for them if

self-folding is present. (Note that this should not happen in any serious calculation...)

6.12 Calculation of the electronic structure

SIESTA can use three qualitatively diﬀerent methods to determine the electronic structure of the

system. The ﬁrst is standard diagonalization, which works for all systems and has a cubic scaling

with the size. The second is based on the direct minimization of a special functional over a set of

trial orbitals. These orbitals can either extend over the entire system, resulting in a cubic scaling

algorithm, or be constrained within 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 an equivalent approach

to diagonalization in terms of the accuracy of the solution; the latter is the historical O(N) method

used by SIESTA (described in 6.12.5); it scales in principle linearly with the size of the system (only

if the size is larger than the radial cutoﬀ for the local solution wave-functions), but is quite fragile

and substantially more diﬃcult to use, and only works for systems with clearly separated occupied

and empty states. The default is to use diagonalization. The third method (PEXSI) is based on the

pole expansion of the Fermi-Dirac function and the direct computation of the density matrix via an

eﬃcient scheme of selected inversion (see Sec 6.13).

The calculation of the H and S matrix elements is always done with an O(N) method. The actual

scaling is not linear for small systems, but it becomes O(N) when the system dimensions are larger

than the scale of orbital r

’s.

The relative importance of both parts of the computation (matrix elements and solution) depends on

the size and quality of the calculation. The mesh cutoﬀ aﬀects only the matrix-element calculation;

orbital cutoﬀ radii aﬀect the matrix elements and all solvers except diagonalization; the need for

k-point sampling aﬀects the solvers only, and the number of basis orbitals aﬀects them all.

In practice, the vast majority of users employ diagonalization (or the OMM method) for the cal-

culation of the electronic structure. This is so because the vast majority of calculations (done for

intermediate system sizes) would not beneﬁt from the O(N) or PEXSI solvers.

SolutionMethod diagon (string)

Character string to choose among diagonalization (diagon), cubic-scaling minimization

(OMM), Order-N (OrderN) solution of the Kohn-Sham Hamiltonian, transiesta, or the

PEXSI method (PEXSI).

6.12.1 Diagonalization options

NumberOfEigenStates 〈all orbitals〉 (integer)

depends on: Diag.Algorithm

This parameter allows the user to reduce the number of eigenstates that are calculated from

the maximum possible. The beneﬁt is that, for any calculation, the cost of the diagonalization

is reduced by ﬁnding fewer eigenvalues/eigenvectors. For example, during a geometry optimisa-

tion, only the occupied states are required rather than the full set of virtual orbitals. Note, that

if the electronic temperature is greater than zero then the number of partially occupied states

increases, depending on the band gap. The value speciﬁed must be greater than the number of

occupied states and less than the number of basis functions.

If a negative number is passed it corresponds to the number of orbitals above the total charge

of the system. In eﬀect it corresponds to the number of orbitals above the Fermi level for zero

temperature. I.e. if −2 is speciﬁed for a system with 20 orbitals and 10 electrons it is equivalent

to 12.

Using this option can greatly speed up your calculations if used correctly.

NOTE: If experiencing PDORMTR errors in Γ calculations with MRRR algorithm, it is because

of a buggy ScaLAPACK implementation, simply use another algorithm.

NOTE: This only aﬀects the MRRR, ELPA and Expert diagonalization routines.

Diag.WFS.Cache none|cdf (string)

deprecates: UseNewDiagk

Specify whether SIESTA should cache wavefunctions in the diagonalization routine. Without

a cache, a standard two-pass procedure is used. First eigenvalues are obtained to determine the

Fermi level, and then the wavefunctions are computed to build the density matrix.

Using a cache one can do everything in one go. However, this requires substantial IO and

performance may vary.

none The wavefunctions will not be cached and the standard two-pass diagonalization method

is used.

cdf The wavefunctions are stored in WFS.nc (NetCDF format) and created from a single root

node. This requires NetCDF support, see Sec. 2.5.

NOTE: This is an experimental feature.

NOTE: It is not compatible with the Diag.ParallelOverK option.

Diag.Use2D true (logical)

Determine whether a 1D or 2D data decomposition should be used when calling ScaLAPACK.

The use of 2D leads to superior scaling on large numbers of processors and is therefore the

default. This option only inﬂuences the parallel performance.

If Diag.BlockSize is diﬀerent from BlockSize this ﬂag defaults to true, else if

Diag.ProcessorY is 1 or the total number of processors, then this ﬂag will default to false.

Diag.ProcessorY ∼

√

N (integer)

depends on: Diag.Use2D

Set the number of processors in the 2D distribution along the rows. Its default is equal to the

lowest multiple of N (number of MPI cores) below

√

N such that, ideally, the distribution will

be a square grid.

The input is required to be a multiple of the total number of MPI cores but SIESTA will reduce

the input value such that it coincides with this.

Once the lowest multiple closest to

√

N, or the input, is determined the 2D distribution will be

ProcessorY × N/ProcessorY, rows × columns.

NOTE: If the automatic correction (lowest multiple of MPI cores) is 1 the default of

Diag.Use2D will be false.

Diag.BlockSize 〈BlockSize〉 (integer)

depends on: Diag.Use2D

The block-size used for the 2D distribution in the ScaLAPACK calls. This number greatly

aﬀects the performance of ScaLAPACK.

If the ScaLAPACK library is threaded this parameter should not be too small. In any case it

may be advantageous to run a few tests to ﬁnd a suitable value.

NOTE: If Diag.Use2D is set to false this ﬂag is not used.

Diag.Algorithm Divide-and-Conquer|... (string)

deprecates: Diag.DivideAndConquer, Diag.MRRR, Diag.ELPA, Diag.NoExpert

Select the algorithm when calculating the eigenvalues and/or eigenvectors.

The fastest routines are typically MRRR or ELPA which may be signiﬁcantly faster by specifying

a suitable NumberOfEigenStates value.

Currently the implemented solvers are:

divide-and-Conquer Use the divide-and-conquer algorithm.

divide-and-Conquer-2stage Use the divide-and-conquer 2stage algorithm (fall-back to the

divide-and-conquer if not available).

MRRR depends on: NumberOfEigenStates

Use the multiple relatively robust algorithm.

NOTE: The MRRR method is defaulted not to be compiled in, however, if your ScaLAPACK

library does contain the relevant sources one may add this pre-processor ﬂag -DSIESTA__MRRR.

MRRR-2stage depends on: NumberOfEigenStates

Use the 2-stage multiple relatively robust algorithm.

expert depends on: NumberOfEigenStates

Use the expert algorithm which allows calculating a subset of the eigenvalues/eigenvectors.

expert-2stage depends on: NumberOfEigenStates

Use the 2-stage expert algorithm which allows calculating a subset of the eigenval-

ues/eigenvectors.

noexpert|QR Use the QR algorithm.

noexpert-2stage|QR-2stage Use the 2-stage QR algorithm.

ELPA-1stage depends on: NumberOfEigenStates

Use the ELPA

[1;8]

1-stage solver. Requires compilation of SIESTA with ELPA, see Sec. 2.5.

Not compatible with Diag.ParallelOverK.

ELPA|ELPA-2stage depends on: NumberOfEigenStates

Use the ELPA

[1;8]

2-stage solver. Requires compilation of SIESTA with ELPA, see Sec. 2.5.

Not compatible with Diag.ParallelOverK.

NOTE: All the 2-stage solvers are (as of July 2017) only implemented in the LAPACK library,

so they will only be usable in serial or when using Diag.ParallelOverK.

To enable the 2-stage solvers add this ﬂag to the arch.make

FPPFLAGS += -DSIESTA__DIAG_2STAGE

If one uses the shipped LAPACK library the 2-stage solvers are added automatically.

NOTE: This ﬂag has precedence over the deprecated ﬂags: Diag.DivideAndConquer,

Diag.MRRR, Diag.ELPA and Diag.NoExpert. However, the default is taking from the

deprecated ﬂags.

Diag.ELPA.UseGPU false (logical)

Newer versions of the ELPA library have optional support for GPUs. This ﬂag will request that

GPU-speciﬁc code be used by the library.

To use this feature, GPU support has to be explicitly enabled during compilation of the ELPA

library. At present, detection of GPU support in the code is not fool-proof, so this ﬂag should

only be enabled if GPU support is indeed available.

Diag.ParallelOverK false (logical)

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 where the number of k points is much larger than the number of processors

and therefore orbital parallelisation is generally preferred. The exception is for metals where

the unit cell is small, but the number of k points to be sampled is very large. In this last case

it is recommend that this option be used.

NOTE: This scheme is not used for the diagonalizations involved in the generation of the band-

structure (as speciﬁed with BandLines or BandPoints) or in the generation of wave-function

information (as speciﬁed with WaveFuncKPoints). In these cases the program falls back to

using parallelization over orbitals.

Diag.AbsTol 10

−16

(real)

The absolute tolerance for the orthogonality of the eigenvectors. This tolerance is only applicable

for the solvers:

expert for both the serial and parallel solvers.

mrrr for the serial solver.

Diag.OrFac 10

−3

(real)

Re-orthogonalization factor to determine when the eigenvectors should be re-orthogonalized.

Only applicable for the expert serial and parallel solvers.

Diag.Memory 1 (real)

Whether the parallel diagonalization of a matrix is successful or not can depend on how much

workspace is available to the routine when there are clusters of eigenvalues. Diag.Memory

allows the user to increase the memory available, when necessary, to achieve successful diago-

nalization and is a scale factor relative to the minimum amount of memory that ScaLAPACK

might need.

Diag.UpperLower lower|upper (string)

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

NOTE: Do not change this variable unless you are performing benchmarks. It should be fastest

with the lower part.

Deprecated diagonalization options

Diag.MRRR false (logical)

depends on: NumberOfEigenStates

Use the MRRR method in ScaLAPACK for diagonalization. Specifying a number of eigenvectors

to store is possible through the symbol NumberOfEigenStates (see above).

NOTE: The MRRR method is defaulted not to be compiled in, however, if your ScaLAPACK

library does contain the relevant sources one may add this pre-processor ﬂag -DSIESTA__MRRR.

NOTE: Use Diag.Algorithm instead.

Diag.DivideAndConquer true (logical)

Logical to select whether the normal or Divide and Conquer algorithms are used within the

ScaLAPACK/LAPACK diagonalization routines.

NOTE: Use Diag.Algorithm instead.

Diag.ELPA false (logical)

depends on: NumberOfEigenStates

See the ELPA articles

[1;8]

for additional information.

NOTE: It is not compatible with the Diag.ParallelOverK option.

NOTE: Use Diag.Algorithm instead.

Diag.NoExpert false (logical)

Logical to select whether the simple or expert versions of the ScaLAPACK/LAPACK routines

are used. Usually the expert routines are faster, but may require slightly more memory.

NOTE: Use Diag.Algorithm instead.

6.12.2 Output of eigenvalues and wavefunctions

This section focuses on the output of eigenvalues and wavefunctions produced during the (last)

iteration of the self-consistent cycle, and associated to the appropriate k-point sampling.

For band-structure calculations (which typically use a diﬀerent set of k-points) and speciﬁc requests

for wavefunctions, see Secs. 6.14 and 6.15, respectively.

The complete set of wavefunctions obtained during the last iteration of the SCF loop will be written

to a NetCDF ﬁle WFS.nc if the Diag.WFS.Cache cdf option is in eﬀect.

The complete set of wavefunctions obtained during the last iteration of the SCF loop will be written

to SystemLabel.fullBZ.WFSX if the COOP.Write option is in eﬀect.

WriteEigenvalues false (logical)

If true it writes the Hamiltonian eigenvalues for the sampling

k points, in the main output

ﬁle. If false, it writes them in the ﬁle SystemLabel.EIG, which can be used by the Eig2DOS

postprocessing utility (in the Util/Eig2DOS directory) for obtaining the density of states.

NOTE: this option only works for SolutionMethod which calculates the eigenvalues.

6.12.3 Occupation of electronic states and Fermi level

OccupationFunction FD (string)

String variable to select the function that determines the occupation of the electronic states.

Two options are available:

FD The usual Fermi-Dirac occupation function is used.

MP The occupation function proposed by Methfessel and Paxton (Phys. Rev. B, 40, 3616

(1989)), is used.

The smearing of the electronic occupations is done, in both cases, using an energy width deﬁned

by the ElectronicTemperature variable. Note that, while in the case of Fermi-Dirac, the

occupations 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 Methfessel-Paxton function. In this

case, the tempeature is just a mathematical artifact to obtain a more accurate integration of

the physical quantities at a lower cost. In particular, the Methfessel-Paxton scheme has the

advantage that, even for quite large smearing temperatures, the obtained energy is very close

to the physical energy at T = 0. Also, it allows a much faster convergence with respect to

k-points, specially for metals. Finally, the convergence to selfconsistency is very much improved

(allowing the use of larger mixing coeﬃcients).

For the Methfessel-Paxton case, one can use relatively large values for the ElectronicTem-

perature parameter. How large depends on the speciﬁc system. A guide can be found in the

article by J. Kresse and J. Furthmüller, Comp. Mat. Sci. 6, 15 (1996).

If Methfessel-Paxton smearing is used, the order of the corresponding Hermite polynomial ex-

pansion must also be chosen (see description of variable OccupationMPOrder).

We ﬁnally note that, in both cases (FD and MP), once a ﬁnite temperature has been chosen,

the relevant energy is not the Kohn-Sham energy, but the Free energy. In particular, the atomic

forces are derivatives of the Free energy, not the KS energy. See R. Wentzcovitch et al., Phys.

Rev. B 45, 11372 (1992); S. de Gironcoli, Phys. Rev. B 51, 6773 (1995); J. Kresse and J.

Furthmüller, Comp. Mat. Sci. 6, 15 (1996), for details.

OccupationMPOrder 1 (integer)

Order of the Hermite-Gauss polynomial expansion for the electronic occupation functions in

the Methfessel-Paxton scheme (see Phys. Rev. B 40, 3616 (1989)). Specially for metals,

higher order expansions provide better convergence to the ground state result, even with larger

smearing temperatures, and provide also better convergence with k-points.

NOTE: only used if OccupationFunction is MP.

ElectronicTemperature 300 K (temperature/energy)

Temperature for Fermi-Dirac or Methfessel-Paxton distribution. Useful specially for metals,

and to accelerate selfconsistency in some cases.

6.12.4 Orbital minimization method (OMM)

The OMM is an alternative cubic-scaling solver that uses a minimization algorithm instead of direct

diagonalization to ﬁnd the occupied subspace. The main advantage over diagonalization is the

possibility of iteratively reusing the solution from each SCF/MD step as the starting guess of the

following one, thus greatly reducing the time to solution. Typically, therefore, the ﬁrst few SCF

cycles of the ﬁrst MD step of a simulation will be slower than diagonalization, but the rest will be

faster. The main disadvantages are that individual Kohn-Sham eigenvalues are not computed, and

that only a ﬁxed, integer number of electrons at each k point/spin is allowed. Therefore, only spin-

polarized calculations with Spin.Fix are allowed, and Spin.Total must be chosen appropriately.

For non-Γ point calculations, the number of electrons is set to be equal at all k points. Non-collinear

calculations (see Spin) are not supported at present. The OMM implementation was initially

developed by Fabiano Corsetti.

It is important to note that the OMM requires all occupied Kohn-Sham eigenvalues to be negative;

this can be achieved by applying a shift to the 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 slow

or unstable convergence, this is almost certainly due to the fact that the default value of ON.eta

(0.0 eV) is too low, and should be raised by a few eV.

OMM.UseCholesky true (logical)

Select whether to perform a Cholesky factorization of the generalized eigenvalue problem; this

removes the overlap matrix from the problem but also destroys the sparsity of the Hamiltonian

matrix.

OMM.Use2D true (logical)

Select whether to use a 2D data decomposition of the matrices for parallel calculations. This

generally leads to superior scaling for large numbers of MPI processes.

OMM.UseSparse false (logical)

Select whether to make use of the sparsity of the Hamiltonian and overlap matrices where

possible when performing matrix-matrix multiplications (these operations are thus reduced from

O(N

) to O(N

) without loss of accuracy).

NOTE: not compatible with OMM.UseCholesky, OMM.Use2D, or non-Γ point calcula-

tions

OMM.Precon -1 (integer)

Number of SCF steps for all MD steps for which to apply a preconditioning scheme based on the

overlap and kinetic energy matrices; for negative values the preconditioning is always applied.

Preconditioning is usually essential for fast and accurate convergence (note, however, that it

is not needed if a Cholesky factorization is performed; in such cases this variable will have no

eﬀect on the calculation).

NOTE: cannot be used with OMM.UseCholesky.

OMM.PreconFirstStep 〈OMM.Precon〉 (integer)

Number of SCF steps in the ﬁrst MD step for which to apply the preconditioning scheme; if

present, this will overwrite the value given in OMM.Precon for the ﬁrst MD step only.

OMM.Diagon 0 (integer)

Number of SCF steps for all MD steps for which to use a standard diagonalization before

switching to the OMM; for negative values diagonalization is always used, and so the calculation

is eﬀectively equivalent to SolutionMethod diagon. In general, selecting the ﬁrst few SCF

steps can speed up the calculation by removing the costly initial minimization (at present this

works best for Γ point calculations).

OMM.DiagonFirstStep 〈OMM.Diagon〉 (integer)

Number of SCF steps in the ﬁrst MD step for which to use a standard diagonalization before

switching to the OMM; if present, this will overwrite the value given in OMM.Diagon for the

ﬁrst MD step only.

OMM.BlockSize 〈BlockSize〉 (integer)

Blocksize used for distributing the elements of the matrix over MPI processes. Speciﬁcally, this

variable controls the dimension relating to the trial orbitals used in the minimization (equal to

the number of occupied states at each k point/spin); the equivalent variable for the dimension

relating to the underlying basis orbitals is controlled by BlockSize.

OMM.TPreconScale 10 Ry (energy)

Scale of the kinetic energy preconditioning (see C. K. Gan et al., Comput. Phys. Commun.

134, 33 (2001)). A smaller value indicates more aggressive kinetic energy preconditioning,

while an inﬁnite value indicates no kinetic energy preconditioning. In general, the kinetic

energy preconditioning is much less important than the tensorial correction brought about by

the overlap matrix, and so this value will have fairly little impact on the overall performace of the

preconditioner; however, too aggressive kinetic energy preconditioning can have a detrimental

eﬀect on performance and accuracy.

OMM.RelTol 10

−9

(real)

Relative tolerance in the conjugate gradients minimization of the Kohn-Sham band energy (see

ON.Etol).

OMM.Eigenvalues false (logical)

Select whether to perform a diagonalization at the end of each MD step to obtain the Kohn-

Sham eigenvalues.

OMM.WriteCoeﬀs false (logical)

Select whether to write the coeﬃcients of the solution orbitals to ﬁle at the end of each MD

step.

OMM.ReadCoeﬀs false (logical)

Select whether to read the coeﬃcients of the solution orbitals from ﬁle at the beginning of

a new calculation. Useful for restarting an interrupted calculation, especially when used in

conjuction with DM.UseSaveDM. Note that the same number of MPI processes and values

of OMM.Use2D, OMM.BlockSize, and BlockSize must be used when restarting.

OMM.LongOutput false (logical)

Select whether to output detailed information of the conjugate gradients minimization for each

SCF step.

6.12.5 Order(N) calculations

The Ordern(N) subsystem is quite fragile and only works for systems with clearly separated occupied

and empty states. Note also that the option to compute the chemical potential automatically does

not yet work in parallel.

NOTE: Since it is used less often, bugs creeping into the O(N) solver have been more resilient than

in more popular bits of the code. Work is ongoing to clean and automate the O(N) process, to make

the solver more user-friendly and robust.

ON.functional Kim (string)

Choice of order-N minimization functionals:

Kim Functional of Kim, Mauri and Galli, PRB 52, 1640 (1995).

Ordejon-Mauri Functional of Ordejón et al, or Mauri et al, see PRB 51, 1456 (1995). The num-

ber of localized wave functions (LWFs) used must coincide with N

/2 (unless spin polarized).

For the initial assignment of LWF centers to atoms, atoms with even number of electrons, n,

get n/2 LWFs. Odd atoms get (n + 1)/2 and (n − 1)/2 in an alternating sequence, ir order

of appearance (controlled by the input in the atomic coordinates block).

ﬁles Reads localized-function information from a ﬁle and chooses automatically the functional

to be used.

ON.MaxNumIter 1000 (integer)

Maximum number of iterations in the conjugate minimization of the electronic energy, in each

SCF cycle.

ON.Etol 10

−8

(real)

Relative-energy tolerance in the conjugate minimization of the electronic energy. The mini-

mization ﬁnishes if 2(E

− E

n−1

)/(E

+ E

n−1

) ≤ ON.Etol.

ON.eta 0 eV (energy)

Fermi level parameter of Kim et al.. This should be in the energy gap, and tuned to obtain the

correct number of electrons. If the calculation is spin polarised, then separate Fermi levels for

each spin can be speciﬁed.

ON.eta.alpha 0 eV (energy)

Fermi level parameter of Kim et al. for alpha spin electrons. This should be in the energy gap,

and tuned to obtain the correct number of electrons. Note that if the Fermi level is not speciﬁed

individually for each spin then the same global eta will be used.

ON.eta.beta 0 eV (energy)

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 of electrons. Note that if the Fermi level is not speciﬁed

individually for each spin then the same global eta will be used.

ON.RcLWF 9.5 Bohr (length)

Localization redius for the Localized Wave Functions (LWF’s).

ON.ChemicalPotential false (logical)

Speciﬁes whether to calculate an order-N estimate of the Chemical Potential, by the projection

method (Goedecker and Teter, PRB 51, 9455 (1995); Stephan, Drabold and Martin, PRB 58,

13472 (1998)). This is done by expanding the Fermi function (or density matrix) at a given

temperature, by means of Chebyshev polynomials, and imposing a real space truncation on

the density matrix. To obtain a realistic estimate, the temperature should be small enough

(typically, smaller than the energy gap), the localization range large enough (of the order of

the one you would use for the Localized Wannier Functions), and the order of the polynomial

expansion suﬃciently large (how large depends on the temperature; typically, 50-100).

NOTE: this option does not work in parallel. An alternative is to obtain the approximate value

of the chemical potential using an initial diagonalization.

ON.ChemicalPotential.Use false (logical)

Speciﬁes whether to use the calculated estimate of the Chemical Potential, instead of the pa-

rameter ON.eta for the order-N energy functional minimization. This is useful if you do not

know the position of the Fermi level, typically in the beginning of an order-N run.

NOTE: this overrides the value of ON.eta and ON.ChemicalPotential. Also, this option

does not work in parallel. An alternative is to obtain the approximate value of the chemical

potential using an initial diagonalization.

ON.ChemicalPotential.Rc 9.5 Bohr (length)

Deﬁnes the cutoﬀ radius for the density matrix or Fermi operator in the calculation of the

estimate of the Chemical Potential.

ON.ChemicalPotential.Temperature 0.05 Ry (temperature/energy)

Deﬁnes the temperature to be used in the Fermi function expansion in the calculation of the

estimate of the Chemical Potential. To have an accurate results, this temperature should be

smaller than the gap of the system.

ON.ChemicalPotential.Order 100 (integer)

Order of the Chebishev expansion to calculate the estimate of the Chemical Potential.

ON.LowerMemory false (logical)

If true, then a slightly reduced memory algorithm is used in the 3-point line search during the

order N minimisation. Only aﬀects parallel runs.

Output of localized wavefunctions At the end of each conjugate gradient minimization of

the energy functional, the LWF’s are stored on disk. These can be used as an input for the same

system in a restart, or in case something goes wrong. The LWF’s are stored in sparse form in ﬁle

SystemLabel.LWF

It is important to keep very good care of this ﬁle, since the ﬁrst minimizations can take MANY

steps. Loosing them will mean performing the whole minimization again. It is also a good practice

to save it periodically during the simulation, in case a mid-run restart is necessary.

ON.UseSaveLWF false (logical)

Instructs to read the localized wave functions stored in ﬁle SystemLabel.LWF by a previous run.

6.13 The PEXSI solver

The PEXSI solver is based on the combination of the pole expansion of the Fermi-Dirac function

and the computation of only a selected (sparse) subset of the elements of the matrices (H − z

−1

at each pole z

This solver can eﬃciently use the sparsity pattern of the Hamiltonian and overlap matrices generated

in SIESTA, and for large systems has a much lower computational complexity than that associated

with the matrix diagonalization procedure. It is also highly scalable.

The PEXSI technique can be used in this version of SIESTA to evaluate the electron density, free

energy, atomic forces, density of states and local density of states without computing any eigenvalue

or eigenvector of the Kohn-Sham Hamiltonian. It can achieve accuracy fully comparable to that

obtained from a matrix diagonalization procedure for general systems, including metallic systems at

low temperature.

The current implementation of the PEXSI solver in SIESTA makes use of a full ﬁne-grained-level

interface to earlier versions (0.8.X and 0.9.X) of the PEXSI library (http://pexsi.org), and can

deal with spin-polarization, but it is still restricted to Γ-point calculations. Newer versions of

SIESTA (in the Gitlab development site) can use the current PEXSI library through the ELSI library

interface, which oﬀers some more options, although not currently the density-of-states calculation.

The following is a brief description of the input-ﬁle parameters relevant to the workings of the

PEXSI solver. For more background, including a discussion of the conditions under which this

solver is competitive, the user is referred to the paper Lin et al.

[7]

, and references therein.

The technology involved in the PEXSI solver can also be used to compute densities of states and

“local densities of states”. These features are documented in this section and also linked to in the

relevant general sections.

6.13.1 Pole handling

Note that the temperature for the Fermi-Dirac distribution which is pole-expanded is taken directly

from the ElectronicTemperature parameter (see Sec. 6.12.3).

PEXSI.NumPoles 40 (integer)

Eﬀective number of poles used to expand the Fermi-Dirac function.

PEXSI.deltaE 3 Ry (energy)

In principle PEXSI.deltaE should be E

max

−µ, where E

max

is the largest eigenvalue for (H,S),

and µ is the chemical potential. However, due to the fast decay of the Fermi-Dirac function,

PEXSI.deltaE can often be chosen to be much lower. In practice we set the default to be 3

Ryd. This number should be set to be larger if the diﬀerence between Tr[H·DM] and Tr[S∗EDM]

(displayed in the output if PEXSI.Verbosity is at least 2) does not decrease with the increase

of the number of poles.

PEXSI.Gap 0 Ry (energy)

Spectral gap. This can be set to be 0 in most cases.

6.13.2 Parallel environment and control options

MPI.Nprocs.SIESTA 〈total processors〉 (integer)

Speciﬁes the number of MPI processes to be used in those parts of the program (such as

Hamiltonian setup and computation of forces) which are outside of the PEXSI solver itself.

This is needed in large-scale calculations, for which the number of processors that can be used

by the PEXSI solver is much higher than those needed by other parts of the code.

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 program, leaving the rest idle for the whole

calculation. This will adversely aﬀect the computing budget, so take care not to use this option

in that case.

PEXSI.NP-per-pole 4 (integer)

Number of MPI processes used to perform the PEXSI computations in one pole. If the total

number of MPI processes is smaller than this number times the number of poles (times the spin

multiplicity), the PEXSI library will compute appropriate groups of poles in sequence. The

minimum time to solution is achieved by increasing this parameter as much as it is reasonable

for parallel eﬃciency, and using enough MPI processes to allow complete parallelization over

poles. On the other hand, the minimum computational cost (in the sense of computing budget)

is obtained by using the minimum value of this parameter which is compatible with the mem-

ory footprint. The additional parallelization over poles will be irrelevant for cost, but it will

obviously aﬀect the time to solution.

Internally, SIESTA computes the processor grid parameters nprow and npcol for the PEXSI

library, with nprow >= npcol, and as similar as possible. So it is best to choose PEXSI.NP-

per-pole as the product of two similar numbers.

NOTE: The total number of MPI processes must be divisible by PEXSI.NP-per-pole. In

case of spin-polarized calculations, the total number of MPI processes must be divisible by

PEXSI.NP-per-pole times 2.

PEXSI.Ordering 1 (integer)

For large matrices, symbolic factorization should be performed in parallel to reduce the wall

clock time. This can be done using ParMETIS/PT-Scotch by setting PEXSI.Ordering to

0. However, we have been experiencing some instability problem of the symbolic factorization

phase when ParMETIS/PT-Scotch is used. In such case, for relatively small matrices one can

either use the sequential METIS (PEXSI.Ordering = 1) or set PEXSI.NP-symbfact to 1.

PEXSI.NP-symbfact 1 (integer)

Number of MPI processes used to perform the symbolic factorizations needed in the PEXSI

procedure. A default value should be given to reduce the instability problem. From experience

so far setting this to be 1 is most stable, but going beyond 64 does not usually improve much.

PEXSI.Verbosity 1 (integer)

It determines the amount of information logged by the solver in diﬀerent places. A value of zero

gives minimal information.

• In the ﬁles logPEXSI[0-9]+, the verbosity level is interpreted by the PEXSI library itself.

In the latest version, when PEXSI is compiled in RELEASE mode, only logPEXSI0 is

given in the output. This is because we have observed that simultaneous output for all

processors can have very signiﬁcant cost for a large number of processors (>10000).

• In the SIESTA output ﬁle, a verbosity level of 1 and above will print lines (preﬁxed by &o)

indicating the various heuristics used at each scf step. A verbosity level of 2 and above

will print extra information.

The design of the output logging is still in ﬂux.

6.13.3 Electron tolerance and the PEXSI solver

PEXSI.num-electron-tolerance 10

−4

(real)

Tolerance in the number of electrons for the PEXSI solver. At each iteration of the solver, the

number of electrons is computed as the trace of the density matrix times the overlap matrix,

and compared with the total number of electrons in the system. This tolerance can be ﬁxed,

or dynamically determined as a function of the degree of convergence of the self-consistent-ﬁeld

loop.

PEXSI.num-electron-tolerance-lower-bound 10

−2

(real)

See PEXSI.num-electron-tolerance-upper-bound.

PEXSI.num-electron-tolerance-upper-bound 0.5 (real)

The upper and lower bounds for the electron tolerance are used to dynamically change the

tolerance in the PEXSI solver, following the simple algorithm:

tolerance = Max(lower_bound,Min(dDmax, upper_bound))

The ﬁrst scf step uses the upper bound of the tolerance range, and subsequent steps use pro-

gressively lower values, in correspondence with the convergence-monitoring variable dDmax.

NOTE: This simple update schedule tends to work quite well. There is an experimental

algorithm, documented only in the code itself, which allows a ﬁner degree of control of the

tolerance update.

PEXSI.mu-max-iter 10 (integer)

Maximum number of iterations of the PEXSI solver. Note that in this implementation there is no

fallback procedure if the solver fails to converge in this number of iterations to the prescribed

tolerance. In this case, the resulting density matrix might still be re-normalized, and the

calculation able to continue, if the tolerance for non normalized DMs is not set too tight. For

example,

# (true_no_electrons/no_electrons) - 1.0

DM.NormalizationTolerance 1.0e-3

will allow a 0.1% error in the number of electrons. For obvious reasons, this feature, which is

also useful in connection with the dynamic tolerance update, should not be abused.

If the parameters of the PEXSI solver are adjusted correctly (including a judicious use of

inertia-counting to reﬁne the µ bracket), we should expect that the maximum number of solver

iterations needed is around 3

PEXSI.mu −0.6 Ry (energy)

The starting guess for the chemical potential for the PEXSI solver. Note that this value does not

aﬀect the initial µ bracket for the inertia-count reﬁnement, which is controlled by PEXSI.mu-

min and PEXSI.mu-max. After an inertia-count phase, µ will be reset, and further iterations

inherit this estimate, so this parameter is only relevant if there is no inertia-counting phase.

PEXSI.mu-pexsi-safeguard 0.05 Ry (energy)

NOTE: This feature has been deactivated for now. The condition for starting a new phase of

inertia-counting is that the Newton estimation falls outside the current bracket. The bracket is

expanded accordingly.

The PEXSI solver uses Newton’s method to update the estimate of µ. If the attempted change

in µ is larger than PEXSI.mu-pexsi-safeguard, the solver cycle is stopped and a fresh phase

of inertia-counting is started.

6.13.4 Inertia-counting

PEXSI.Inertia-Counts 3 (integer)

In a given scf step, the PEXSI procedure can optionally employ a µ bracket-reﬁnement proce-

dure based on inertia-counting. Typically, this is used only in the ﬁrst few scf steps, and this

parameter determines how many. If positive, inertia-counting will be performed for exactly that

number of scf steps. If negative, inertia-counting will be performed for at least that number of

scf steps, and then for as long as the scf cycle is not yet deemed to be near convergence (as

determined by the PEXSI.safe-dDmax-no-inertia parameter).

NOTE: Since it is cheaper to perform an inertia-count phase than to execute one iteration of

the solver, it pays to call the solver only when the µ bracket is suﬃciently reﬁned.

PEXSI.mu-min −1 Ry (energy)

The lower bound of the initial range for µ used in the inertia-count reﬁnement. In runs with

multiple geometry iterations, it is used only for the very ﬁrst scf iteration at the ﬁrst geometry

step. Further iterations inherit possibly reﬁned values of this parameter.

PEXSI.mu-max 0 Ry (energy)

The upper bound of the initial range for µ used in the inertia-count reﬁnement. In runs with

multiple geometry iterations, it is used only for the very ﬁrst scf iteration at the ﬁrst geometry

step. Further iterations inherit possibly reﬁned values of this parameter.

PEXSI.safe-dDmax-no-inertia 0.05 (real)

During the scf cycle, the variable conventionally called dDmax monitors how far the cycle is

from convergence. If PEXSI.Inertia-Counts is negative, an inertia-counting phase will be

performed in a given scf step for as long as dDmax is greater than PEXSI.safe-dDmax-no-

inertia.

NOTE: Even though dDmax represents historically how far from convergence the density-

matrix is, the same mechanism applies to other forms of mixing in which other magnitudes are

monitored for convergence (Hamiltonian, charge density...).

PEXSI.lateral-expansion-inertia 3 eV (energy)

If the correct µ is outside the bracket provided to the inertia-counting phase, the bracket is

expanded in the appropriate direction(s) by this amoount.

PEXSI.Inertia-mu-tolerance 0.05 Ry (energy)

One of the criteria for early termination of the inertia-counting phase. The value of the estimated

µ (basically the center of the resulting brackets) is monitored, and the cycle stopped if its change

from one iteration to the next is below this parameter.

PEXSI.Inertia-max-iter 5 (integer)

Maximum number of inertia-count iterations per cycle.

PEXSI.Inertia-min-num-shifts 10 (integer)

Minimum number of sampling points for inertia counts.

PEXSI.Inertia-energy-width-tolerance 〈PEXSI.Inertia-mu-tolerance〉 (energy)

One of the criteria for early termination of the inertia-counting phase. The cycle stops if the

width of the resulting bracket is below this parameter.

6.13.5 Re-use of µ information accross iterations

This is an important issue, as the eﬃciency of the PEXSI procedure depends on how close a guess

of µ we have at our disposal. There are two types of information re-use:

• Bracketing information used in the inertia-counting phase.

• The values of µ itself for the solver.

PEXSI.safe-width-ic-bracket 4 eV (energy)

By default, the µ bracket used for the inertia-counting phase in scf steps other than the ﬁrst is

taken as an interval of width PEXSI.safe-width-ic-bracket around the latest estimate of µ.

PEXSI.safe-dDmax-ef-inertia 0.1 (real)

The change in µ from one scf iteration to the next can be crudely estimated by assuming that

the change in the band structure energy (estimated as Tr∆HDM) is due to a rigid shift. When

the scf cycle is near convergence, this ∆µ can be used to estimate the new initial bracket for

the inertia-counting phase, rigidly shifting the output bracket from the previous scf step. The

cycle is assumed to be near convergence when the monitoring variable dDmax is smaller than

PEXSI.safe-dDmax-ef-inertia.

NOTE: Even though dDmax represents historically how far from convergence the density-

matrix is, the same mechanism applies to other forms of mixing in which other magnitudes are

monitored for convergence (Hamiltonian, charge density...).

NOTE: This criterion will lead in general to tighter brackets than the previous one, but oscil-

lations in H in the ﬁrst few iterations might make it more dangerous. More information from

real use cases is needed to reﬁne the heuristics in this area.

PEXSI.safe-dDmax-ef-solver 0.05 (real)

When the scf cycle is near convergence, the ∆µ estimated as above can be used to shift the

initial guess for µ for the PEXSI solver. The cycle is assumed to be near convergence when the

monitoring variable dDmax is smaller than PEXSI.safe-dDmax-ef-solver.

NOTE: Even though dDmax represents historically how far from convergence the density-

matrix is, the same mechanism applies to other forms of mixing in which other magnitudes are

monitored for convergence (Hamiltonian, charge density...).

PEXSI.safe-width-solver-bracket 4 eV (energy)

In all cases, a “safe” bracket around µ is provided even in direct calls 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 PEXSI.safe-width-solver-bracket

6.13.6 Calculation of the density of states by inertia-counting

The cumulative or integrated density of states (INTDOS) can be easily obtained by inertia-counting,

which involves a factorization of H −σS for varying σ (see SIESTA-PEXSI paper). Apart from the

DOS-speciﬁc options below, the “ordering”, “symbolic factorization”, and “pole group size” (re-

interpreted as the number of MPI processes dealing with a given σ) options are honored.

The current version of the code generates a ﬁle with the energy-INTDOS information, PEXSI_INTDOS,

which can be later processed to generate the DOS by direct numerical diﬀerentiation, or a SIESTA-

style SystemLabel.EIG ﬁle (using the Util/PEXSI/intdos2eig program).

PEXSI.DOS false (logical)

Whether to compute the DOS (actually, the INTDOS — see above) using the PEXSI technology.

PEXSI.DOS.Emin −1 Ry (energy)

Lower bound of energy window to compute the DOS in.

See PEXSI.DOS.Ef.Reference.

PEXSI.DOS.Emax 1 Ry (energy)

Upper bound of energy window to compute the DOS in.

See PEXSI.DOS.Ef.Reference.

PEXSI.DOS.Ef.Reference true (logical)

If this ﬂag is true, the bounds of the energy window (PEXSI.DOS.Emin and

PEXSI.DOS.Emax) are with respect to the Fermi level.

PEXSI.DOS.NPoints 200 (integer)

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 available factorization groups, as the operations are

perfectly parallel and there will be no extra cost involved.

6.13.7 Calculation of the LDOS by selected-inversion

The local-density-of-states (LDOS) around a given reference energy ε, representing the contribution

to the charge density of the states with eigenvalues in the vicinity of ε, can be obtained formally by

a “one-pole expansion” with suitable broadening (see SIESTA-PEXSI paper).

Apart from the LDOS-speciﬁc options below, the “ordering”, “verbosity”, and “symbolic factoriza-

tion” options are honored.

The current version of the code generates a real-space grid ﬁle with extension SystemLabel.LDSI,

and (if netCDF is compiled-in) a ﬁle Rho.grid.nc (which unfortunately will overwrite any other

charge-density ﬁles produced in the same run).

NOTE: The LDOS computed with this procedure is not exactly the same as the vanilla SIESTA

LDOS, which uses an explicit energy interval. Here the broadening acts around a single value of the

energy.

PEXSI.LDOS false (logical)

Whether to compute the LDOS using the PEXSI technology.

PEXSI.LDOS.Energy 0 Ry (energy)

The (absolute) energy at which to compute the LDOS.

PEXSI.LDOS.Broadening 0.01 Ry (energy)

The broadening parameter for the LDOS.

PEXSI.LDOS.NP-per-pole 〈PEXSI.NP-per-pole〉 (integer)

The value of this parameter supersedes PEXSI.NP-per-pole for the calculation of the LDOS,

which otherwise would keep idle all but PEXSI.NP-per-pole MPI processes, as it essentially

consists of a “one-pole” procedure.

6.14 Band-structure analysis

This calculation of the band structure is performed optionally after the geometry loop ﬁnishes, and

the output information written to the SystemLabel.bands ﬁle (see below for the format).

BandLinesScale pi/a (string)

Speciﬁes the scale of the k vectors given in BandLines and BandPoints below. The options

are:

pi/a k-vector coordinates are given in Cartesian coordinates, in units of π/a, where a is the

lattice constant

ReciprocalLatticeVectors k vectors are given in reciprocal-lattice-vector coordinates

NOTE: you might need to deﬁne explicitly a LatticeConstant tag in your fdf ﬁle if you do not

already have one, and make it consistent with the scale of the k-points and any unit-cell vectors

you might have already deﬁned.

%block BandLines 〈None〉 (block)

Speciﬁes the lines along which band energies are calculated (usually along high-symmetry di-

rections). An example for an FCC lattice is:

%block BandLines

1 1.000 1.000 1.000 L # Begin at L

20 0.000 0.000 0.000 \Gamma # 20 points from L to gamma

25 2.000 0.000 0.000 X # 25 points from gamma to 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

X label for use in the band plot. If only given points

(not lines) are required, simply specify 1 in the ﬁrst column of each line. The ﬁrst column of

the ﬁrst line must be always 1.

NOTE: this block is not used if BandPoints is present.

%block BandPoints 〈None〉 (block)

Band energies are calculated for the list of arbitrary k points given in the block. Units deﬁned

by BandLinesScale as for BandLines. The generated SystemLabel.bands ﬁle will contain

the k point coordinates (in a.u.) and the corresponding band energies (in eV). Example:

%block BandPoints

0.000 0.000 0.000 # This is a comment. eg this is gamma

1.000 0.000 0.000

0.500 0.500 0.500

%endblock BandPoints

similar results as the vacuum method.

%block Slab.DipoleCorrection.Vacuum 〈None〉 (block)

depends on: Slab.DipoleCorrection vacuum

Options for the vacuum ﬁeld determination.

direction Mandatory input for chain and molecule calculations.

Specify along which direction we should determine the electric ﬁeld/dipole.

For slabs this defaults to the non-bulk direction.

position Specify a point in the vacuum region.

Defaults to the vacuum region based on the atomic coordinates.

tolerance Tolerance for determining whether we are in a vacuum region. The premise of the

electric ﬁeld calculation in the vacuum region is that the derivative of the potential (E) is

ﬂat. When the electric ﬁeld changes by more than this tolerance the region is not vacuum

anymore and the point is disregarded.

Defaults to 10

−4

eV/Ang/e.

Its format is

%block Slab.DipoleCorrection.Vacuum

# this is optional

# default position is the center of system + 0.5 lattice vector

# along ’direction’

position 0.000 10.000 0.500 Ang

# this is optional

# default is 1e-4 eV/Ang/e

tolerance 0.001 eV/Ang/e

# this is mandatory

direction 0.000 1.000 0.

%endblock

NOTE: this will only be read if Slab.DipoleCorrection vacuum is used.

%block Geometry.Hartree 〈None〉 (block)

Allows introduction of regions with changed Hartree potential. Introducing a potential can act

as a repulsion (positive value) or attraction (negative value) region.

The regions are deﬁned as geometrical objects and there are no limits to the number of deﬁned

geometries.

Details regarding this implementation may be found in Papior et al.

[10]

Currently 4 diﬀerent kinds of geometries are allowed:

Inﬁnite plane Deﬁne a geometry by an inﬁnite plane which cuts the unit-cell.

104

This geometry is deﬁned by a single point which is in the plane and a vector normal to the

plane.

This geometry has 3 diﬀerent settings:

delta An inﬁnite plane with δ-height.

gauss An inﬁnite plane with a Gaussian distributed height proﬁle.

exp An inﬁnite plane with an exponentially distributed height proﬁle.

Bounded plane Deﬁne a geometric plane which is bounded, i.e. not inﬁnite.

This geometry is deﬁned by an origo of the bounded plane and two vectors which span the

plane, both originating in the respective origo.

This geometry has 3 diﬀerent settings:

delta A plane with δ-height.

gauss A plane with a Gaussian distributed height proﬁle.

exp A plane with an exponentially distributed height proﬁle.

Box This geometry is deﬁned by an origo of the box and three vectors which span the box, all

originating from the respective origo.

This geometry has 1 setting:

delta No decay-region outside the box.

Spheres This geometry is deﬁned by a list of spheres and a common radii.

This geometry has 2 settings:

gauss All spheres have an gaussian distribution about their centre.

exp All spheres have an exponential decay.

Here is a list of all options combined in one block:

%block Geometry.Hartree

plane 1. eV # The lifting potential on the geometry

delta

1.0 1.0 1.0 Ang # An intersection point, in the plane

1.0 0.5 0.2 # The normal vector to the plane

plane -1. eV # The lifting potential on the geometry

gauss 1. 2. Ang # the std. and the cut-off length

1.0 1.0 1.0 Ang # An intersection point, in the plane

1.0 0.5 0.2 # The normal vector to the plane

plane 1. eV # The lifting potential on the geometry

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

1.0 0.5 0.2 # The normal vector to the plane

square 1. eV # The lifting potential on the geometry

delta

1.0 1.0 1.0 Ang # The starting point of the square

2.0 0.5 0.2 Ang # The first spanning vector

0.0 2.5 0.2 Ang # The second spanning vector

square 1. eV # The lifting potential on the geometry

gauss 1. 2. Ang # the std. and the cut-off length

1.0 1.0 1.0 Ang # The starting point of the square

105

2.0 0.5 0.2 Ang # The first spanning vector

0.0 2.5 0.2 Ang # The second spanning vector

square 1. eV # The lifting potential on the geometry

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

2.0 0.5 0.2 Ang # The first spanning vector

0.0 2.5 0.2 Ang # The second spanning vector

box 1. eV # The lifting potential on the geometry

delta

1.0 1.0 1.0 Ang # Origo of the box

2.0 0.5 0.2 Ang # The first spanning vector

0.0 2.5 0.2 Ang # The second spanning vector

0.0 0.5 3.2 Ang # The third spanning vector

coords 1. eV # The lifting potential on the geometry

gauss 2. 4. Ang # First is std. deviation, second is cut-off radii

2 spheres # How many spheres in the following lines

0.0 4. 2. Ang # The centre coordinate of 1. sphere

1.3 4. 2. Ang # The centre coordinate of 2. sphere

coords 1. eV # The lifting potential on the geometry

exp 2. 4. Ang # First is half-length, second is cut-off radii

2 spheres # How many spheres in the following lines

0.0 4. 2. Ang # The centre coordinate of 1. sphere

1.3 4. 2. Ang # The centre coordinate of 2. sphere

%endblock Geometry.Hartree

%block Geometry.Charge 〈None〉 (block)

This is similar to the Geometry.Hartree block. However, instead of specifying a potential,

one deﬁnes the total charge that is spread on the geometry.

To see how the input should be formatted, see Geometry.Hartree and remove the unit-

speciﬁcation. Note that the input value is number of electrons (similar to NetCharge, however

this method ensures charge-neutrality).

Details regarding this implementation may be found in Papior et al.

[10]

6.22 Output of charge densities and potentials on the grid

SIESTA represents these magnitudes on the real-space grid. The following options control the gen-

eration of the appropriate ﬁles, which can be processed by the programs in the Util/Grid directory,

and also by Andrei Postnikov’s utilities in Util/Contrib/APostnikov. See also Util/Denchar for

an alternative way to plot the charge density (and wavefunctions).

SaveRho false (logical)

Instructs to write the valence pseudocharge density at the mesh used by DHSCF, in ﬁle

SystemLabel.RHO.

NOTE: ﬁle .RHO is only written, not read, by siesta. This ﬁle can be read by routine IORHO,

which may be used by other application programs.

If netCDF support is compiled in, the ﬁle Rho.grid.nc is produced.

SaveDeltaRho false (logical)

Instructs to write δρ(~r) = ρ(~r) − ρ

atm

(~r), i.e., the valence pseudocharge density minus the sum

106

of atomic valence pseudocharge densities. It is done for the mesh points used by DHSCF and it

comes in ﬁle SystemLabel.DRHO. This ﬁle can be read by routine IORHO, which may be used

by an application program in later versions.

NOTE: ﬁle .DRHO is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle DeltaRho.grid.nc is produced.

SaveRhoXC false (logical)

Instructs to write the valence pseudocharge density at the mesh, including the nonlocal core

corrections used to calculate the exchange-correlation energy, in ﬁle SystemLabel.RHOXC.

Use: File .RHOXC is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle RhoXC.grid.nc is produced.

SaveElectrostaticPotential false (logical)

Instructs to write the total electrostatic potential, deﬁned as the sum of the hartree potential

plus the local pseudopotential, at the mesh used by DHSCF, in ﬁle SystemLabel.VH. This ﬁle

can be read by routine IORHO, which may be used by an application program in later versions.

Use: File .VH is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle ElectrostaticPotential.grid.nc is produced.

SaveNeutralAtomPotential false (logical)

Instructs to write the neutral-atom potential, deﬁned as the sum of the hartree potential of a

“pseudo atomic valence charge” plus the local pseudopotential, at the mesh used by DHSCF,

in ﬁle SystemLabel.VNA. It is written at the start of the self-consistency cycle, as this potential

does not change.

Use: File .VNA is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle Vna.grid.nc is produced.

SaveTotalPotential false (logical)

Instructs to write the valence total eﬀective local potential (local pseudopotential + Hartree +

Vxc), at the mesh used by DHSCF, in ﬁle SystemLabel.VT. This ﬁle can be read by routine

IORHO, which may be used by an application program in later versions.

Use: File .VT is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle TotalPotential.grid.nc is produced.

NOTE: a side eﬀect; the vacuum level, deﬁned as the eﬀective potential at grid points with

zero density, is printed in the standard output whenever such points exist (molecules, slabs) and

either SaveElectrostaticPotential or SaveTotalPotential are true. In a symetric (nonpo-

lar) slab, the work function can be computed as the diﬀerence between the vacuum level and

the Fermi energy.

SaveIonicCharge false (logical)

Instructs to write the soft diﬀuse ionic charge at the mesh used by DHSCF, in ﬁle

SystemLabel.IOCH. This ﬁle can be read by routine IORHO, which may be used by an ap-

plication program in later versions. Remember that, within the SIESTA sign convention, the

electron charge density is positive and the ionic charge density is negative.

Use: File .IOCH is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle Chlocal.grid.nc is produced.

107

SaveTotalCharge false (logical)

Instructs to write the total charge density (ionic+electronic) at the mesh used by DHSCF, in

ﬁle SystemLabel.TOCH. This ﬁle can be read by routine IORHO, which may be used by an

application program in later versions. Remember that, within the SIESTA sign convention,

the electron charge density is positive and the ionic charge density is negative.

Use: File .TOCH is only written, not read, by siesta.

If netCDF support is compiled in, the ﬁle TotalCharge.grid.nc is produced.

SaveBaderCharge false (logical)

Instructs the program to save the charge density for further post-processing by a Bader-analysis

program. This “Bader charge” is the sum of the electronic valence charge density and a set of

“model core charges” placed at the atomic sites. For a given atom, the model core charge is

a generalized Gaussian, but conﬁned to a radius of 1.0 Bohr (by default), and integrating to

the total core charge (Z-Z

val

). These core charges are needed to provide local maxima for the

charge density at the atomic sites, which are not guaranteed in a pseudopotential calculation.

For hydrogen, an artiﬁcial core of 1 electron is added, with a conﬁnement radius of 0.6 Bohr by

default. The Bader charge is projected on the grid points of the mesh used by DHSCF, and saved

in ﬁle SystemLabel.BADER. This ﬁle can be post-processed by the program Util/grid2cube

to convert it to the “cube” format, accepted by several Bader-analysis programs (for example,

see http://theory.cm.utexas.edu/bader/). Due to the need to represent a localized core

charge, it is advisable to use a moderately high Mesh!Cutoﬀ when invoking this option (300-500

Ry). The size of the “basin of attraction” around each atom in the Bader analysis should be

monitored to check that the model core charge is contained in it.

The radii for the model core charges can be speciﬁed in the input fdf ﬁle. For example:

bader-core-radius-standard 1.3 Bohr

bader-core-radius-hydrogen 0.4 Bohr

The suggested way to run the Bader analysis with the Univ. of Texas code is to use both the

RHO and BADER ﬁles (both in “cube” format), with the BADER ﬁle providing the “reference”

and the RHO ﬁle the actual signiﬁcant valence charge data which is important in bonding. (See

the notes for pseudopotential codes in the above web page.) For example, for the h2o-pop

example:

bader h2o-pop.RHO.cube -ref h2o-pop.BADER.cube

If netCDF support is compiled in, the ﬁle BaderCharge.grid.nc is produced.

AnalyzeChargeDensityOnly false (logical)

If true, the program optionally generates charge density ﬁles and computes partial atomic

charges (Hirshfeld, Voronoi, Bader) from the information in the input density matrix, and

stops. This is useful to analyze the properties of the charge density without a diagonalization

step, and with a user-selectable mesh cutoﬀ. Note that the DM.UseSaveDM option should

be active. Note also that if an initial density matrix (DM ﬁle) is used, it is not normalized. All

the relevant fdf options for charge-density ﬁle production and partial charge calculation can be

used with this option.

SaveInitialChargeDensity false (logical)

deprecated by: AnalyzeChargeDensityOnly

If true, the program generates a SystemLabel.RHOINIT ﬁle (and a RhoInit.grid.nc ﬁle if

108

netCDF support is compiled in) containing the charge density used to start the ﬁrst self-

consistency step, and it stops. Note that if an initial density matrix (DM ﬁle) is used, it is

not normalized. This is useful to generate the charge density associated to “partial” DMs, as

created by progras such as dm_creator and dm_filter.

(This option is to be deprecated in favor of AnalyzeChargeDensityOnly).

6.23 Auxiliary Force ﬁeld

It is possible to supplement the DFT interactions with a limited set of force-ﬁeld options, typically

useful to simulate dispersion interactions. It is not yet possible to turn oﬀ DFT and base the

dynamics only on the force ﬁeld. The GULP program should be used for that.

%block MM.Potentials 〈None〉 (block)

This block allows the input of molecular mechanics potentials between species. The following

potentials are currently implemented:

• C6, C8, C10 powers of the Tang-Toennes damped dispersion potential.

• A harmonic interaction.

• A dispersion potential of the Grimme type (similar to the C6 type but with a diﬀerent

damping function). (See S. Grimme, J. Comput. Chem. Vol 27, 1787-1799 (2006)). See

also MM.Grimme.D and MM.Grimme.S6 below.

The format of the input is the two species numbers that are to interact, the potential name (C6,

C8, C10, harm, or Grimme), followed by the potential parameters. For the damped dispersion

potentials the ﬁrst number is the coeﬃcient and the second is the exponent of the damping

term (i.e., a reciprocal length). A value of zero for the latter term implies no damping. For the

harmonic potential the force constant is given ﬁrst, followed by r0. For the Grimme potential

C6 is given ﬁrst, followed by the (corrected) sum of the van der Waals radii for the interacting

species (a real length). Positive values of the C6, C8, and C10 coeﬃcients imply attractive

potentials.

%block MM.Potentials

1 1 C6 32.0 2.0

1 2 harm 3.0 1.4

2 3 Grimme 6.0 3.2

%endblock MM.Potentials

To automatically create input for Grimme’s method, please see the utility: Util/Grimme which

can read an fdf ﬁle and create the correct input for Grimme’s method.

MM.Cutoﬀ 30 Bohr (length)

Speciﬁes the distance out to which molecular mechanics potential will act before being treated

as going to zero.

MM.UnitsEnergy eV (unit)

Speciﬁes the units to be used for energy in the molecular mechanics potentials.

MM.UnitsDistance Ang (unit)

Speciﬁes the units to be used for distance in the molecular mechanics potentials.

109

MM.Grimme.D 20.0 (real)

Speciﬁes the scale factor d for the scaling function in the Grimme dispersion potential (see

above).

MM.Grimme.S6 1.66 (real)

Speciﬁes the overall ﬁtting factor s

for the Grimme dispersion potential (see above). This

number depends on the quality of the basis set, the exchange-correlation functional, and the

ﬁtting set.

6.24 Parallel options

BlockSize 〈automatic〉 (integer)

The orbitals are distributed over the processors when running in parallel using a 1-D block-

cyclic algorithm. BlockSize is the number of consecutive orbitals which are located on a given

processor before moving to the next one. Large values of this parameter lead to poor load

balancing, while small values can lead to ineﬃcient execution. The performance of the parallel

code can be optimised by varying this parameter until a suitable value is found.

ProcessorY 〈automatic〉 (integer)

The mesh points are divided in the Y and Z directions (more precisely, along the second and

third lattice vectors) over the processors in a 2-D grid. ProcessorY speciﬁes the dimension of

the processor grid in the Y-direction and must be a factor of the total number of processors.

Ideally the processors should be divided so that the number of mesh points per processor along

each axis is as similar as possible.

Defaults to a multiple of number of processors.

6.24.1 Parallel decompositions for O(N)

Apart from the default block-cyclic decomposition of the orbital data, O(N) calculations can use

other schemes which should be more eﬃcient: spatial decomposition (based on atom proximity),

and domain decomposition (based on the most eﬃcient abstract partition of the interaction graph

of the Hamiltonian).

UseDomainDecomposition false (logical)

This option instructs the program to employ a graph-partitioning algorithm (using the METIS

library (See www.cs.umn.edu/~metis) to ﬁnd an eﬃcient distribution of the orbital data over

processors. To use this option (meaningful only in parallel) the program has to be compiled

with the preprocessor option SIESTA__METIS (or the deprecated ON_DOMAIN_DECOMP) and the

METIS library has to be linked in.

UseSpatialDecomposition false (logical)

When performing a parallel order N calculation, this option instructs the program to execute

a spatial decomposition algorithm in which the system is divided into cells, which are then

assigned, together with the orbitals centered in them, to the diﬀerent processors. The size

of the cells is, by default, equal to the maximum distance at which there is a non-zero matrix

element in the Hamiltonian between two orbitals, or the radius of the Localized Wannier function

- which ever is the larger. If this is the case, then an orbital will only interact with other orbitals

110

in the same or neighbouring cells. However, by decreasing the cell size and searching over more

cells it is possible to achieve better load balance in some cases. This is controlled by the variable

RcSpatial.

NOTE: the distribution algorithm is quite fragile and a careful tuning of RcSpatial might be

needed. This option is therefore not enabled by default.

RcSpatial 〈maximum orbital range〉 (length)

Controls the cell size during the spatial decomposition.

6.25 Eﬃciency options

DirectPhi false (logical)

The calculation of the matrix elements on the mesh requires the value of the orbitals on the

mesh points. This array represents one of the largest uses of memory within the code. If set to

true this option allows the code to generate the orbital values when needed rather than storing

the values. This obviously costs more computer time but will make it possible to run larger

jobs where memory is the limiting factor.

This controls whether the values of the orbitals at the mesh points are stored or calculated on

the ﬂy.

6.26 Memory, CPU-time, and Wall time accounting options

AllocReportLevel 0 (integer)

Sets the level of the allocation report, printed in ﬁle SystemLabel.alloc. However, not all

the allocated arrays are included in the report (this will be corrected in future versions). The

allowed values are:

• level 0 : no report at all (the default)

• level 1 : only total memory peak and where it occurred

• level 2 : detailed report printed only at normal program termination

• level 3 : detailed report printed at every new memory peak

• level 4 : print every individual (re)allocation or deallocation

NOTE: In MPI runs, only node-0 peak reports are produced.

AllocReportThreshold 0. (real)

Sets the minimum size (in bytes) of the arrays whose memory use is individually printed in the

detailed allocation reports (levels 2 and 3). It does not aﬀect the reported memory sums and

peaks, which always include all arrays.

TimerReportThreshold 0. (real)

Sets the minimum fraction, of total CPU time, of the subroutines or code sections whose CPU

time is individually printed in the detailed timer reports. To obtain the accounting of MPI

communication times in parallel executions, you must compile with option -DMPI_TIMING. In

serial execution, the CPU times are printed at the end of the output ﬁle. In parallel execution,

they are reported in a separated ﬁle named SystemLabel.times.

111

UseTreeTimer false (logical)

Enable an experimental timer which is based on wall time on the master node and is aware of

the tree-structure of the timed sections. At the end of the program, a report is generated in

the output ﬁle, and a time.json ﬁle in JSON format is also written. This ﬁle can be used by

third-party scripts to process timing data.

NOTE: , if used with the PEXSI solver (see Sec. 6.13) this defaults to true.

UseParallelTimer true (logical)

Determine whether timings are performed in parallel. This may introduce slight overhead.

NOTE: , if used with the PEXSI solver (see Sec. 6.13) this defaults to false.

MaxWalltime Inﬁnity (real time)

Set an internal limit to the wall time allotted to the program’s execution. Typically this is related

to the external limit imposed by queuing systems. The code checks its wall time periodically

and will abort if nearing the limit, with some slack left for clean-up operations (proper closing

of ﬁles, emergency output...), as determined by MaxWalltime.Slack. See Sec. 16 for available

units of time (s, mins, hours, days).

MaxWalltime.Slack 5 s (real time)

The code checks its wall time T

wall

periodically and will abort if T

wall

> T

max

− T

slack

, so that

some slack is left for any clean-up operations.

6.27 The catch-all option UseSaveData

This is a dangerous feature, and is deprecated, but retained for historical compatibility. Use the

individual options instead.

UseSaveData false (logical)

Instructs to use as much information as possible stored from previous runs in ﬁles

SystemLabel.XV, SystemLabel.DM and SystemLabel.LWF,

NOTE: if the ﬁles are not existing it will read the information from the fdf ﬁle.

6.28 Output of information for Denchar

The program denchar in Util/Denchar can generate charge-density and wavefunction information

in real space.

Write.Denchar false (logical)

Instructs to write information needed by the utility program DENCHAR (by J. Junquera

and P. Ordejón) to generate valence charge densities and/or wavefunctions in real space (see

Util/Denchar). The information is written in ﬁles SystemLabel.PLD and SystemLabel.DIM.

To run DENCHAR you will need, apart from the .PLD and .DIM ﬁles, the Density-Matrix (DM)

ﬁle and/or a wavefunction (.WFSX) ﬁle, and the .ion ﬁles containing the information about the

basis orbitals.

112

6.29 NetCDF (CDF4) output ﬁle

NOTE: this requires SIESTA compiled with CDF4 support.

To unify and construct a simple output ﬁle for an entire SIESTA calculation a generic NetCDF ﬁle

will be created if SIESTA is compiled with ncdf support, see Sec. 2.5 and the ncdf section.

Generally all output to NetCDF ﬂags, SaveElectrostaticPotential, etc. apply to this ﬁle as well.

One may control the output ﬁle with compressibility and parallel I/O, if needed.

CDF.Save false (logical)

Create the SystemLabel.nc ﬁle which is a NetCDF ﬁle.

This ﬁle will be created with a large set of groups which make separating the quantities easily.

Also it will inherently denote the units for the stored quantities.

NOTE: this option is not available for MD/relaxations, only for force constant runs.

CDF.Compress 0 (integer)

Integer between 0 and 9. The former represents no compressing and the latter is the highest

compressing.

The higher the number the more computation time is spent on compressing the data. A good

compromise between speed and compression is 3.

NOTE: if one requests parallel I/O (CDF.MPI) this will automatically be set to 0. One

cannot perform parallel IO and compress the data simultaneously.

NOTE: instead of using SIESTA for compression you may compress after execution by:

nccopy -d 3 -s noncompressed.nc compressed.nc

CDF.MPI false (logical)

Write SystemLabel.nc in parallel using MPI for increased performance. This has almost no

memory overhead but may for very large number of processors saturate the ﬁle-system.

NOTE: this is an experimental ﬂag.

CDF.Grid.Precision single|double (string)

At which precision should the real-space grid quantities be stored, such as the density, electro-

static potential etc.

7 STRUCTURAL RELAXATION, PHONONS, AND MOLECU-

LAR DYNAMICS

This functionality is not SIESTA-speciﬁc, but is implemented to provide a more complete simulation

package. The program has an outer geometry loop: it computes the electronic structure (and thus the

forces and stresses) for a given geometry, updates the atomic positions (and maybe the cell vectors)

accordingly and moves on to the next cycle. If there are molecular dynamics options missing you

are highly recommend to look into MD.TypeOfRun Lua or MD.TypeOfRun Master.

Several options for MD and structural optimizations are implemented, selected by

113

MD.TypeOfRun CG (string)

CG Coordinate

optimization by conjugate gradients). Optionally (see variable MD.VariableCell below),

the optimization can include the cell vectors.

Broyden Coordinate optimization by a modiﬁed Broyden scheme). Optionally, (see variable

MD.VariableCell below), the optimization can include the cell vectors.

FIRE Coordinate optimization by Fast Inertial Relaxation Engine (FIRE) (E. Bitzek et al, PRL

97, 170201, (2006)). Optionally, (see variable MD.VariableCell below), the optimization

can include the cell vectors.

Verlet Standard Verlet algorithm MD

Nose MD with temperature controlled by means of a Nosé thermostat

ParrinelloRahman MD with pressure controlled by the Parrinello-Rahman method

NoseParrinelloRahman MD with temperature controlled by means of a Nosé thermostat and

pressure controlled by the Parrinello-Rahman method

Anneal MD with annealing to a desired temperature and/or pressure (see variable

MD.AnnealOption below)

FC Compute force constants matrix for phonon calculations.

Master|Forces Receive coordinates from, and return forces to, an external driver program, us-

ing MPI, Unix pipes, or Inet sockets for communication. The routines in module fsiesta

allow the user’s program to perform this communication transparently, as if SIESTA

were a conventional force-ﬁeld subroutine. See Util/SiestaSubroutine/README for details.

WARNING: if this option is speciﬁed without a driver program sending data, siesta may hang

without any notice.

See directory Util/Scripting for other driving options.

Lua Fully control the MD cycle and convergence path using an external Lua script.

With an external Lua script one may control nearly everything from a script. One can query

any internal data-structures in SIESTA and, similarly, return any data thus overwriting the

internals. A list of ideas which may be implemented in such a Lua script are:

• New geometry relaxation algorithms

• NEB calculations

• New MD routines

• Convergence tests of Mesh.Cutoﬀ and kgrid.MonkhorstPack, or other parameters

(currently basis set optimizations cannot be performed in the Lua script).

Sec. 9 for additional details (and a description of flos which implements some of the above

mentioned items).

Using this option requires the compilation of SIESTA with the flook library.If SIESTA is

not compiled as prescribed in Sec. 2.5 this option will make SIESTA die.

NOTE: if Compat.Pre-v4-Dynamics is true this will default to Verlet.

Note that some options speciﬁed in later variables (like quenching) modify the behavior of these

MD options.

114

Appart from being able to act as a force subroutine for a driver program that uses module

fsiesta, SIESTA is also prepared to communicate with the i-PI code (see https://github.

com/i-pi/i-pi). To do this, SIESTA must be started after i-PI (it acts as a client of i-PI,

communicating with it through Inet or Unix sockets), and the following lines must be present

in the .fdf data ﬁle:

MD.TypeOfRun Master # equivalent to ’Forces’

Master.code i-pi # ( fsiesta | i-pi )

Master.interface socket # ( pipes | socket | mpi )

Master.address localhost # or driver’s IP, e.g. 150.242.7.140

Master.port 10001 # 10000+siesta_process_order

Master.socketType inet # ( inet | unix )

7.1 Compatibility with pre-v4 versions

Starting in the summer of 2015, some changes were made to the behavior of the program regarding

default dynamics options and choice of coordinates to work with during post-processing of the

electronic structure. The changes are:

• The default dynamics option is “CG” instead of “Verlet”.

• The coordinates, if moved by the dynamics routines, are reset to their values at the previous

step for the analysis of the electronic structure (band structure calculations, DOS, LDOS, etc).

• Some output ﬁles reﬂect the values of the “un-moved” coordinates.

• The default convergence criteria is now both density and Hamiltonian convergence, see

SCF.DM.Converge and SCF.H.Converge.

To recover the previous behavior, the user can turn on the compatibility switch Compat.Pre-v4-

Dynamics, which is oﬀ by default.

Note that complete compatibility cannot be perfectly guaranteed.

7.2 Structural relaxation

In this mode of operation, the program moves the atoms (and optionally the cell vectors) trying to

minimize the forces (and stresses) on them.

These are the options common to all relaxation methods. If the Zmatrix input option is in eﬀect

(see Sec. 6.4.2) the Zmatrix-speciﬁc options take precedence. The ’MD’ preﬁx is misleading but kept

for historical reasons.

MD.VariableCell false (logical)

If true, the lattice is relaxed together with the atomic coordinates. It allows to target hy-

drostatic pressures or arbitrary stress tensors. See MD.MaxStressTol, Target.Pressure,

Target.Stress.Voigt, Constant.Volume, and MD.PreconditionVariableCell.

NOTE: only compatible with MD.TypeOfRun CG, Broyden or ﬁre.

115

Constant.Volume false (logical)

deprecates: MD.ConstantVolume

If true, the cell volume is kept constant in a variable-cell relaxation: only the cell shape and

the atomic coordinates are allowed to change. Note that it does not make much sense to

specify a target stress or pressure in this case, except for anisotropic (traceless) stresses. See

MD.VariableCell, Target.Stress.Voigt.

NOTE: only compatible with MD.TypeOfRun CG, Broyden or ﬁre.

MD.RelaxCellOnly false (logical)

If true, only the cell parameters are relaxed (by the Broyden or FIRE method, not CG). The

atomic coordinates are re-scaled to the new cell, keeping the fractional coordinates constant.

For Zmatrix calculations, the fractional position of the ﬁrst atom in each molecule is kept

ﬁxed, and no attempt is made to rescale the bond distances or angles.

NOTE: only compatible with MD.TypeOfRun Broyden or ﬁre.

MD.MaxForceTol 0.04 eV/Ang (force)

Force tolerance in coordinate optimization. Run stops if the maximum atomic force is smaller

than MD.MaxForceTol (see MD.MaxStressTol for variable cell).

MD.MaxStressTol 1 GPa (pressure)

Stress tolerance in variable-cell CG optimization. Run stops if the maximum atomic force

is smaller than MD.MaxForceTol and the maximum stress component is smaller than

MD.MaxStressTol.

Special consideration is needed if used with Sankey-type basis sets, since the combination of

orbital kinks at the cutoﬀ radii and the ﬁnite-grid integration originate discontinuities in the

stress components, whose magnitude depends on the cutoﬀ radii (or energy shift) and the mesh

cutoﬀ. The tolerance has to be larger than the discontinuities to avoid endless optimizations if

the target stress happens to be in a discontinuity.

MD.Steps 0 (integer)

deprecates: MD.NumCGsteps

Maximum number of steps in a minimization routine (the minimization will stop if tolerance is

reached before; see MD.MaxForceTol below).

NOTE: The old ﬂag MD.NumCGsteps will remain for historical reasons.

MD.MaxDispl 0.2 Bohr (length)

deprecates: MD.MaxCGDispl

Maximum atomic displacements in an optimization move.

In the Broyden optimization method, it is also possible to limit indirectly the initial atomic

displacements using MD.Broyden.Initial.Inverse.Jacobian. For the FIRE method, the

same result can be obtained by choosing a small time step.

Note that there are Zmatrix-speciﬁc options that override this option.

NOTE: The old ﬂag MD.MaxCGDispl will remain for historical reasons.

MD.PreconditionVariableCell 5 Ang (length)

A length to multiply to the strain components in a variable-cell optimization. The strain

components enter the minimization on the same footing as the coordinates. For good eﬃciency,

116

this length should make the scale of energy variation with strain similar to the one due to

atomic displacements. It is also used for the application of the MD.MaxDispl value to the

strain components.

ZM.ForceTolLength 0.00155574 Ry/Bohr (force)

Parameter that controls the convergence with respect to forces on Z-matrix lengths

ZM.ForceTolAngle 0.00356549 Ry/rad (torque)

Parameter that controls the convergence with respect to forces on Z-matrix angles

ZM.MaxDisplLength 0.2 Bohr (length)

Parameter that controls the maximum change in a Z-matrix length during an optimisation step.

ZM.MaxDisplAngle 0.003 rad (angle)

Parameter that controls the maximum change in a Z-matrix angle during an optimisation step.

7.2.1 Conjugate-gradients optimization

This was historically the default geometry-optimization method, and all the above options were

introduced speciﬁcally for it, hence their names. The following pertains only to this method:

MD.UseSaveCG false (logical)

Instructs to read the conjugate-gradient hystory information stored in ﬁle SystemLabel.CG by

a previous run.

NOTE: to get actual continuation of iterrupted CG runs, use together with MD.UseSaveXV

true with the .XV ﬁle generated in the same run as the CG ﬁle. If the required ﬁle does not

exist, a warning is printed but the program does not stop. Overrides UseSaveData.

NOTE: no such feature exists yet for a Broyden-based relaxation.

7.2.2 Broyden optimization

It uses the modiﬁed Broyden algorithm to build up the Jacobian matrix. (See D.D. Johnson, PRB

38, 12807 (1988)). (Note: This is not BFGS.)

MD.Broyden.History.Steps 5 (integer)

Number of relaxation steps during which the modiﬁed Broyden algorithm builds up the Jacobian

matrix.

MD.Broyden.Cycle.On.Maxit true (logical)

Upon reaching the maximum number of history data sets which are 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 the Broyden minimization algorithm from a ﬁrst step of a diagonal inverse Jacobian

(which might be useful when the minimization is stuck).

MD.Broyden.Initial.Inverse.Jacobian 1 (real)

Initial inverse Jacobian for the optimization procedure. (The units are those implied by the

internal Siesta usage. The default value seems to work well for most systems.

117

7.2.3 FIRE relaxation

Implementation of the Fast Inertial Relaxation Engine (FIRE) method (E. Bitzek et al, PRL 97,

170201, (2006) in a manner compatible with the CG and Broyden modes of relaxation. (An older

implementation activated by the MD.FireQuench variable is still available).

MD.FIRE.TimeStep 〈MD.LengthTimeStep〉 (time)

The (ﬁctitious) time-step for FIRE relaxation. This is the main user-variable when the option

FIRE for MD.TypeOfRun is active.

NOTE: the default value is encouraged to be changed as the link to MD.LengthTimeStep

is misleading.

There are other low-level options tunable by the user (see the routines fire_optim and

cell_fire_optim for more details.

7.3 Target stress options

Useful for structural optimizations and constant-pressure molecular dynamics.

Target.Pressure 0 GPa (pressure)

deprecates: MD.TargetPressure

Target pressure for Parrinello-Rahman method, variable cell optimizations, and annealing op-

tions.

NOTE: this is only compatible with MD.TypeOfRun ParrinelloRahman, NoseParrinel-

loRahman, CG, Broyden or FIRE (variable cell), or Anneal (if MD.AnnealOption Pres-

sure or TemperatureandPressure).

%block Target.Stress.Voigt −1 −1 −1 0 0 0 (block)

deprecates: MD.TargetStress

External or target stress tensor for variable cell optimizations. Stress components are given in

a line, in the Voigt order xx, yy, zz, yz, xz, xy. In units of Target.Pressure, but with

the opposite sign. For example, a uniaxial compressive stress of 2 GPa along the 100 direction

would be given by

Target.Pressure 2. GPa

%block Target.Stress.Voigt

-1.0 0.0 0.0 0.0 0.0 0.0

%endblock

Only used if MD.TypeOfRun is CG, Broyden or FIRE and MD.VariableCell is true.

%block MD.TargetStress −1 −1 −1 0 0 0 (block)

deprecated by: Target.Stress.Voigt

Same as Target.Stress.Voigt but the order is same as older SIESTA version (prior to 4.1).

Order is xx, yy, zz, xy, xz, yz.

MD.RemoveIntramolecularPressure false (logical)

If true, the contribution to the stress coming from the internal degrees of freedom of the

molecules will be subtracted from the stress tensor used in variable-cell optimization or variable-

cell molecular-dynamics. This is done in an approximate manner, using the virial form of the

118

stress, and assumming that the “mean force” over the coordinates of the molecule represents

the “inter-molecular” stress. The correction term was already computed in earlier versions of

SIESTA and used to report the “molecule pressure”. The correction is now computed molecule-

by-molecule if the Zmatrix format is used.

If the intra-molecular stress is removed, the corrected static and total stresses are printed in

addition to the uncorrected items. The corrected Voigt form is also printed.

NOTE: versions prior to 4.1 (also 4.1-beta releases) printed the Voigt stress-tensor in this

format: [x, y, z, xy, yz, xz]. In 4.1 and later SIESTA only show the correct Voigt rep-

resentation: [x, y, z, yz, xz, xy].

7.4 Molecular dynamics

In this mode of operation, the program moves the atoms (and optionally the cell vectors) in response

to the forces (and stresses), using the classical equations of motion.

Note that the Zmatrix input option (see Sec. 6.4.2) is not compatible with molecular dynamics. The

initial geometry can be speciﬁed using the Zmatrix format, but the Zmatrix generalized coordinates

will not be updated.

MD.InitialTimeStep 1 (integer)

Initial time step of the MD simulation. In the current version of SIESTA it must be 1.

Used only if MD.TypeOfRun is not CG or Broyden.

MD.FinalTimeStep 〈MD.Steps〉 (integer)

Final time step of the MD simulation.

MD.LengthTimeStep 1 fs (time)

Length of the time step of the MD simulation.

MD.InitialTemperature 0 K (temperature/energy)

Initial temperature for the MD run. The atoms are assigned random velocities drawn from the

Maxwell-Bolzmann distribution with the corresponding temperature. The constraint of zero

center of mass velocity is imposed.

NOTE: only used if MD.TypeOfRun Verlet, Nose, ParrinelloRahman, NoseParrinel-

loRahman or Anneal.

MD.TargetTemperature 0 K (temperature/energy)

Target temperature for Nose thermostat and annealing options.

NOTE: only used if MD.TypeOfRun Nose, NoseParrinelloRahman or Anneal if

MD.AnnealOption is Temperature or TemperatureandPressure.

MD.NoseMass 100 Ry fs

(moment of inertia)

Generalized mass of Nose variable. This determines the time scale of the Nose variable dynamics,

and the coupling of the thermal bath to the physical system.

Only used for Nose MD runs.

MD.ParrinelloRahmanMass 100 Ry fs

(moment of inertia)

Generalized mass of Parrinello-Rahman variable. This determines the time scale of the

119

Parrinello-Rahman variable dynamics, and its coupling to the physical system.

Only used for Parrinello-Rahman MD runs.

MD.AnnealOption TemperatureAndPressure (string)

Type of annealing MD to perform. The target temperature or pressure are achieved by velocity

and unit cell rescaling, in a given time determined by the variable MD.TauRelax below.

Temperature Reach a target temperature by velocity rescaling

Pressure Reach a target pressure by scaling of the unit cell size and shape

TemperatureandPressure Reach a target temperature and pressure by velocity rescaling and

by scaling of the unit cell size and shape

Only applicable for MD.TypeOfRun Anneal.

MD.TauRelax 100 fs (time)

Relaxation time to reach target temperature and/or pressure in annealing MD. Note that this

is a “relaxation time”, and as such it gives a rough estimate of the time needed to achieve the

given targets. As a normal simulation also exhibits oscillations, the actual time needed to reach

the averaged targets will be signiﬁcantly longer.

Only applicable for MD.TypeOfRun Anneal.

MD.BulkModulus 100 Ry/Bohr

(pressure)

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 in annealing MD.

Only applicable for MD.TypeOfRun Anneal, when MD.AnnealOption is Pressure or

TemperatureAndPressure

7.5 Output options for dynamics

Every time the atoms move, either during coordinate relaxation or molecular dynamics, their po-

sitions predicted for next step and current velocities are stored in ﬁle SystemLabel.XV. The

shape of the unit cell and its associated ’velocity’ (in Parrinello-Rahman dynamics) are also stored

in this ﬁle.

WriteCoorInitial true (logical)

It determines whether the initial atomic coordinates of the simulation are dumped into the main

output ﬁle. These coordinates correspond to the ones actually used in the ﬁrst step (see the

section on precedence issues in structural input) and are output in Cartesian coordinates in

Bohr units.

It is not aﬀected by the setting of LongOutput.

WriteCoorStep false (logical)

If true, it writes the atomic coordinates to standard output at every MD time step or relax-

ation step. The coordinates are always written in the SystemLabel.XV ﬁle, but overriden at

every step. They can be also accumulated in the .MD or SystemLabel.MDX ﬁles depending on

WriteMDHistory.

120

WriteForces false (logical)

If true, it writes the atomic forces to the output ﬁle at every MD time step or relaxation step.

Note that the forces of the last step can be found in the ﬁle SystemLabel.FA. If constraints are

used, the ﬁle SystemLabel.FAC is also written.

WriteMDHistory false (logical)

If true, SIESTA accumulates the molecular dynamics trajectory in the following ﬁles:

• SystemLabel.MD : atomic coordinates and velocities (and lattice vectors and their time

derivatives, if the dynamics implies variable cell). The information is stored unformatted

for postprocessing with utility programs to analyze the MD trajectory.

• SystemLabel.MDE : shorter description of the run, with energy, temperature, etc., per time

step.

These ﬁles are accumulative even for diﬀerent runs.

The trajectory of a molecular dynamics run (or a conjugate gradient minimization) can be

accumulated in diﬀerent ﬁles: SystemLabel.MD, SystemLabel.MDE, and SystemLabel.ANI.

The ﬁrst ﬁle keeps the whole trajectory information, meaning positions and velocities at every

time step, including lattice vectors if the cell varies. NOTE that the positions (and maybe the

cell vectors) stored at each time step are the predicted values for the next step. Care should

be taken if joint position-velocity correlations need to be computed from this ﬁle. The second

gives global information (energy, temperature, etc), and the third has the coordinates in a form

suited for XMol animation. See the WriteMDHistory and WriteMDXmol data descriptors

above for information. SIESTA always appends new information on these ﬁles, making them

accumulative even for diﬀerent runs.

The iomd subroutine can generate both an unformatted ﬁle .MD (default) or ASCII formatted

ﬁles .MDX and .MDC containing the atomic and lattice trajectories, respectively. Edit the ﬁle to

change the settings if desired.

Write.OrbitalIndex true (logical)

If true it causes the writing of an extra ﬁle named SystemLabel.ORB_INDX containing all

orbitals used in the calculation.

Its formatting is clearly speciﬁed at the end of the ﬁle.

7.6 Restarting geometry optimizations and MD runs

Every time the atoms move, either during coordinate relaxation or molecular dynamics, their posi-

tions predicted for next step and current velocities are stored in ﬁle SystemLabel.XV, where

SystemLabel is the value of that fdf descriptor (or ’siesta’ by default). The shape of the unit cell and

its associated ’velocity’ (in Parrinello-Rahman dynamics) are also stored in this ﬁle. For MD runs of

type Verlet, Parrinello-Rahman, Nose, Nose-Parrinello-Rahman, or Anneal, a ﬁle named SystemLa-

bel.VERLET_RESTART, SystemLabel.PR_RESTART, SystemLabel.NOSE_RESTART, System-

Label.NPR_RESTART, or SystemLabel.ANNEAL_RESTART, respectively, is created to hold the

values of auxiliary variables needed for a completely seamless continuation.

If the restart ﬁle is not available, a simulation can still make use of the XV information, and “restart”

by basically repeating the last-computed step (the positions are shifted backwards by using a single

Euler-like step with the current velocities as derivatives). While this feature does not result in

121

seamless continuations, it allows cross-restarts (those in which a simulation of one kind (e.g., Anneal)

is followed by another (e.g., Nose)), and permits to re-use dynamical information from old runs.

This restart ﬁx is not satisfactory from a fundamental point of view, so the MD subsystem in Siesta

will have to be redesigned eventually. In the meantime, users are reminded that the scripting hooks

being steadily introduced (see Util/Scripting) might be used to create custom-made MD scripts.

7.7 Use of general constraints

Note: The Zmatrix format (see Sec. 6.4.2) provides an alternative constraint formulation which can

be useful for system involving molecules.

%block Geometry.Constraints 〈None〉 (block)

Constrains certain atomic coordinates or cell parameters in a consistent method.

There are a high number of conﬁgurable parameters that may be used to control the relaxation

of the coordinates.

NOTE: SIESTA prints out a small section of how the constraints are recognized.

atom|position Fix certain atomic coordinates.

This option takes a variable number of integers which each correspond to the atomic index

(or input sequence) in AtomicCoordinatesAndAtomicSpecies.

atom is now the preferred input option while position still works for backwards compatibility.

One may also specify ranges of atoms according to:

atom A [B [C [. . . ]]] A sequence of atomic indices which are constrained.

atom from A to B [step s] Here atoms A up to and including B are constrained. If step

<s> is given, the range A:B will be taken in steps of s.

atom from 3 to 10 step 2

will constrain atoms 3, 5, 7 and 9.

atom from A plus/minus B [step s] Here atoms A up to and including A + B − 1 are

constrained. If step <s> is given, the range A:A + B −1 will be taken in steps of s.

atom [A, B -- C [step s], D] Equivalent to from . . . to speciﬁcation, however in a shorter

variant. Note that the list may contain arbitrary number of ranges and/or individual

indices.

atom [2, 3 -- 10 step 2, 6]

will constrain atoms 2, 3, 5, 7, 9 and 6.

atom [2, 3 -- 6, 8]

will constrain atoms 2, 3, 4, 5, 6 and 8.

atom all Constrain all atoms.

NOTE: these speciﬁcations are apt for directional constraints.

Z Equivalent to atom with all indices of the atoms that have atomic number equal to the

speciﬁed number.

NOTE: this speciﬁcation is apt for directional constraints.

122

species-i Equivalent to atom with all indices of the atoms that have species according to the

ChemicalSpeciesLabel and AtomicCoordinatesAndAtomicSpecies.

NOTE: this speciﬁcation is apt for directional constraints.

center One may retain the coordinate center of a range of atoms (say molecules or other groups

of atoms).

Atomic indices may be speciﬁed according to atom.

NOTE: this speciﬁcation is apt for directional constraints.

rigid|molecule Move a selection of atoms together as though they where one atom.

The forces are summed and averaged to get a net-force on the entire molecule.

Atomic indices may be speciﬁed according to atom.

NOTE: this speciﬁcation is apt for directional constraints.

rigid-max|molecule-max Move a selection of atoms together as though they where one atom.

The maximum force acting on one of the atoms in the selection will be expanded to act on

all atoms speciﬁed.

Atomic indices may be speciﬁed according to atom.

cell-angle Control whether the cell angles (α, β, γ) may be altered.

This takes either one or more of alpha/beta/gamma as argument.

alpha is the angle between the 2nd and 3rd cell vector.

beta is the angle between the 1st and 3rd cell vector.

gamma is the angle between the 1st and 2nd cell vector.

NOTE: currently only one angle can be constrained at a time and it forces only the spanning

vectors to be relaxed.

cell-vector Control whether the cell vectors (A, B, C) may be altered.

This takes either one or more of A/B/C as argument.

Constraining the cell-vectors are only allowed if they only have a component along their

respective Cartesian direction. I.e. B must only have a y-component.

stress Control which of the 6 stress components are constrained.

This takes a number of integers 1 ≤ i ≤ 6 where 1 corresponds to the AA stress-component,

2 is BB, 3 is CC, 4 is BC /CB, 5 is AC /CA and 6 is AB/BA.

routine This calls the constr routine speciﬁed in the ﬁle: constr.f. Without having changed

the corresponding source ﬁle, this does nothing. See details and comments in the source-ﬁle.

clear Remove constraints on selected atoms from all previously speciﬁed constraints.

This may be handy when specifying constraints via Z or species-i.

Atomic indices may be speciﬁed according to atom.

clear-prev Remove constraints on selected atoms from the previous speciﬁed constraint.

This may be handy when specifying constraints via Z or species-i.

Atomic indices may be speciﬁed according to atom.

NOTE: two consecutive clear-prev may be used in conjunction as though the atoms where

speciﬁed on the same line.

123

It is instructive to give an example of the input options presented.

Consider a benzene molecule (C

) and we wish to relax all Hydrogen atoms. This may be

accomplished in this fashion

%block Geometry.Constraints

Z 6

%endblock

Or as in this example

%block AtomicCoordinatesAndAtomicSpecies

... ... ... 1 # C 1

... ... ... 2 # H 2

... ... ... 1 # C 3

... ... ... 2 # H 4

... ... ... 1 # C 5

... ... ... 2 # H 6

... ... ... 1 # C 7

... ... ... 2 # H 8

... ... ... 1 # C 9

... ... ... 2 # H 10

... ... ... 1 # C 11

... ... ... 2 # H 12

%endblock

%block Geometry.Constraints

atom from 1 to 12 step 2

%endblock

%block Geometry.Constraints

atom [1 -- 12 step 2]

%endblock

%block Geometry.Constraints

atom all

clear-prev [2 -- 12 step 2]

%endblock

where the 3 last blocks all create the same result.

Finally, the directional constraint is an important and often useful feature. When relaxing

complex structures it may be advantageous to ﬁrst relax along a given direction (where you

expect the stress to be largest) and subsequently let it fully relax. Another example would be to

relax the binding distance between a molecule and a surface, before relaxing the entire system

by forcing the molecule and adsorption site to relax together. To use directional constraint

one may provide an additional 3 reals after the atom/rigid. For instance in the previous

example (benzene) one may ﬁrst relax all Hydrogen atoms along the y and z Cartesian vector

by constraining the x Cartesian vector

%block Geometry.Constraints

Z 6 # constrain Carbon

Z 1 1. 0. 0. # constrain Hydrogen along x Cartesian vector

%endblock

Note that you must append a “.” to denote it a real. The vector speciﬁed need not be normalized.

Also, if you want it to be constrained along the x-y vector you may do

%block Geometry.Constraints

Z 6

124

Z 1 1. 1. 0.

%endblock

7.8 Phonon calculations

If MD.TypeOfRun is FC, SIESTA sets up a special outer geometry loop that displaces individual

atoms along the coordinate directions to build the force-constant matrix.

The output (see below) can be analyzed to extract phonon frequencies and vectors with the VIBRA

package in the Util/Vibra directory. For computing the Born eﬀective charges together with the

force constants, see BornCharge.

MD.FCDispl 0.04 Bohr (length)

Displacement to use for the computation of the force constant matrix for phonon calculations.

MD.FCFirst 1 (integer)

Index of ﬁrst atom to displace for the computation of the force constant matrix for phonon

calculations.

MD.FCLast 〈MD.FCFirst〉 (integer)

Index of last atom to displace for the computation of the force constant matrix for phonon

calculations.

The force-constants matrix is written in ﬁle SystemLabel.FC. The format is the following: for the

displacement of each atom in each direction, the forces on each of the other atoms is writen (divided

by the value of the displacement), in units of eV/Å

. Each line has the forces in the x, y and z

direction for one of the atoms.

If constraints are used, the ﬁle SystemLabel.FCC is also written.

8 DFT+U

NOTE: This implementation works for both LDA and GGA, hence named DFT+U in the main

text.

NOTE: Current implementation is based on the simpliﬁed rotationally invariant DFT+U formula-

tion of Dudarev and collaborators [see, Dudarev et al., Phys. Rev. B 57, 1505 (1998)]. Although

the input allows to deﬁne independent values of the U and J parameters for each atomic shell, in

the actual calculation the two parameters are combined to produce an eﬀective Coulomb repulsion

eﬀ

= U − J. U

eﬀ

is the parameter actually used in the calculations for the time being.

For large or intermediate values of U

eﬀ

the convergence is sometimes diﬃcult. A step-by-step increase

of the value of U

eﬀ

can be advisable in such cases.

Currently, the DFT+U implementation does not support non-collinear, nor spin-orbit coupling.

DFTU.ProjectorGenerationMethod 2 (integer)

Generation method of the DFT+U projectors. The DFT+U projectors are the localized func-

tions used to calculate the local populations used in a Hubbard-like term that modiﬁes the LDA

Hamiltonian and energy. It is important to recall that DFT+U projectors should be quite local-

125

ized functions. Otherwise the calculated populations loose their atomic character and physical

meaning. Even more importantly, the interaction range can increase so much that jeopardizes

the eﬃciency of the calculation.

Two methods are currently implemented:

1 Projectors are slightly-excited numerical atomic orbitals similar to those used as an auto-

matic basis set by SIESTA. The radii of these orbitals are controlled using the parameter

DFTU.EnergyShift and/or the data included in the block DFTU.Proj (quite similar to

the data block PAO.Basis used to specify the basis set, see below).

2 Projectors are exact solutions of the pseudoatomic problem (and, in principle, are not strictly

localized) which are cut using a Fermi function 1/{1 + exp[(r − r

)ω]}. The values of r

and

ω are controlled using the parameter DFTU.CutoﬀNorm and/or the data included in the

block DFTU.Proj.

DFTU.EnergyShift 0.05 Ry (energy)

Energy increase used to deﬁne the localization radius of the DFT+U projectors (similar to the

parameter PAO.EnergyShift).

NOTE: only used when DFTU.ProjectorGenerationMethod is 1.

DFTU.CutoﬀNorm 0.9 (real)

Parameter used to deﬁne the value of r

used in the Fermi distribution to cut the DFT+U

projectors generated according to generation method 2 (see above). DFTU.CutoﬀNorm is

the norm of the original pseudoatomic orbital contained inside a sphere of radius equal to r

NOTE: only used when DFTU.ProjectorGenerationMethod is 2.

%block DFTU.Proj 〈None〉 (block)

Data block used to specify the DFT+U projectors.

• If DFTU.ProjectorGenerationMethod is 1, the syntax is as follows:

%block DFTU.Proj # Define DFT+U projectors

Fe 2 # Label, l_shells

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 # rc (Bohr)

0.95 # scaleFactor (opt)

0 # l

1.00 0.05 # U(eV), J(eV) for this shell

0.00 # rc(Bohr) (if 0, automatic r_c from DFTU.EnergyShift)

%endblock DFTU.Proj

• If DFTU.ProjectorGenerationMethod is 2, the syntax is as follows:

%block DFTU.Proj # Define DFTU projectors

Fe 2 # Label, l_shells

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 # rc (Bohr), \omega(Bohr) (Fermi cutoff function)

0.95 # scaleFactor (opt)

0 # l

1.00 0.05 # U(eV), J(eV) for this shell

0.00 0.00 # rc(Bohr), \omega(Bohr) (if 0 r_c from DFTU.CutoffNorm

%endblock DFTU.Proj # and \omega from default value)

126

Certain of the quantites have default values:

U 0.0 eV

J 0.0 eV

ω 0.05 Bohr

Scale factor 1.0

depends on DFTU.EnergyShift or DFTU.CutoﬀNorm depending on the generation

method.

DFTU.FirstIteration false (logical)

If true, local populations are calculated and Hubbard-like term is switch on in the ﬁrst iteration.

Useful if restarting a calculation reading a converged or an almost converged density matrix

from ﬁle.

DFTU.ThresholdTol 0.01 (real)

Local populations only calculated and/or updated if the change in the density matrix elements

(dDmax) is lower than DFTU.ThresholdTol.

DFTU.PopTol 0.001 (real)

Convergence criterium for the DFT+U local populations. In the current implementation the

Hubbard-like term of the Hamiltonian is only updated (except for the last iteration) if the

variations of the local populations are larger than this value.

DFTU.PotentialShift false (logical)

If set to true, the value given to the U parameter in the input ﬁle is interpreted as a local

potential shift. Recording the change of the local populations as a function of this potential

shift, we can calculate the appropriate value of U for the system under study following the

methology proposed by Cococcioni and Gironcoli in Phys. Rev. B 71, 035105 (2005).

9 External control of SIESTA

Since SIESTA 4.1 an additional method of controlling the convergence and MD of SIESTA is

enabled through external scripting capability. The external control comes in two variants:

• Implicit control of MD through updating/changing parameters and optimizing forces. For

instance one may use a Verlet MD method but additionally update the forces through some

external force-ﬁeld to amend limitations by the Verlet method for your particular case. In

the implicit control the molecular dynamics is controlled by SIESTA.

• Explicit control of MD. In this mode the molecular dynamics must be controlled in the external

Lua script and the convergence of the geometry should also be controlled via this script.

The implicit control is in use if MD.TypeOfRun is something other than lua, while if the option

is lua the explicit control is in use.

For examples on the usage of the Lua scripting engine and the power you may ﬁnd the library

flos

, see https://github.com/siesta-project/flos. At the time of writing the flos library

This library is implemented by Nick R. Papior to further enhance the inter-operability with SIESTA and external

contributions.

127

already implements new geometry/cell relaxation schemes and new force-constants algorithms. You

are highly encouraged to use the new relaxation schemes as they may provide faster convergence of

the relaxation.

Lua.Script 〈none〉 (ﬁle)

Specify a Lua script ﬁle which may be used to control the internal variables in SIESTA. Such

a script ﬁle must contain at least one function named siesta_comm with no arguments.

An example ﬁle could be this (note this is Lua code):

-- This function (siesta_comm) is REQUIRED

function siesta_comm()

-- Define which variables we want to retrieve from SIESTA

get_tbl = {"geom.xa", "E.total"}

-- Signal to SIESTA which variables we want to explore

siesta.receive(get_tbl)

-- Now we have the required variables,

-- convert to a simpler variable name (not nested tables)

-- (note the returned quantities are in SIESTA units (Bohr, Ry)

xa = siesta.geom.xa

Etot = siesta.E.total

-- If we know our energy is wrong by 0.001 Ry we may now

-- change the total energy

Etot = Etot - 0.001

-- Return to SIESTA the total energy such that

-- it internally has the "correct" energy.

siesta.E.total = Etot

ret_tbl = {"E.total"}

siesta.send(ret_tbl)

end

Within this function there are certain states which deﬁnes diﬀerent execution points in SIESTA:

Initialization This is right after SIESTA has read the options from the FDF ﬁle. Here you

may query some of the FDF options (and even change them) for your particular problem.

NOTE: siesta.state == siesta.INITIALIZE.

Initialize-MD Right before the SCF step starts. This point is somewhat superﬂuous, but is

necessary to communicate the actual meshcutoﬀ used

NOTE: siesta.state == siesta.INIT_MD.

SCF Right after SIESTA has calculated the output density matrix, and just after SIESTA has

performed mixing.

NOTE: siesta.state == siesta.SCF_LOOP.

Remember that the Mesh.Cutoﬀ deﬁned is the minimum cutoﬀ used.

128

Forces This stage is right after SIESTA has calculated the forces.

NOTE: siesta.state == siesta.FORCES.

Move This state will only be reached if MD.TypeOfRun is lua.

If one does not return updated atomic coordinates SIESTA will reuse the same geometry as

just analyzed.

NOTE: siesta.state == siesta.MOVE.

Analysis Just before SIESTA completes and exits.

NOTE: siesta.state == siesta.ANALYSIS.

Beginning with implementations of Lua scripts may be cumbersome. It is recommended to

start by using flos, see https://github.com/siesta-project/flos which contains several

examples on how to start implementing your own scripts. Currently flos implements a larger

variety of relaxation schemes, for instance:

local flos = require "flos"

LBFGS = flos.LBFGS()

function siesta_comm()

LBFGS:SIESTA(siesta)

end

which is the most minimal example of using the L-BFGS algorithm for geometry relax-

ation. Note that flos reads the parameters MD.MaxDispl and MD.MaxForceTol through

SIESTA automatically.

NOTE: The number of available variables continues to grow and to ﬁnd which quantities are

accessible in Lua you may add this small code in your Lua script:

siesta.print_allowed()

which prints out a list of all accessible variables (note they are not sorted).

If there are any variables you require which are not in the list, please contact the developers.

If you want to stop SIESTA from Lua you can use the following:

siesta.Stop = true

siesta.send({"Stop"})

which will abort SIESTA.

Remark that since anything may be changed via Lua one may easily make SIESTA crash due to

inconsistencies in the internal logic. This is because SIESTA does not check what has changed,

it accepts everything as is and continues. Hence, one should be careful what is changed.

Lua.Debug false (logical)

Debug the Lua script mode by printing out (on stdout) information everytime SIESTA com-

municates with Lua.

Lua.Debug.MPI false (logical)

Debug all nodes (if in a parallel run).

Lua.Interactive false (logical)

Start an interactive Lua session at all the states in the program and ask for user-input. This is

primarily intended for debugging purposes. The interactive session is executed just before the

129

siesta_comm function 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 ﬁrst MPI node.

There are various commands that are caught if they are the only content on a line:

/debug Turn on/oﬀ debugging information.

/show Show the currently collected lines of code.

/clear Clears the currently collected lines of code.

; Run the currently collected lines of code and continue collecting lines.

/run Same as ;.

/cont Run the currently collected lines of code and continue SIESTA.

/stop Run the currently collected lines of code and stop all future interactive Lua sessions.

Currently this only works if Lua.Script is having a valid Lua ﬁle (note the ﬁle may be empty).

9.1 Examples of Lua programs

Please look in the Tests/lua_* folders where examples of basic Lua scripts are found. Below is a

description of the * examples.

h2o Changes the mixing weight continuously in the SCF loop. This will eﬀectively speed up con-

vergence time if one can attain the best mixing weight per SCF-step.

si111 Change the mixing method based on certain convergence criteria. I.e. after a certain conver-

gence one can switch to a more aggressive mixing method.

A combination of the above two examples may greatly improve convergence, however, creating a

generic method to adaptively change the mixing parameters may be very diﬃcult to implement. If

you do create such a Lua script, please share it on the mailing list.

9.2 External MD/relaxation methods

Using the Lua interface allows a very easy interface for creating external MD and/or relaxation

methods.

A public library (flos, https://github.com/siesta-project/flos) already implements a wider

range of relaxation methods than intrinsically enabled in SIESTA. Secondly, by using external

scripting mechanisms one can customize the routines to a much greater extend while simultaneously

create custom constraints.

You are highly encouraged to try out the flos library (please note that flook is required, see

installation instructions above).

130

10 TRANSIESTA

SIESTA includes the possibility of performing calculations of electronic transport properties using

the TranSIESTA method. This Section describes how to use these capabilities, and a reference

guide to the relevant fdf options. We describe here only the additional options available for Tran-

SIESTA calculations, while the rest of the Siesta functionalities and variables are described in the

previous sections of this User’s Guide.

An accompanying Python toolbox is available which will assist with TranSIESTA calculations.

Please use (and cite) sisl

[13]

10.1 Source code structure

In this implementation, the TranSIESTA routines have been grouped in a set of modules whose

ﬁle names begin with m_ts or ts.

10.2 Compilation

Prior to SIESTA 4.1 TranSIESTA was a separate executable. Now TranSIESTA is fully incor-

porated into SIESTA. Only compile SIESTA and the full functionality is present. Sec. 2 for details

on compiling SIESTA.

10.3 Brief description

The TranSIESTA method is a procedure to solve the electronic structure of an open system

formed by a ﬁnite structure sandwiched between semi-inﬁnite metallic leads. A ﬁnite bias can be

applied between leads, to drive a ﬁnite current. The method is described in detail in Brandbyge

et al.

[4]

; Papior et al.

[11]

. In practical terms, calculations using TranSIESTA involve the solution of

the electronic density from the DFT Hamiltonian using Greens functions techniques, instead of the

usual diagonalization procedure. Therefore, TranSIESTA calculations involve 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

module’ in what follows.

TranSIESTA was originally developed by Mads Brandbyge, José-Luis Mozos, Pablo Ordejón,

Jeremy Taylor and Kurt Stokbro

[4]

. It consisted, mainly, in setting up an interface between SIESTA

and the (tight-binding) transport codes developed by M. Brandbyge and K. Stokbro. Initially ev-

erything was written in Fortran-77. As SIESTA started to be translated to Fortran-90, so were the

TranSIESTA parts of the code. This was accomplished by José-Luis Mozos, who also worked on

the parallelization of TranSIESTA. Subsequently Frederico D. Novaes extended TranSIESTA to

allow k-point sampling for transverse directions. Additional extensions was added by Nick R. Papior

during 2012.

The current TranSIESTA module has been completely rewritten by Nick R. Papior and encompass

highly advanced inversion algorithms as well as allowing N ≥ 1 electrode setups among many new

features. Furthermore, the 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

131

N ≥ 1 setups

[11]

• Transport calculations involve electrode (EL) calculations, and subsequently the Scattering

Region (SR) calculation. The electrode calculations are usual SIESTA calculations, but where

ﬁles SystemLabel.TSHS, and optionally SystemLabel.TSDE, are generated. These ﬁles contain

the information necessary for calculation of the self-energies. If any electrodes have identical

structures (see below) the same ﬁles can and should be used to describe those. In general,

however, electrodes can be diﬀerent and therefore two diﬀerent SystemLabel.TSHS ﬁles must

be generated. The location of these electrode ﬁles must be speciﬁed in the fdf input ﬁle of

the SR calculation, see TS.Elec.<>.HS.

• For the SR, TranSIESTA starts with the usual SIESTA procedure, converging a Density

Matrix (DM) with the usual Kohn-Sham scheme for periodic systems. It uses this solution

as an initial input for the Greens function self consistent cycle. Eﬀectively you will start a

TranSIESTA calculation from a fully periodic calculation. This is why the 0 V calculation

should be the only calculation where you start from SIESTA.

TranSIESTA stores the SCF DM in a ﬁle named SystemLabel.TSDE. In a rerun of the same

system (meaning the same SystemLabel), if the code ﬁnds a SystemLabel.TSDE ﬁle in the

directory, it will take this DM as the initial input and this is then considered a continua-

tion run. In this case it does not perform an initial SIESTA run. It must be clear that

when starting a calculation from scratch, in the end one will ﬁnd both ﬁles, SystemLabel.DM

and SystemLabel.TSDE. The ﬁrst one stores the SIESTA density matrix (periodic boundary

conditions in all directions and no voltage), and the latter the TranSIESTA solution.

• When performing several bias calculations, it is heavily advised to run diﬀerent bias’ in dif-

ferent directories. To drastically improve convergence (and throughput) one should copy the

SystemLabel.TSDE from the closest, previously, calculated bias to the current bias.

• The SystemLabel.TSDE may be read equivalently as the SystemLabel.DM. Thus, it may be

used by fx. denchar to analyze the non-equilibrium charge density. Alternatively one can use

sisl

[13]

to interpolate the DM and EDM to speed up convergence.

• As in the case of SIESTA calculations, what TranSIESTA does is to obtain a converged DM,

but for open boundary conditions and possibly a ﬁnite bias applied between electrodes. The

corresponding Hamiltonian matrix (once self consistency is achieved) of the SR is also stored in

a SystemLabel.TSHS ﬁle. Subsequently, transport properties are obtained in a post-processing

procedure using the TBtrans code (located in the Util/TS/TBtrans directory). We note that

the SystemLabel.TSHS ﬁles contain all the needed structural information (atomic positions,

matrix elements, . . . ), and so the input (fdf) ﬂags for the geometry and basis have no inﬂuence

of the subsequent TBtrans calculations.

• When the non-equilibrium calculation uses diﬀerent electrodes one should use so-called buﬀer

atoms behind the electrodes to act as additional screening regions when calculating the initial

guess (using SIESTA) for TranSIESTA. Essentially they may be used to achieve a better

“bulk-like” environment at the electrodes in the SR calculation.

• An important parameter is the lower bound of the energy contours. It is a good practice, to

start with a SIESTA calculation for the SR and look at the eigenvalues of the system. The

lower bound of the contours must be well below the lowest eigenvalue.

132

• Periodic boundary conditions are assumed in 2 cases.

1. For N

6= 2 all lattice vectors are periodic, users must manually deﬁne

TS.kgrid.MonkhorstPack

2. For N

= 2 TranSIESTA will auto-detect if both electrodes are semi-inﬁnite along the

same lattice vector. If so, only 1 k point will be used along that lattice vector.

• The default algorithm for matrix inversion is the BTD method, before starting a TranSIESTA

calculation please run with the analyzation step TS.Analyze (note this is very fast and can

be done on any desktop computer, regardless of system size).

• Importantly(!) the k-point sampling need typically be much higher in a TBtrans calculation

to achieve a converged transmission function.

• Energies from TranSIESTA are not to be trusted since the open boundaries complicates

the energy calculation. Therefore care needs to be taken when comparing energies between

diﬀerent calculations and/or diﬀerent bias’.

• Always ensure that charges are preserved in the scattering region calculation. Doing the SCF

an output like the following will be shown:

ts-q: D E1 C1 E2 C2 dQ

ts-q: 436.147 392.146 3.871 392.146 3.871 7.996E-3

Always ensure the last column (dQ) is a very small fraction of the total number of electrons.

Ideally this should be 0. For 0 bias calculations this should be very small, typically less than

0.1 % of the total charge in the system. If this is not the case, it probably means that there

is not enough screening towards the electrodes which can be solved by adding more electrode

layers between the electrode and the scattering region. This layer thickness is very important

to obtain a correct open boundary calculation.

• Do not perform TranSIESTA calculations using semi-conducting electrodes. The basic

premise of TranSIESTA calculations is that the electrodes behave like bulk in the electrode

regions of the SR. This means that the distance between the electrode and the perturbed must

equal the screening length of the electrode.

This is problematic for semi-conducting systems since they intrinsically have a very long screen-

ing length.

In addition, the Fermi-level of semi-conductors are not well-deﬁned since it may be placed

anywhere in the band gap.

10.4 Electrodes

To calculate the electronic structure of a system under external bias, TranSIESTA attaches the

system to semi-inﬁnite electrodes which extend to their respective semi-inﬁnite directions. Examples

of electrodes would include surfaces, nanowires, nanotubes or fully inﬁnite regions. The electrode

must be large enough (in the semi-inﬁnite direction) so that orbitals within the unit cell only interact

with a single nearest neighbor cell in the semi-inﬁnite direction (the size of the unit cell can thus be

derived from the range of support for the orbital basis functions). TranSIESTA will stop if this

133

is not enforced. The electrodes are generated by a separate TranSIESTA run on a bulk system.

This implies that the proper bulk properties are obtained by a suﬃciently high k-point sampling.

If in doubt, use 100 k-points along the semi-inﬁnite direction. The results are saved in a ﬁle with

extension SystemLabel.TSHS which contains a description of the electrode unit cell, the position

of the atoms within the unit cell, as well as the Hamiltonian and overlap matrices that describe

the electronic structure of the lead. One can generate a variety of electrodes and the typical use

of TranSIESTA would involve reusing the same electrode for several setups. At runtime, the

TranSIESTA coordinates are checked against the electrode coordinates and the program stops

if there is a mismatch to a certain precision (10

−4

Bohr). Note that the atomic coordinates are

compared relatively. Hence the input atomic coordinates of the electrode and the device need not

be the same (see e.g. the tests in the Tests directory.

To run an electrode calculation one should do:

siesta --electrode RUN.fdf

or deﬁne these options in the electrode fdf ﬁles: TS.HS.Save and TS.DE.Save to true (the above

–electrode is a shorthand to forcefully deﬁne the two options).

10.4.1 Matching coordinates

Here are some rules required to successfully construct the appropriate coordinates of the scattering

region. Contrary to versions prior to 4.1, the order of atoms is largely irrelevant. One may deﬁne

all electrodes, then subsequently the device, or vice versa. Similarly, buﬀer atoms are not restricted

to be the ﬁrst/last atoms.

However, atoms in any given electrode must be consecutive in the device ﬁle. I.e. if an electrode

input option is given by:

%block TS.Elec.<>

HS ../elec-<>/siesta.TSHS

bloch 1 3 1

used-atoms 4

electrode-position 10

...

%endblock

then the atoms from 10 to 10 + 4 ∗ 3 −1 must coincide with the atoms of the calculation performed

in the ../elec-<>/ subdirectory. The above options will be discussed in the following section.

When using the Bloch expansion (highly recommended if your system allows it) it is advised to

follow the tiling method. However both of the below sequences are allowed.

Tile Here the atoms are copied and displaced by the full electrode. Generally this expansion should

be preferred over the repeat expansion due to much faster execution.

iaD = 10 ! as per the above input option

do iC = 0 , nC - 1

do iB = 0 , nB - 1

do iA = 0 , nA - 1

134

do iaE = 1 , na_u

xyz_device(:, iaD) = xyz_elec(:, iaE) + &

cell_elec(:, 1) * iA + &

cell_elec(:, 2) * iB + &

cell_elec(:, 3) * iC

iaD = iaD + 1

end do

By using sisl

[13]

one can achieve the tiling scheme by using the following command-line utility on

an input ELEC.fdf structure with the minimal electrode:

sgeom -tx 1 -ty 3 -tz 1 ELEC.fdf DEVICE_ELEC.fdf

Repeat Here the atoms are copied individually. Generally this expansion should not be used since

it is much slower than tiling.

iaD = 10 ! as per the above input option

do iaE = 1 , na_u

do iC = 0 , nC - 1

do iB = 0 , nB - 1

do iA = 0 , nA - 1

xyz_device(:, iaD) = xyz_elec(:, iaE) + &

cell_elec(:, 1) * iA + &

cell_elec(:, 2) * iB + &

cell_elec(:, 3) * iC

iaD = iaD + 1

end do

By using sisl

[13]

one can achieve the repeating scheme by using the following command-line utility

on an input ELEC.fdf structure with the minimal electrode:

sgeom -rz 1 -ry 3 -rx 1 ELEC.fdf DEVICE_ELEC.fdf

10.4.2 Principal layer interactions

It is extremely important that the electrodes only interact with one neighboring supercell due to the

self-energy calculation

[14]

. TranSIESTA will print out a block as this

<> principal cell is perfect!

if the electrode is correctly setup and it only interacts with its neighboring supercell. In case the

electrode is erroneously setup, something similar to the following will be shown in the output ﬁle.

135

<> principal cell is extending out with 96 elements:

Atom 1 connects with atom 3

Orbital 8 connects with orbital 26

Hamiltonian value: |H(8,6587)|@R=-2 = 0.651E-13 eV

Overlap : S(8,6587)|@R=-2 = 0.00

It is imperative that you have a perfect electrode as otherwise nonphysical results will occur. This

means that you need to add more layers in your electrode calculation (and hence also in your

scattering region). An example is an ABC stacking electrode. If the above error is shown one has

to create an electrode with ABCABC stacking in order to retain periodicity.

By default TranSIESTA will die if there are connections beyond the principal cell. One may control

whether this is allowed or not by using TS.Elecs.Neglect.Principal.

10.5 Convergence of electrodes and scattering regions

For successful TranSIESTA calculations it is imperative that the electrodes and scattering regions

are well-converged. The basic principle is equivalent to the SIESTA convergence, see Sec. 6.9.

The steps should be something along the line of (only done at 0 V ).

1. Converge electrodes and ﬁnd optimal Mesh.Cutoﬀ, kgrid.MonkhorstPack etc.

Electrode k points should be very high along the semi-inﬁnite direction. The default is 100,

but at least > 50 should easily be reachable.

2. Use the parameters from the electrodes and also converge the same parameters for the scat-

tering region SCF.

This is an iterative process since the scattering region forces the electrodes to use equivalent

k points (see TS.Elec.<>.check-kgrid).

Note that k points should be limited in the TranSIESTA run, see

TS.kgrid.MonkhorstPack.

One should always use the same parameters in both the electrode and scattering region cal-

culations, except the number of k points for the electrode calculations along their respective

semi-inﬁnite directions.

3. Once TranSIESTA is completed one should also converge the number of k points for TB-

trans. Note that k point sampling in TBtrans should generally be much denser but always

fulﬁll N

TranSIESTA

≥ N

TBtrans

The converged parameters obtained at 0 V should be used for all subsequent bias calculations.

Remember to copy the SystemLabel.TSDE from the closest, previously, calculated bias for restart

and much faster convergence.

TranSIESTA is also more diﬃcult to converge during the SCF steps. This may be due to several

interrelated problems:

• A too short screening distance between the scattering atoms and the electrode layers.

136

• In case buﬀer atoms (TS.Atoms.Buﬀer) are used with vacuum on the backside it may be

that there are too few buﬀer atoms to accurately screen oﬀ the vacuum region for a suﬃciently

good initial guess. This eﬀect is only true for 0 V calculations.

• The mixing parameters may need to be smaller than for SIESTA, see Sec. 6.9.2 and it is never

guaranteed that it will converge. It is always a trial and error method, there are no omnipotent

mixing parameters.

• Very high bias’ may be extremely diﬃcult to converge. Generally one can force bias convergence

by doing smaller steps of bias. E.g. if problems arise at 0.5 V with an initial DM from a 0.25 V

calculation, one could try and 0.3 V ﬁrst.

• If a particular bias point is hard to converge, even by doing the previous step, it may be related

to an eigenstate close to the chemical potentials of either electrode (e.g. a molecular eigenstate

in the junction). In such cases one could try an even higher bias and see if this converges more

smoothly.

10.6 TranSIESTA Options

The fdf options shown here are only to be used at the input ﬁle for the scattering region. When using

TranSIESTA for electrode calculations, only the usual SIESTA options are relevant. Note that

since TranSIESTA is a generic N

electrode NEGF code the input options are heavily changed

compared to versions prior to 4.1.

10.6.1 Quick and dirty

Since 4.1, TranSIESTA has been fully re-implemented. And so have every input fdf-ﬂag. To

accommodate an easy transition between previous input ﬁles 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 if you are familiar with previous TranSIESTA versions.

One may input options as in the old TranSIESTA version and then run

ts2ts OLD.fdf > NEW.fdf

which translates all keys to the new, equivalent, input format. If you are familiar with the old-style

ﬂags this is highly recommendable while becoming comfortable with the new input format. Please

note that some defaults have changed to more conservative values in the newer release.

If one does not know the old ﬂags and wish to get a basic example of an input ﬁle, a script

Util/TS/tselecs.sh exists that can create the basic input for N

electrodes. One may call it

like:

tselecs.sh -2 > TWO_ELECTRODE.fdf

tselecs.sh -3 > THREE_ELECTRODE.fdf

tselecs.sh -4 > FOUR_ELECTRODE.fdf

...

where the ﬁrst 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 additional options.

137

Before endeavoring on large scale calculations you are advised to run an analyzation of the system

at hand, you may run your system as

siesta -fdf TS.Analyze RUN.fdf > analyze.out

which will analyze the sparsity pattern and print out several diﬀerent pivoting schemes. Please see

TS.Analyze for more information.

10.6.2 General options

One have to set SolutionMethod to transiesta to enable TranSIESTA.

TS.SolutionMethod btd|mumps|full (string)

Control the algorithm used for calculating the Green function. Generally the BTD method is

the fastest and this option need not be changed.

BTD Use the block-tri-diagonal algorithm for matrix inversion.

This is generally the recommended method.

MUMPS Use sparse matrix inversion algorithm (MUMPS). This requires TranSIESTA to be

compiled with MUMPS.

full Use full matrix inversion algorithm (LAPACK). Generally only usable for debugging pur-

poses.

TS.Voltage 0 eV (energy)

Deﬁne the reference applied bias. For N

= 2 electrode calculations this refers to the actual

potential drop between the electrodes, while for N

6= 2 this is a reference bias. In the latter

case it must be equivalent to the maximum diﬀerence between the chemical potential of any

two electrodes.

NOTE: Specifying -V on the command-line overwrites the value in the fdf ﬁle.

%block TS.kgrid.MonkhorstPack 〈kgrid.MonkhorstPack〉 (block)

k points used for the TranSIESTA calculation.

For N

6= 2 this should always be deﬁned. Always take care to use only 1 k point along non-

periodic lattice vectors. An electrode semi-inﬁnite region is considered non-periodic since it is

integrated out through the self-energies.

This defaults to kgrid.MonkhorstPack.

TS.Atoms.Buﬀer 〈None〉 (block/list)

Specify atoms that will be removed in the TranSIESTA SCF. They are not considered in the

calculation and may be used to improve the initial guess for the Hamiltonian.

An intended use for buﬀer atoms is to ensure a bulk behavior in the electrode regions when

electrodes are diﬀerent. As an example: a 2 electrode calculation with left consisting of Au

atoms and the right consisting of Pt atoms. In such calculations one cannot create a periodic

geometry along the transport direction. One needs to add vacuum between the Au and Pt

atoms that comprise the electrodes. However, this creates an artiﬁcial edge of the electrostatic

environment for the electrodes since in SIESTA there is vacuum, whereas in TranSIESTA

the eﬀective Hamiltonian sees a bulk environment. To ensure that SIESTA also exhibits a

138

bulk environment on the electrodes we add buﬀer atoms towards the vacuum region to screen

oﬀ the electrode region. These buﬀer atoms is thus a technicality that has no inﬂuence on the

TranSIESTA calculation but they are necessary to ensure the electrode bulk properties.

The above discussion is even more important when doing N

-electrode calculations.

NOTE: all lines are additive for the buﬀer atoms and the input method is similar to that of

Geometry.Constraints for the atom line(s).

%block TS.Atoms.Buffer

atom [ 1 -- 5 ]

%endblock

# Or equivalently as a list

TS.Atoms.Buffer [1 -- 5]

will remove atoms [1–5] from the calculation.

TS.ElectronicTemperature 〈ElectronicTemperature〉 (energy)

Deﬁne the temperature used for the Fermi distributions for the chemical potentials. See

TS.ChemPot.<>.ElectronicTemperature.

TS.SCF.DM.Tolerance 〈SCF.DM.Tolerance〉 (real)

depends on: SCF.DM.Tolerance, SCF.DM.Converge

The density matrix tolerance for the TranSIESTA SCF cycle.

TS.SCF.H.Tolerance 〈SCF.H.Tolerance〉 (energy)

depends on: SCF.H.Tolerance, SCF.H.Converge

The Hamiltonian tolerance for the TranSIESTA SCF cycle.

TS.SCF.dQ.Converge true (logical)

Whether TranSIESTA should check whether the total charge is within a provided tolerance,

see TS.SCF.dQ.Tolerance.

TS.SCF.dQ.Tolerance Q(device) · 10

−3

(real)

depends on: TS.SCF.dQ.Converge

The charge tolerance during the SCF.

The charge is not stable in TranSIESTA calculations and this ﬂag ensures that one does not,

by accident, do post-processing of ﬁles where the charge distribution is completely wrong.

A too high tolerance may heavily inﬂuence the electrostatics of the simulation.

NOTE: Please see TS.dQ for ways to reduce charge loss in equilibrium calculations.

TS.SCF.Initialize diagon|transiesta (string)

Control which initial guess should be used for TranSIESTA. The general way is the diagon

solution method (which is preferred), however, one can start a TranSIESTA run immedi-

ately. If you start directly with TranSIESTA please refer to these ﬂags: TS.Elecs.DM.Init,

DM.Init.Bulk and TS.Fermi.Initial.

NOTE: Setting this to transiesta is highly experimental and convergence may be extremely

poor.

TS.Fermi.Initial

(energy)

Manually set the initial Fermi level to a predeﬁned value.

139

NOTE: this may also be used to change the Fermi level for calculations where you restart

calculations. Using this feature is highly experimental.

TS.Weight.Method orb-orb|[[un]correlated+][sum|tr]-atom-[atom|orb]|mean (string)

Control how the NEGF weighting scheme is conducted. Generally one should only use the

orb-orb while the others are present for more advanced usage. They refer to how the weighting

coeﬃcients of the diﬀerent non-equilibrium contours are performed. In the following the weight

are denoted in a two-electrode setup while they are generalized for multiple electrodes.

Deﬁne the normalised geometric mean as ∝

via

∝h·

i ≡

h·

i + h·

. (21)

When applying a bias, TranSIESTA will printout the following during the SCF cycle:

ts-err-D: ij( 447, 447), M = 1.8275, ew = -.257E-2, em = 0.258E-2. avg_em = 0.542E-06

ts-err-E: ij( 447, 447), M = -6.7845, ew = 0.438E-3, em = -.439E-3. avg_em = -.981E-07

ts-w-q: qP1 qP2

ts-w-q: 219.150 216.997

ts-q: D E1 C1 E2 C2 dQ

ts-q: 436.147 392.146 3.871 392.146 3.871 7.996E-3

The extra output corresponds to ﬁne details in the integration scheme.

ts-err-* are estimated error outputs from the diﬀerent integrals, for the density matrix

(D) and the energy density matrix (E), see Eq. (12) in

[11]

. All values (except avg_em)

are for the given orbital site

ij(A,B) refers to the matrix element between orbital A and B

M is the weighted matrix element value,

ew is the maximum diﬀerence between

− ρ

for all e.

em is the maximum diﬀerence between ρ

− ρ

for all combinations of e and e

avg_em is the averaged diﬀerence of em for all orbital sites.

ts-w-q is the Mulliken charge from the diﬀerent integrals: Tr[w

orb-orb Weight each orbital-density matrix element individually.

tr-atom-atom Weight according to the trace of the atomic density matrix sub-blocks

∝

∈{i}

(∆ρ

µµ

)

∈{j}

(∆ρ

µµ

)

(22)

tr-atom-orb Weight according to the trace of the atomic density matrix sub-block times the

weight of the orbital weight

ij,µν

∝

ij,µν

(23)

sum-atom-atom Weight according to the total sum of the atomic density matrix sub-blocks

ij,µν

∝

∈{i}

(∆ρ

µν

)

∈{j}

(∆ρ

µν

)

(24)

140

sum-atom-orb Weight according to the total sum of the atomic density matrix sub-block times

the weight of the orbital weight

ij,µν

∝

ij,µν

(25)

mean A standard average.

Each of the methods (except mean) comes in a correlated and uncorrelated variant where

is either outside or inside the square, respectively.

TS.Weight.k.Method correlated|uncorrelated (string)

Control weighting per k-point or the full sum. I.e. if uncorrelated is used it will weight n

times if there are n

k-points in the Brillouin zone.

TS.Forces true (logical)

Control whether the forces are calculated. If not TranSIESTA will use slightly less memory

and the performance slightly increased, however the ﬁnal forces shown are incorrect.

If this is true the ﬁle SystemLabel.TSFA (and possibly the SystemLabel.TSFAC) will be cre-

ated. They contain forces for the atoms that are having updated density-matrix elements

(TS.Elec.<>.DM-update all).

Generally one should not expect good forces close to the electrode/device interface since this

typically has some electrostatic eﬀects that are inherent to the TranSIESTA method. Forces

on atoms far from the electrode can safely be analyzed.

TS.dQ none|buﬀer|fermi (string)

Any excess/deﬁciency of charge can be re-adjusted after each TranSIESTA cycle to reduce

charge ﬂuctuations in the cell.

NOTE: recommended to only use charge corrections for 0 V calculations.

The non-neutral charge in TranSIESTA cycles is an expression of one of the following things:

1. An incorrect screening towards the electrodes. To check this, simply add more electrode

layers towards the device at each electrode and see how the charge evolves. It should tend

to zero.

The best way to check this is to follow these steps:

(a) Perform a SIESTA-only calculation (the resulting DM should be used as the starting

point for both following calculations)

(b) Perform a TranSIESTA calculation with the option TS.Elecs.DM.Init diagon

(please note that the electrode option has precedence, so remove any entry from the

TS.Elec.<> block)

(please note that the electrode option has precedence, so remove any entry from the

TS.Elec.<> block)

Now compare the ﬁnal output and the initial charge distribution, e.g.:

>>> TS.Elecs.DM.Init diagon

transiesta: Charge distribution, target = 396.00000

Total charge [Q] : 396.00000

141

>>> TS.Elecs.DM.Init bulk

transiesta: Charge distribution, target = 396.00000

Total charge [Q] : 395.9995

The above shows that there is very little charge diﬀerence between the bulk electrode DM

and the scattering region. This ensures that the charge distribution are similar and that

your electrode is suﬃciently screened.

Additionally one may compare the ﬁnal output such as total energies, calculated DOS

and ADOS (see TBtrans). If the two calculations show diﬀerent properties, one should

carefully examine the system setup.

2. An incorrect reference energy level. In TranSIESTA the Fermi level is calculated from

the SIESTA SCF. However, the SIESTA Fermi level corresponds to a periodic calculation

and not an open system calculation such as NEGF.

If the ﬁrst step shows a good screening towards the electrode it is usually the reference

energy level, then use TS.dQ fermi.

3. A combination of the above, this is the typical case.

none No charge corrections are introduced.

buﬀer Excess/missing electrons are placed in the buﬀer regions (buﬀer atoms are required to

exist)

fermi Correct the charge ﬁlling by calculating a new reference energy level (referred to as the

Fermi level).

We approximate the contribution to be constant around the Fermi level and ﬁnd

− Q

, (26)

where Q

is the charge from a TranSIESTA SCF step and Q|

is the equilibrium charge at

the current Fermi level, Q is the supposed charge to reside in the calculation. Fermi correction

utilizes Eq. (26) for the ﬁrst correction and all subsequent corrections are based on a cubic

spline interpolation to faster converge the “correct” Fermi level.

This method will create a ﬁle called TS_FERMI.

NOTE: correcting the reference energy level is a costly operation since the SCF cycle typically

gets corrupted resulting in many more SCF cycles.

TS.dQ.Factor 0.8 (real)

Any positive value close to 1. 0 means no charge correction. 1 means total charge correction.

This will reduce the ﬂuctuations in the SCF and setting this to 1 may result in diﬃculties in

converging.

TS.dQ.Fermi.Tolerance 0.01 (real)

The tolerance at which the charge correction will converge. Any excess/missing charge (|Q

−

Q| > Tol) will result in a correction for the Fermi level.

TS.dQ.Fermi.Max 1.5 eV (energy)

The maximally allowed value that the Fermi level will change from a charge correction using

the Fermi correction method. In case the Fermi level lies in between two bands a DOS of 0 at

142

the Fermi level will make the Fermi change equal to ∞. This is not physical and the user can

thus truncate the correction.

NOTE: If you know the band-gab, setting this to 1/4 (or smaller) of the band gab seems like

a better value than the rather arbitrarily default one.

TS.dQ.Fermi.Eta 1 meV (energy)

The η value that we extrapolate the charge at the poles to. Usually a smaller η value will mean

larger changes in the Fermi level. If the charge convergence w.r.t. the Fermi level is ﬂuctuating

a lot one should increase this η value.

TS.HS.Save true (logical)

Must be true for saving the Hamiltonian (SystemLabel.TSHS). Can only be set if Solution-

Method is not transiesta.

The default is false for SolutionMethod diﬀerent from transiesta and if –electrode has

not been passed as a command line argument.

TS.DE.Save true (logical)

Must be true for saving the density and energy density matrix for continuation runs

(SystemLabel.TSDE). Can only be set if SolutionMethod is not transiesta.

The default is false for SolutionMethod diﬀerent from transiesta and if –electrode has

not been passed as a command line argument.

TS.S.Save false (logical)

This is a ﬂag mainly used for the Inelastica code to produce overlap matrices for Pulay correc-

tions. This should only be used by advanced users.

TS.SIESTA.Only false (logical)

Stop TranSIESTA right after the initial diagonalization run in SIESTA. Upon exit it will

also create the SystemLabel.TSDE ﬁle which may be used for initialization runs later.

This may be used to start several calculations from the same initial density matrix, and it

may also be used to rescale the Fermi level of electrodes. The rescaling is primarily used for

semi-conductors where the Fermi levels of the device and electrodes may be misaligned.

TS.Analyze false (logical)

When using the BTD solution method (TS.SolutionMethod) this will analyze the Hamilto-

nian and printout an analysis of the sparsity pattern for optimal choice of the BTD partitioning

algorithm.

This yields information regarding the TS.BTD.Pivot ﬂag.

NOTE: we advice users to always run an analyzation step prior to actual calculation and

select the best BTD format. This analyzing step is very fast and may be performed on small

work-station computers, even on systems of  10, 000 orbitals.

To run the analyzing step you may do:

siesta -fdf TS.Analyze RUN.fdf > analyze.out

note that there is little gain on using MPI and it should complete within a few minutes, no

matter the number of orbitals.

Choosing the best one may be diﬃcult. Generally one should choose the pivoting scheme that

143

uses the least amount of memory. However, one should also choose the method with the largest

block-size being as small as possible. As an example:

TS.BTD.Pivot atom+GPS

...

BTD partitions (7):

[ 2984, 2776, 192, 192, 1639, 4050, 105 ]

BTD matrix block size [max] / [average]: 4050 / 1705.429

BTD matrix elements in % of full matrix: 47.88707 %

TS.BTD.Pivot atom+GGPS

...

BTD partitions (6):

[ 2880, 2916, 174, 174, 2884, 2910 ]

BTD matrix block size [max] / [average]: 2916 / 1989.667

BTD matrix elements in % of full matrix: 48.62867 %

Although the GPS method uses the least amount of memory, the GGPS will likely perform

better as the largest block in GPS is 4050 vs. 2916 for the GGPS method.

TS.Analyze.Graphviz false (logical)

depends on: TS.Analyze

If performing the analysis, also create the connectivity graph and store it as GRAPHVIZ_atom.gv

or GRAPHVIZ_orbital.gv to be post-processed in Graphviz

10.6.3 Algorithm speciﬁc options

These options adhere to the speciﬁc solution methods available for TranSIESTA. For instance the

TS.BTD.* options adhere only when using TS.SolutionMethod BTD, similarly for options with

MUMPS.

TS.BTD.Pivot 〈ﬁrst electrode〉 (string)

Decide on the partitioning for the BTD matrix. One may denote either atom+ or orb+ as a

preﬁx which does the analysis on the atomic sparsity pattern or the full orbital sparsity pattern,

respectively. If neither are used it will default to atom+.

Please see TS.Analyze.

<elec-name>|CG-<elec-name> The partitioning will be a connectivity graph starting from

the electrode denoted by the name. This name must be found in the TS.Elecs block. One

can append more than one electrode to simultaneously start from more than 1 electrode. This

may be necessary for multi-terminal calculations.

rev-CM Use the reverse Cuthill-McKee for pivoting the matrix elements to reduce bandwidth.

One may omit rev- to use the standard Cuthill-McKee algorithm (not recommended).

This pivoting scheme depends on the initial starting electrodes, append +<elec-name> to

start the Cuthill-McKee algorithm from the speciﬁed electrode(s).

GPS Use the Gibbs-Poole-Stockmeyer algorithm for reducing the bandwidth.

GGPS Use the generalized Gibbs-Poole-Stockmeyer algorithm for reducing the bandwidth.

www.graphviz.org

144

NOTE: this algorithm does not work on dis-connected graphs.

PCG Use the perphiral connectivity graph algorithm for reducing the bandwidth.

This pivoting scheme may depend on the initial starting electrode(s), append +<elec-

name> to initialize the PCG algorithm from the speciﬁed electrode(s).

Examples are

TS.BTD.Pivot atom+GGPS

TS.BTD.Pivot GGPS

TS.BTD.Pivot orb+GGPS

TS.BTD.Pivot orb+PCG+Left

where the ﬁrst two are equivalent. The 3rd and 4th are more heavy on analysis and will typically

not improve the bandwidth reduction.

TS.BTD.Optimize speed|memory (string)

When selecting the smallest blocks for the BTD matrix there are certain criteria that may

change the size of each block. For very memory consuming jobs one may choose the memory.

NOTE: often both methods provide exactly the same BTD matrix due to constraints on the

matrix.

TS.BTD.Guess1.Min 〈empirically determined〉 (int)

depends on: TS.BTD.Guess1.Max

Constructing the blocks for the BTD starts by guessing the ﬁrst block size. One could guess on

all diﬀerent block sizes, but to speed up the process one can deﬁne a smaller range of guesses

by deﬁning TS.BTD.Guess1.Min and TS.BTD.Guess1.Max.

The initial guessed block size will be between the two values.

By default this is 1/4 of the minimum bandwidth for a selected ﬁrst set of orbitals.

NOTE: setting this to 1 may sometimes improve the ﬁnal BTD matrix blocks.

TS.BTD.Guess1.Max 〈empirically determined〉 (int)

depends on: TS.BTD.Guess1.Min

See TS.BTD.Guess1.Min.

NOTE: for improved initialization performance setting Min/Max ﬂags to the ﬁrst block size for

a given pivoting scheme will drastically reduce the search space and make initialization much

faster.

TS.BTD.Spectral propagation|column (string)

How to compute the spectral function (GΓG

†

For N

< 4 this defaults to propagation which should be the fastest.

For N

≥ 4 this defaults to column.

Check which has the best performance for your system if you endeavor on huge amounts of

calculations for the same system.

TS.MUMPS.Ordering 〈read MUMPS manual〉 (string)

One may select from a number of diﬀerent matrix orderings which are all described in the

MUMPS manual.

The following list of orderings are available (without detailing their diﬀerences): auto, AMD,

145

AMF, SCOTCH, PORD, METIS, QAMD.

TS.MUMPS.Memory 20 (integer)

Specify a factor for the memory consumption in MUMPS. See the INFOG(9) entry in the

MUMPS manual. Generally if TranSIESTA dies and INFOG(9)=-9 one should increase

this number.

TS.MUMPS.BlockingFactor 112 (integer)

Specify the number of internal block sizes. Larger numbers increases performance at the cost

of memory.

NOTE: this option may heavily inﬂuence performance.

10.6.4 Poisson solution for ﬁxed boundary conditions

TranSIESTA requires ﬁxed boundary conditions and forcing this is an intricate and important

detail.

It is important that these options are exactly the same if one reuses the SystemLabel.TSDE ﬁles.

TS.Poisson ramp|elec-box|〈ﬁle〉 (string)

Deﬁne how the correction of the Poisson equation is superimposed. The default is to apply

the linear correction across the entire cell (if there are two semi-inﬁnite aligned electrodes).

Otherwise this defaults to the box solution which will introduce spurious eﬀects at the electrode

boundaries. In this case you are encouraged to supply a ﬁle.

If the input is a ﬁle, it should be a NetCDF ﬁle containing the grid information which acts as

the boundary conditions for the SCF cycle. The grid information should conform to the grid

size of the unit-cell in the simulation. NOTE: the ﬁle option is only applicable if compiled with

CDF4 compliance.

ramp Apply the ramp for the full cell. This is the default for 2 electrodes.

<ﬁle> Specify an external ﬁle used as the boundary conditions for the applied bias. This is

encouraged to use for N

> 2 electrode calculations but may also be used when an a priori

potential proﬁle is know.

The ﬁle should contain something similar to this output (ncdump -h):

netcdf <file> {

dimensions:

one = 1 ;

a = 43 ;

b = 451 ;

c = 350 ;

variables:

double Vmin(one) ;

Vmin:unit = "Ry" ;

double Vmax(one) ;

Vmax:unit = "Ry" ;

double V(c, b, a) ;

V:unit = "Ry" ;

}

Note that the units should be in Ry. Vmax/Vmin should contain the maximum/minimum

ﬁxed boundary conditions in the Poisson solution. This is used internally by TranSIESTA

146

to scale the potential to arbitrary V . This enables the Poisson solution to only be solved once

independent on subsequent calculations. For chemical potential conﬁgurations where the

Poisson solution is not linearly dependent one have to create separate ﬁles for each applied

bias.

elec-box The default potential proﬁle for N

> 2, or when the electrodes does are not aligned

(in terms of their transport direction).

NOTE: usage of this Poisson solution is highly discouraged. Please see TS.Poisson <ﬁle>.

TS.Hartree.Fix [-+][ABC] (string)

Specify which plane to ﬁx the Hartree potential at. For regular (2 electrode calculations with

a single transport direction) this should not be set. For N

6= 2 electrode systems one have to

specify a plane to ﬁx. One can specify one or several planes to ﬁx. Users are encouraged to ﬁx

the plane where the entire plane has the highest/lowest potential.

TS.Hartree.Fix.Frac 1. (real)

Fraction of the correction that is applied.

NOTE: this is an experimental feature!

TS.Hartree.Oﬀset 0 eV (energy)

An oﬀset in the Hartree potential to match the electrode potential.

This value may be useful in certain cases where the Hartree potentials are very diﬀerent between

the electrode and device region calculations.

This should not be changed between diﬀerent bias calculations. It directly relates to the reference

energy level (E

10.6.5 Electrode description options

As TranSIESTA supports N

electrodes one needs to specify all electrodes in a generic input

format.

%block TS.Elecs 〈None〉 (block)

Each line denote an electrode which is queried in TS.Elec.<> for its setup.

%block TS.Elec.<> 〈None〉 (block)

Each line represents a setting for electrode <>. There are a few lines that must be present,

HS, semi-inf-dir, electrode-pos, chem-pot. The remaining options are optional.

NOTE: Options preﬁxed with tbt are neglected in TranSIESTA calculations. In TBtrans

calculations these ﬂags has precedence over the other options and must be placed at the end of

the block.

HS The Hamiltonian information from the initial electrode calculation. This ﬁle retains the

geometrical information as well as the Hamiltonian, overlap matrix and the Fermi-level of the

electrode. This is a ﬁle-path and the electrode SystemLabel.TSHS need not be located in the

simulation folder.

semi-inf-direction|semi-inf-dir|semi-inf The semi-inﬁnite direction of the electrode with re-

spect to the electrode unit-cell.

147

It may be one of [-+][abc], [-+]A[123], ab, ac, bc or abc. The latter four all describe a

real-space self-energy as described in

[12]

NOTE: this direction is not with respect to the scattering region unit cell. It is with respect

to the electrode unit cell. TranSIESTA will ﬁgure out the alignment of the electrode unit

cell and the scattering region unit-cell.

chemical-potential|chem-pot|mu The chemical potential that is associated with this elec-

trode. This is a string that should be present in the TS.ChemPots block.

electrode-position|elec-pos The index of the electrode in the scattering region. This may

be given by either elec-pos <idx>, which refers to the ﬁrst atomic index of the electrode

residing at index <idx>. Else the electrode position may be given via elec-pos end <idx>

where the last index of the electrode will be located at <idx>.

used-atoms Number of atoms from the electrode calculation that is used in the scattering

region as electrode. This may be useful when the periodicity of the electrodes forces extensive

electrodes in the semi-inﬁnite direction.

NOTE: do not set this if you use all atoms in the electrode.

Bulk Control whether the Hamiltonian of the electrode region in the scattering region is enforced

bulk or whether the Hamiltonian is taken from the scattering region elements.

This defaults to true. If there are buﬀer atoms behind the electrode it may be advantageous

to set this to false to extend the electrode region.

DM-update depends on: TS.Elec.<>.Bulk

String of values none, cross-terms or all which controls which part of the electrode density

matrix elements that are updated. If all, both the density matrix elements in the elec-

trode and the coupling elements between the electrode and scattering region are updated. If

cross-terms; only the coupling elements between the electrode and the scattering region are

updated.

If TS.Elec.<>.Bulk false this is forced to all and cannot be changed.

If TS.Elec.<>.Bulk true this defaults to cross-terms, but may be changed.

DM-init depends on: TS.Elecs.DM.Init, TS.Elec.<>.Bulk, TS.Voltage

String of values bulk, diagon (default) or force-bulk which controls whether the DM is

initially overwritten by the DM from the bulk electrode calculation. This requires the DM

ﬁle for the electrode to be present. Only force-bulk will have eﬀect if V 6= 0. Otherwise this

option only aﬀects V = 0 calculations.

The density matrix elements in the electrodes of the scattering region may be forcefully

set to the bulk values by reading in the DM of the corresponding electrode. If one uses

TS.Elec.<>.Bulk false it may be dis-advantageous to set this to bulk. If the system is

well setup (good screening towards electrodes), setting this to bulk may be advantageous.

This option may be used to check how good the electrodes are screened, see TS.dQ fermi.

Gf String with ﬁlename of the surface Green function data (SystemLabel.TSGF*). This may

be used to place a common surface Green function ﬁle in a top directory which may then be

used in all calculations using the same electrode and the same contour. If many calculations

are performed this will heavily increase performance at the cost of disk-space.

Gf-Reuse Logical deciding whether the surface Green function ﬁle should be re-used or deleted.

148

If this is false the surface Green function ﬁle is deleted and re-created upon start.

Eta depends on: TS.Elecs.Eta

Control the imaginary energy (η) of the surface Green function for this electrode.

The imaginary part is only used in the non-equilibrium contours since the equilibrium are

already lifted into the complex plane. Thus this η reﬂects the imaginary part in the GΓG

†

calculations. Ensure that all imaginary values are larger than 0 as otherwise TranSIESTA

may seg-fault.

NOTE: if this energy is negative the complex value associated with the non-equilibrium

contour is used. This is particularly useful when providing a user-deﬁned contour along the

real axis.

Accuracy depends on: TS.Elecs.Accuracy

Control the convergence accuracy required for the self-energy calculation when using the

Lopez-Sanchez, Lopez-Sanchez iterative scheme.

NOTE: advanced use only.

DE Density and energy density matrix ﬁle for the electrode. This may be used to initialize the

density matrix elements in the electrode region by the bulk values. See TS.Elec.<>.DM-

init bulk.

NOTE: this should only be performed on one TranSIESTA calculation as then the scat-

tering region SystemLabel.TSDE contains the electrode density matrix.

Bloch 3 integers should be present on this line which each denote the number of times bigger

the scattering region electrode is compared to the electrode, in each lattice direction. Remark

that these expansion coeﬃcients are with regard to the electrode unit-cell. This is denoted

“Bloch” because it is an expansion based on Bloch waves.

NOTE: Using symmetries such as periodicity will greatly increase performance.

Bloch-A/a1|B/a2|C/a3 Speciﬁc Bloch expansions in each of the electrode unit-cell direction.

See Bloch for details.

pre-expand String denoting how the expansion of the surface Green function ﬁle will be per-

formed. This only aﬀects the Green function ﬁle if Bloch is larger than 1. By default the

Green function ﬁle will contain the fully expanded surface Green function, but not Hamilto-

nian and overlap matrices (Green). One may reduce the ﬁle size by setting this to Green

which only expands the surface Green function. Finally none may be passed to reduce the

ﬁle size to the bare minimum. For performance reasons all is preferred.

If disk-space is a limited resource and the SystemLabel.TSGF* ﬁles are really big, try none.

out-of-core If true (default) the GF ﬁles are created which contain the surface Green function.

If false the surface Green function will be calculated when needed. Setting this to false will

heavily degrade performance and it is highly discouraged!

delta-Ef Specify an oﬀset for the Fermi-level of the electrode. This will directly be added to

the Fermi-level found in the electrode ﬁle.

NOTE: this option only makes sense for semi-conducting electrodes since it shifts the entire

electronic structure. This is because the Fermi-level may be arbitrarily placed anywhere in

the band gap. It is the users responsibility to deﬁne a value which does not introduce a

potential drop between the electrode and device region. Please do not use unless you really

149

know what you are doing.

V-fraction Specify the fraction of the chemical potential shift in the electrode-device coupling

region. This corresponds to:

← H

+ µ

V − fractionS

(27)

in the coupling region. Consequently the value must be between 0 and 1.

NOTE: this option only makes sense for TS.Elec.<>.DM-update none since otherwise

the electrostatic potential will be incorporated in the Hamiltonian.

check-kgrid For N

electrode calculations the k mesh will sometimes not be equivalent for

the electrodes and the device region calculations. However, TranSIESTA requires that the

device and electrode k samplings are commensurate. This ﬂag controls whether this check is

enforced for a given electrode.

NOTE: only use if fully aware of the implications!

There are several ﬂags which are globally controlling the variables for the electrodes (with

TS.Elec.<> taking precedence).

TS.Elecs.Bulk true (logical)

This globally controls how the Hamiltonian is treated in all electrodes. See TS.Elec.<>.Bulk.

TS.Elecs.Eta 1 meV (energy)

Globally control the imaginary energy (η) used for the surface Green function calculation on

the non-equilibrium contour. See TS.Elec.<>.Eta for extended details on the usage of this

ﬂag.

TS.Elecs.Accuracy 10

−13

eV (energy)

Globally control the accuracy required for convergence of the self-energy. See

TS.Elec.<>.Accuracy.

TS.Elecs.Neglect.Principal false (logical)

If this is false TranSIESTA dies if there are connections beyond the principal cell.

NOTE: set this to true with care, non-physical results may arise. Use at your own risk!

TS.Elecs.Gf.Reuse true (logical)

Globally control whether the surface Green function ﬁles should be re-used (true) or re-created

(false).

See TS.Elec.<>.Gf-Reuse.

TS.Elecs.Out-of-core true (logical)

Whether the electrodes will calculate the self energy at each SCF step. Using this will not

require the surface Green function ﬁles but at the cost of heavily degraded performance.

See TS.Elec.<>.Out-of-core.

TS.Elecs.DM.Update cross-terms|all|none (string)

Globally controls which parts of the electrode density matrix gets updated.

See TS.Elec.<>.DM-update.

150

TS.Elecs.DM.Init diagon|bulk|force-bulk (string)

Specify how the density matrix elements in the electrode regions of the scattering region will

be initialized when starting TranSIESTA.

See TS.Elec.<>.DM-init.

TS.Elecs.Coord.EPS 0.001 Ang (length)

When using Bloch expansion of the self-energies one may experience diﬃculties in obtaining

perfectly aligned electrode coordinates.

This parameter controls how strict the criteria for equivalent atomic coordinates is. If Tran-

SIESTA crashes due to mismatch between the electrode atomic coordinates and the scattering

region calculation, one may increase this criteria. This should only be done if one is sure that

the atomic coordinates are almost similar and that the diﬀerence in electronic structures of the

two may be negligible.

10.6.6 Chemical potentials

For N

electrodes there will also be N

chemical potentials. They are deﬁned via blocks similar to

TS.Elecs.

%block TS.ChemPots 〈None〉 (block)

Each line denotes a new chemical potential which is deﬁned in the TS.ChemPot.<> block.

%block TS.ChemPot.<> 〈None〉 (block)

Each line deﬁnes a setting for the chemical potential named <>.

chemical-shift|mu Deﬁne the chemical shift (an energy) for this chemical potential. One may

specify the shift in terms of the applied bias using V/<integer> instead of explicitly typing

the energy.

contour.eq A subblock which deﬁnes the integration curves for the equilibrium contour for

this equilibrium chemical potential. One may supply as many diﬀerent contours to create

whatever shape of the contour

Its format is

contour.eq

begin

<contour-name-1>

<contour-name-2>

...

end

NOTE: If you do not specify contour.eq in the block one will automatically use the con-

tinued fraction method and you are encouraged to use 50 or more poles

[9]

ElectronicTemperature|Temp|kT Specify the electronic temperature (as an energy or in

Kelvin). This defaults to TS.ElectronicTemperature.

One may specify this in units of TS.ElectronicTemperature by using the unit kT.

contour.eq.pole Deﬁne the number of poles used via an energy speciﬁcation. TranSIESTA

will automatically convert the energy to the closest number of poles (rounding up).

NOTE: this has precedence over TS.ChemPot.<>.contour.eq.pole.N if it is speciﬁed

151

and a positive energy. Set this to a negative energy to directly control the number of poles.

contour.eq.pole.N Deﬁne the number of poles via an integer.

NOTE: this will only take eﬀect if TS.ChemPot.<>.contour.eq.pole is a negative energy.

NOTE: It is important to realize that the parametrization in 4.1 of the voltage into the chemical

potentials enables one to have a single input ﬁle which is never required to be changed, even

when changing the applied bias (if using the command line options for specifying the applied

bias). This is diﬀerent from 4.0 and prior versions since one had to manually change the

TS.biasContour.NumPoints for each applied bias.

These options complicate the input sequence for regular 2 electrode which is unfortunate.

Using tselecs.sh -only-mu yields this output:

%block TS.ChemPots

Left

Right

%endblock

%block TS.ChemPot.Left

mu V/2

contour.eq

begin

C-Left

T-Left

end

%endblock

%block TS.ChemPot.Right

mu -V/2

contour.eq

begin

C-Right

T-Right

end

%endblock

Note that the default is a 2 electrode setup with chemical potentials associated directly with the

electrode names “Left”/“Right”. Each chemical potential has two parts of the equilibrium contour

named according to their name.

10.6.7 Complex contour integration options

Specifying the contour for N

electrode systems is a bit extensive due to the possibility of more

than 2 chemical potentials. Please use the Util/TS/tselecs.sh as a means to create default input

blocks.

The contours are split in two segments. One, being the equilibrium contour of each of the diﬀerent

chemical potentials. The second for the non-equilibrium contour. The equilibrium contours are

shifted according to their chemical potentials with respect to a reference energy. Note that for

TranSIESTA the reference energy is named the Fermi-level, which is rather unfortunate (for non-

equilibrium but not equilibrium). Fortunately the non-equilibrium contours are deﬁned from diﬀerent

chemical potentials Fermi functions, and as such this contour is deﬁned in the window of the minimum

152

and maximum chemical potentials. Because the reference energy is the periodic Fermi level it is

advised to retain the average chemical potentials equal to 0. Otherwise applying diﬀerent bias will

shift transmission curves calculated via TBtrans relative to the average chemical potential.

In this section the equilibrium contours are deﬁned, and in the next section the non-equilibrium

contours are deﬁned.

TS.Contours.Eq.Pole 1.5 eV (energy)

The imaginary part of the line integral crossing the chemical potential. Note that the actual

number of poles may diﬀer between diﬀerent calculations where the electronic temperatures are

diﬀerent.

NOTE: if the energy speciﬁed is negative, TS.Contours.Eq.Pole.N takes eﬀect.

TS.Contours.Eq.Pole.N 8 (integer)

Manually select the number poles for the equilibrium contour.

NOTE: this ﬂag will only take eﬀect if TS.Contours.Eq.Pole is a negative energy.

%block TS.Contour.<> 〈None〉 (block)

Specify a contour named <> with options within the block.

The names <> are taken from the TS.ChemPot.<>.contour.eq block in the chemical po-

tentials.

The format of this block is made up of at least 4 lines, in the following order of appearance.

part Specify which part of the equilibrium contour this is:

circle The initial circular part of the contour

square The initial square part of the contour

line The straight line of the contour

tail The ﬁnal part of the contour must be a tail which denotes the Fermi function tail.

from a to b Deﬁne the integration range on the energy axis. Thus a and b are energies.

The parameters may also be given values prev/next which is the equivalent of specifying

the same energy as the previous contour it is connected to.

NOTE: that b may be supplied as inf for tail parts.

points/delta Deﬁne the number of integration points/energy separation. If specifying the num-

ber of points an integer should be supplied.

If specifying the separation between consecutive points an energy should be supplied.

method Specify the numerical method used to conduct the integration. Here a number of

diﬀerent numerical integration schemes are accessible

mid|mid-rule Use the mid-rule for integration.

simpson|simpson-mix Use the composite Simpson 3/8 rule (three point Newton-Cotes).

boole|boole-mix Use the composite Booles rule (ﬁve point Newton-Cotes).

G-legendre Gauss-Legendre quadrature.

NOTE: has opt left

NOTE: has opt right

153

tanh-sinh Tanh-Sinh quadrature.

NOTE: has opt precision <>

NOTE: has opt left

NOTE: has opt right

G-Fermi Gauss-Fermi quadrature (only on tails).

opt Specify additional options for the method. Only a selected subset of the methods have

additional options.

These options complicate the input sequence for regular 2 electrode which is unfortunate. However,

it allows highly customizable contours.

Using tselecs.sh -only-c yields this output:

TS.Contours.Eq.Pole 2.5 eV

%block TS.Contour.C-Left

part circle

from -40. eV + V/2 to -10 kT + V/2

points 25

method g-legendre

opt right

%endblock

%block TS.Contour.T-Left

part tail

from prev to inf

points 10

method g-fermi

%endblock

%block TS.Contour.C-Right

part circle

from -40. eV -V/2 to -10 kT -V/2

points 25

method g-legendre

opt right

%endblock

%block TS.Contour.T-Right

part tail

from prev to inf

points 10

method g-fermi

%endblock

These contour options refer to input options for the chemical potentials as shown in Sec. 10.6.6

(p. 151). Importantly one should note the shift of the contours corresponding to the chemical

potential (the shift corresponds to diﬀerence from the reference energy used in TranSIESTA).

10.6.8 Bias contour integration options

The bias contour is similarly deﬁned as the equilibrium contours. Please use the

Util/TS/tselecs.sh as a means to create default input blocks.

154

TS.Contours.nEq.Eta 0 eV (energy)

The imaginary part (η) of the device states. Generally this is not necessary to deﬁne as the

imaginary part naturally arises from the self-energies (where η > 0).

TS.Contours.nEq.Fermi.Cutoﬀ 5 k

T (energy)

The bias contour is limited by the Fermi function tails. Numerically it does not make sense to

integrate to inﬁnity. This energy deﬁnes where the bias integration window is turned into zero.

Thus above −|V |/2 − E or below |V |/2 + E the DOS is deﬁned as exactly zero.

%block TS.Contours.nEq 〈None〉 (block)

Each line deﬁnes a new contour on the non-equilibrium bias window. The contours deﬁned must

be deﬁned in TS.Contour.nEq.<>.

These contours must all be part line or part tail.

%block TS.Contour.nEq.<> 〈None〉 (block)

This block is exactly equivalently deﬁned as the TS.Contour.<>. See page 153.

The default options related to the non-equilibrium bias contour are deﬁned as this:

%block TS.Contours.nEq

neq

%endblock TS.Contours.nEq

%block TS.Contour.nEq.neq

part line

from -|V|/2 - 5 kT to |V|/2 + 5 kT

delta 0.01 eV

method mid-rule

%endblock TS.Contour.nEq.neq

If one chooses a diﬀerent reference energy than 0, then the limits should change accordingly. Note

that here kT refers to TS.ElectronicTemperature.

10.7 Output

TranSIESTA generates several output ﬁles.

SystemLabel.DM : The SIESTA density matrix. SIESTA initially performs a calculation at zero

bias assuming periodic boundary conditions in all directions, and no voltage, which is used as

a starting point for the TranSIESTA calculation.

SystemLabel.TSDE : The TranSIESTA density matrix and energy density matrix. During a

TranSIESTA run, the SystemLabel.DM values are used for the density matrix in the buﬀer

(if used) and electrode regions. The coupling terms may or may not be updated in a Tran-

SIESTA run, see TS.Elec.<>.DM-update.

SystemLabel.TSHS : The Hamiltonian corresponding to SystemLabel.TSDE. This ﬁle also contains

geometry information etc. needed by TranSIESTA and TBtrans.

155

SystemLabel.TS.KP : The k-points used in the TranSIESTA calculation. See SIESTA

SystemLabel.KP ﬁle for formatting information.

SystemLabel.TSFA : Forces only on atoms in the device region. See TS.Forces for details.

SystemLabel.TSCCEQ* : The equilibrium complex contour integration paths.

SystemLabel.TSCCNEQ* : The non-equilibrium complex contour integration paths for correcting the

equilibrium contours.

SystemLabel.TSGF* : Self-energy ﬁles containing the used self-energies from the leads. These are

very large ﬁles used in the SCF loop. Once completed one can safely delete these ﬁles. For

heavily increased throughput these ﬁles may be re-used for the same electrode settings in

various calculations.

10.8 Utilities for analysis: TBtrans

Please see the separate TBtrans manual (tbtrans.pdf).

11 ANALYSIS TOOLS

There are a number of analysis tools and programs in the Util directory. Some of them have

been directly or indirectly mentioned in this manual. Their documentation is the appropriate sub-

directory of Util. See Util/README.

In addition to the shipped utilities SIESTA is also oﬃcially supported by sisl

[13]

which is a Python

library enabling many of the most commonly encountered things.

12 SCRIPTING

In the Util/Scripting directory we provide an experimental python scripting framework built on

top of the “Atomic Simulation Environment” (see https://wiki.fysik.dtu.dk/ase) by the CAMD

group at DTU, Denmark.

(NOTE: “ASE version 2”, not the new version 3, is needed)

There are objects implementing the “Siesta as server/subroutine” feature, and also hooks for ﬁle-

oriented-communication usage. This interface is diﬀerent from the SIESTA-speciﬁc functionality

already contained in the ASE framework.

Users can create their own scripts to customize the “outer geometry loop” in SIESTA, or to perform

various repetitive calculations in compact form.

Note that the interfaces in this framework are still evolving and are subject to change.

Suggestions for improvements can be sent to Alberto Garcia ([email protected])

156

13 PROBLEM HANDLING

13.1 Error and warning messages

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

similar messages.

Description: Some array dimensions which change infrequently, and do not lead to much

memory use, are ﬁxed to oversized values. This message means that one of this parameters

is too small and neads to be increased. However, if this occurs and your system is not very

large, or unusual in some sense, you should suspect ﬁrst of a mistake in the data ﬁle (incorrect

atomic positions or cell dimensions, too large cutoﬀ radii, etc).

Fix: Check again the data ﬁle. Look for previous warnings or suspicious values in the output.

If you ﬁnd nothing unusual, edit the speciﬁed routine and change the corresponding parameter.

14 REPORTING BUGS

Your assistance is essential to help improve the program. If you ﬁnd any problem, or would like to

oﬀer a suggestion for improvement, please follow the instructions in the ﬁle Docs/REPORTING_BUGS.

Since SIESTA has moved to https://gitlab.com/siesta-project/siesta you are encouraged to

follow the instructions by pressing “New Issue” and selecting “Bug” in the Description drop-down.

Also please follow the debug build options, see Sec. 2.3

15 ACKNOWLEDGMENTS

We want to acknowledge the use of a small number of routines, written by other authors, in de-

veloping 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

attribution, or suspect that other routines may be due to diﬀerent authors, please let us know.

• The main nonpublic contribution, that we thank thoroughly, are modiﬁed 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 ﬁles 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 SiestaXC were written by J.M.Soler in 1996 and

1997, in collaboration with C. Balbás and J. L. Martins. Routine pzxc, which implements

the Perdew-Zunger LDA parametrization of xc, is based on routine velect, written by S.

Froyen.

• The serial version of the multivariate fast fourier transform used to solve Poisson’s equation

was written by Clive Temperton.

• Subroutine iomd.f for writing MD history in ﬁles was originally written by J. Kohanoﬀ.

157

We want to thank very specially O. F. Sankey, D. J. Niklewski and D. A. Drabold for making

the FIREBALL code available to P. Ordejón. Although we no longer use the routines in that code,

it was essential in the initial development of the SIESTA project, which still uses many of the

algorithms developed by them.

We thank V. Heine for his support and encouraging us in this project.

The SIESTA project is supported by the Spanish DGES through several contracts. We also ac-

knowledge past support by the Fundación Ramón Areces.

158

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

force Ry/Bohr 4.11943E-8

159

Magnitude Unit name MKS value

pressure Pa 1.E0

pressure MPa 1.E6

pressure GPa 1.E9

pressure atm 1.01325E5

pressure bar 1.E5

pressure Kbar 1.E8

pressure Mbar 1.E11

pressure Ry/Bohr**3 1.47108E13

pressure eV/Ang**3 1.60219E11

charge C 1.E0

charge e 1.602177E-19

dipole C*m 1.E0

dipole D 3.33564E-30

dipole debye 3.33564E-30

dipole e*Bohr 8.47835E-30

dipole e*Ang 1.602177E-29

MomInert Kg*m**2 1.E0

MomInert Ry*fs**2 2.17991E-48

Eﬁeld V/m 1.E0

Eﬁeld V/nm 1.E9

Eﬁeld V/Ang 1.E10

Eﬁeld V/Bohr 1.8897268E10

Eﬁeld Ry/Bohr/e 2.5711273E11

Eﬁeld Har/Bohr/e 5.1422546E11

Eﬁeld Ha/Bohr/e 5.1422546E11

angle deg 1.d0

angle rad 5.72957795E1

torque eV/deg 1.E0

torque eV/rad 1.745533E-2

torque Ry/deg 13.6058E0

torque Ry/rad 0.237466E0

torque meV/deg 1.E-3

torque meV/rad 1.745533E-5

torque mRy/deg 13.6058E-3

torque mRy/rad 0.237466E-3

160

17 APPENDIX: XML Output

From version 2.0, SIESTA includes an option to write its output to an XML ﬁle. The XML

it produces is in accordance with the CMLComp subset of version 2.2 of the Chemical Markup

Language. Further information and resources can be found at http://cmlcomp.org/ and tools for

working with the XML ﬁle can be found in the Util/CMLComp directory.

The main motivation for standarised XML (CML) output is as a step towards standarising formats

for uses like the following.

• To have SIESTA communicating with other software, either for postprocessing or as part of a

larger workﬂow scheme. In such a scenario, the XML output of one SIESTA simulation may

be easily parsed in order to direct further simulations. Detailed discussion of this is out of the

scope of this manual.

• To generate webpages showing SIESTA output in a more accessible, graphically rich, fashion.

This section will explain how to do this.

17.1 Controlling XML output

XML.Write true (logical)

Determine if the main XML ﬁle should be created for this run.

17.2 Converting XML to XHTML

The translation of the SIESTA XML output to a HTML-based webpage is done using XSLT tech-

nology. The stylesheets conform to XSLT-1.0 plus EXSLT extensions; an xslt processor capable of

dealing with this is necessary. However, in order to make the system easy to use, a script called

ccViz is provided in Util/CMLComp that works on most Unix or Mac OS X systems. It is run like so:

./ccViz SystemLabel.xml

A new ﬁle will be produced. Point your web-browser at SystemLabel.xhtml to view the output.

The generated webpages include support for viewing three-dimensional interactive images of the

system. If you want to do this, you will either 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 Runtime

Environment and browser plugin - installation instructions for these are outside the scope of this

manual, though. However, the webpages are still useful and may be viewed without this plugin.

An online version of this tool is avalable from http://cmlcomp.org/ccViz/, as are updated versions

of the ccViz script.

161

18 APPENDIX: Selection of precision for storage

Some of the real arrays used in Siesta are by default single-precision, to save memory. This applies

to the array that holds the values of the basis orbitals on the real-space grid, to the historical data

sets in Broyden mixing, and to the arrays used in the O(N) routines. Note that the grid functions

(charge densities, potentials, etc) are now (since mid January 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 diﬀerences and will have a negligible eﬀect 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 signiﬁcantly increase the memory used for

large problems, with negligible diﬀerences 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 ac-

celeration 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.

162

19 APPENDIX: Data structures and reference counting

To implement some of the new features (e.g. charge mixing and DM extrapolation), SIESTA uses

new ﬂexible data structures. These are deﬁned and handled through a combination and extension

of ideas already in the Fortran community:

• Simple templating using the “include ﬁle” mechanism, as for example 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 objects. For example, a circular

stack is used in the charge-mixing module. A number of future enhancements depend on this

paradigm.

163

References

[1] T. Auckenthaler, V. Blum, H.-J. Bungartz, T. Huckle, R. Johanni, L. Krämer, B. Lang, H. Led-

erer, and P.R. Willems. Parallel solution of partial symmetric eigenvalue problems from elec-

tronic structure calculations. Parallel Computing, 37(12):783 – 794, 2011. ISSN 0167-8191.

doi: http://dx.doi.org/10.1016/j.parco.2011.05.002. URL http://www.sciencedirect.com/

science/article/pii/S0167819111000494. 6th International Workshop on Parallel Matrix

Algorithms and Applications (PMAA’10).

[2] Amartya S. Banerjee, Phanish Suryanarayana, and John E. Pask. Periodic Pulay method

for robust and eﬃcient convergence acceleration of self-consistent ﬁeld iterations. Chemical

Physics Letters, 647:31–35, mar 2016. ISSN 00092614. doi: 10.1016/j.cplett.2016.01.033. URL

http://linkinghub.elsevier.com/retrieve/pii/S0009261416000464.

[3] D.R Bowler and M.J Gillan. An eﬃcient and robust technique for achieving self consistency

in electronic structure calculations. Chemical Physics Letters, 325(4):473–476, jul 2000. ISSN

00092614. doi: 10.1016/S0009-2614(00)00750-8. URL http://linkinghub.elsevier.com/

retrieve/pii/S0009261400007508.

[4] Mads Brandbyge, José-Luis Mozos, Pablo Ordejón, Jeremy Taylor, and Kurt Stokbro. Density-

functional method for nonequilibrium electron transport. Physical Review B, 65(16):165401,

mar 2002. ISSN 0163-1829. doi: 10.1103/PhysRevB.65.165401. URL http://link.aps.org/

doi/10.1103/PhysRevB.65.165401.

[5] Alberto García, Nick Papior, Arsalan Akhtar, Emilio Artacho, Volker Blum, Emanuele Bosoni,

Pedro Brandimarte, Mads Brandbyge, J. I. Cerdá, Fabiano Corsetti, Ramón Cuadrado,

Vladimir Dikan, Jaime Ferrer, Julian Gale, Pablo García-Fernández, V. M. García-Suárez,

Sandra García, Georg Huhs, Sergio Illera, Richard Korytár, Peter Koval, Irina Lebedeva, Lin

Lin, Pablo López-Tarifa, Sara G. Mayo, Stephan Mohr, Pablo Ordejón, Andrei Postnikov,

Yann Pouillon, Miguel Pruneda, Roberto Robles, Daniel Sánchez-Portal, Jose M. Soler, Raﬁ

Ullah, Victor Wen-zhe Yu, and Javier Junquera. Siesta: Recent developments and applica-

tions. The Journal of Chemical Physics, 152(20):204108, 2020. doi: 10.1063/5.0005077. URL

https://doi.org/10.1063/5.0005077.

[6] G. Kresse and J. Furthmüller. Eﬃciency of ab-initio total energy calculations for metals and

semiconductors using a plane-wave basis set. Computational Materials Science, 6(1):15–50,

jul 1996. ISSN 09270256. doi: 10.1016/0927-0256(96)00008-0. URL http://linkinghub.

elsevier.com/retrieve/pii/0927025696000080.

[7] Lin Lin, Alberto García, Georg Huhs, and Chao Yang. SIESTA-PEXSI: massively paral-

lel method for eﬃcient and accurate ab initio materials simulation without matrix diagonal-

ization. Journal of Physics: Condensed Matter, 26(30):305503, jul 2014. ISSN 0953-8984.

doi: 10.1088/0953-8984/26/30/305503. URL http://stacks.iop.org/0953-8984/26/i=30/

a=305503?key=crossref.dd07c5e621546c5e67b1052b8800daca.

[8] A Marek, V Blum, R Johanni, V Havu, B Lang, T Auckenthaler, A Heinecke, H-J Bungartz,

and H Lederer. The elpa library: scalable parallel eigenvalue solutions for electronic structure

theory and computational science. Journal of Physics: Condensed Matter, 26(21):213201, 2014.

URL http://stacks.iop.org/0953-8984/26/i=21/a=213201.

164

[9] Taisuke Ozaki, Kengo Nishio, and Hiori Kino. Eﬃcient implementation of the nonequilibrium

Green function method for electronic transport calculations. Physical Review B, 81(3):035116,

jan 2010. ISSN 1098-0121. doi: 10.1103/PhysRevB.81.035116. URL http://link.aps.org/

doi/10.1103/PhysRevB.81.035116.

[10] Nick Papior, Tue Gunst, Daniele Stradi, and Mads Brandbyge. Manipulating the voltage drop

in graphene nanojunctions using a gate potential. Phys. Chem. Chem. Phys., 18(2):1025–

1031, 2016. ISSN 1463-9076. doi: 10.1039/C5CP04613K. URL http://xlink.rsc.org/?DOI=

C5CP04613K.

[11] Nick Papior, Nicolás Lorente, Thomas Frederiksen, Alberto García, and Mads Brandbyge. Im-

provements on non-equilibrium and transport Green function techniques: The next-generation

TranSiesta. Computer Physics Communications, 212:8–24, mar 2017. ISSN 00104655. doi:

10.1016/j.cpc.2016.09.022. URL https://doi.org/10.1016/j.cpc.2016.09.022.

[12] Nick Papior, Gaetano Calogero, Susanne Leitherer, and Mads Brandbyge. Removing all periodic

boundary conditions: Eﬃcient nonequilibrium Green’s function calculations. Physical Review

B, 100(19):195417, nov 2019. ISSN 2469-9950. doi: 10.1103/PhysRevB.100.195417. URL

https://link.aps.org/doi/10.1103/PhysRevB.100.195417.

[13] Nick R. Papior. sisl, 2020. URL https://doi.org/10.5281/zenodo.597181.

[14] M P Lopez Sancho, J M Lopez Sancho, and J. Rubio. Highly convergent schemes for the

calculation of bulk and surface Green functions. Journal of Physics F: Metal Physics, 15(4):

851–858, apr 1985. ISSN 0305-4608. doi: 10.1088/0305-4608/15/4/009. URL http://stacks.

iop.org/0305-4608/15/i=4/a=009?key=crossref.8c77f34b0366ff84eaf622609268f5a2.

[15] José M. Soler and Eduardo Anglada. Optimal fourier ﬁltering of a function that is strictly

conﬁned 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.

165

Index

animation, 46

antiferromagnetic initial DM, 64

Backward compatibility, 60, 115

band structure, 91

basis, 37

basis set superposition error (BSSE), 36

Bessel functions, 36

default soft conﬁnement, 31

default soft conﬁnement potential, 32

default soft conﬁnement radius, 32

ﬁlteret basis set, 35

ﬁltering, 36, 37

ﬁx split-valence table, 31

Gen-basis standalone program, 37

ghost atoms, 36

minimal, 29

new split-valence code, 30, 31

PAO, 29, 30, 34

per-shell split norm, 35

point at inﬁnity, 39

polarization, 29, 36

reparametrization of pseudopotential, 38, 39

soft conﬁnement potential, 35

split valence, 30

split valence for H, 30

User basis, 37

User basis (NetCDF format), 37

Berry phase, 98

Bessel functions, 36

%block, 21

Born eﬀective charges, 99

Broyden mixing, 162

Broyden optimization, 117

bug reports, 157

bulk polarization, 98

cell relaxation, 115

Cerius2, 46

Charge conﬁnement, 28, 35

Charge of the system, 102, 106

Chebyshev Polynomials, 82

Chemical Potential, 82, 83

CML, 161

compile

libraries, 14

MPI, 12

OpenMP, 13

pre-processor

-DCDF, 16

-DMPI, 13

-DMPI_TIMING, 111

-DNCDF, 16

-DNCDF_4, 16, 113

-DNCDF_PARALLEL, 16

-DSIESTA__DIAG_2STAGE, 76

-DSIESTA__ELPA, 16

-DSIESTA__FLOOK, 17

-DSIESTA__METIS, 16

-DSIESTA__MRRR, 76, 78

-DSIESTA__MUMPS, 16

-DSIESTA__PEXSI, 17

Conjugate-gradient history information, 117

constant-volume cell relaxation, 116

constraints in relaxations, 122

COOP/COHP curves, 96

Folding in Gamma-point calculations, 73

cutoﬀ radius, 34

Data Structures, 163

denchar, 112

density of states, 78, 93

Dielectric function,optical absorption, 97

diﬀuse orbitals, 29

Doping, 102, 106

double-ζ, 29

egg-box eﬀect, 70, 71, 73

Eig2DOS, 78, 93

ELPA, 16

exchange-correlation

AM05, 49

BH, 50

BLYP, 50

C09, 50

CA, 49

cellXC, 51

DRSLL, 50

166

GGA, 49

KBM, 50

LDA, 49

LMKLL, 50

LSD, 49

PBE, 49

PBEGcGxHEG, 50

PBEGcGxLO, 50

PBEJsJrHEG, 50

PBEJsJrLO, 49

PBEsol, 49

PW91, 49

PW92, 49

PZ, 49

revPBE, 49

RPBE, 49

vdW, 50

vdW-DF, 50

vdW-DF1, 50

vdW-DF2, 50

VV, 50

WC, 49

External library

BLAS, 14

ELPA, 16

fdict, 15

ﬂook, 17, 114

LAPACK, 15

Metis, 16

MPI, 12

MUMPS, 16, 138

ncdf, 16

NetCDF, 16

OpenMP, 13

PEXSI, 17

ScaLAPACK, 15

fatbands, 91

FDF, 20

fdf.log, 19, 21

ferromagnetic initial DM, 64

ﬁnite-range pseudo-atomic orbitals, 29

ﬁxed spin state, 51

ﬂook, 17, 114

Force Constants Matrix, 114, 125

fractional program, 24

Gate, 104

bounded plane, 105

box, 105

inﬁnite plane, 104

spheres, 105

Gaussians, 29

Gen-basis, 25

Gen-basis, 37

ghost atoms, 24, 36

gnubands, 91

grid, 70

Grid precision, 162

Ground-state atomic conﬁguration, 30

Hirshfeld population analysis, 95, 96

input ﬁle, 20

interatomic distances, 47

isotopes, 24

JMol, 45

JSON timing report, 112

Kleinman-Bylander projectors, 32

Localized Wave Functions, 82, 83

Lower order N memory, 83

LSD, 51

Makeﬁle, 11

mesh, 70

Metis, 16

minimal basis, 29

mixps program, 24

Molden, 45, 46

Mulliken population analysis, 22, 95

multiple-ζ, 29, 30

MUMPS, 16, 138

NetCDF format, 16, 37

3, 16

4, 16

output

δρ(~r), 106

atomic coordinates

in a dynamics step, 22, 120

initial, 120

Bader charge, 108

band

k points, 22, 91

167

band structure, 91

basis, 37

charge density, 106–108

charge density and/or wfs for DENCHAR

code, 112

customization, 22

dedicated ﬁles, 23

density matrix, 66, 67

density matrix history, 67

eigenvalues, 22, 78, 93

electrostatic potential, 107

forces, 22, 121

grid

k points, 22, 49

Hamiltonian, 67

Hamiltonian & overlap, 73

Hamiltonian history, 67

Hirshfeld analysis, 95, 96

HSX ﬁle, 73

Information for COOP/COHP curves, 96

ionic charge, 107

local density of states, 94

long, 22

main output ﬁle, 22

molecular dynamics

Force Constants Matrix, 125

history, 121

Mulliken analysis, 22, 95

overlap matrix, 67

overlap matrix history, 67

projected density of states, 93

total charge, 108

total potential, 107

Voronoi analysis, 95, 96

wave functions, 22, 92

output of wave functions for bands, 91, 92

perturbative polarization, 29

perturbative polarization, 36

PEXSI, 17

PEXSI solver, 83

polarization orbitals, 29

Precision selection, 162

pseudopotential

example generation, 18

ﬁles, 25

generation, 24

reading saved data, 112

all, 112

CG, 117

charge density, 65

deformation charge density, 66

density matrix, 64

localized wave functions (order-N), 83

XV, 46

ZM, 47

readwf, 93

readwfsx, 93

Reference counting, 163

relaxation of cell parameters only, 116

removal of intramolecular pressure, 118

Restart of O(N) calculations, 83

rippling, 70, 71, 73

scale factor, 36

SCF, 54

compat-pre4-dm-h, 60

Doping, 102, 106

mixing, 55, 61

Broyden, 57

Charge, 55, 61, 62

Density, 55

Density matrix convergence, 68

end of cycle, 61

energy convergence, 68

energy density matrix convergence, 68

Hamiltonian, 55

Hamiltonian convergence, 68

harris energy convergence, 69

Linear, 56

Pulay, 56

Potential, 104

Recomputing H, 61

SCF convergence criteria, 68

Scripting, 114

Sies2arc, 46

SIESTA, 8

single-ζ, 29

Slab dipole correction, 103

Slabs with net charge, 102

species, 23

spin, 51

initialization, 64

split valence, 29

168

structure input precedence issues, 47

synthetic atoms, 24

TBtrans, 156

Tests, 17, 134

TranSIESTA, 9

transiesta

electrode

principal layer, 135

Variational character of E_KS, 54

VCA, 24

VIBRA, 125

Voronoi population analysis, 95, 96

XML, 161

XMol, 45, 46

169

List of SIESTA ﬁles

arch.make, 11–14, 16, 17, 76, 162

BaderCharge.grid.nc, 108

BASIS_ENTHALPY, 38, 69

BASIS_HARRIS_ENTHALPY, 69

Chlocal.grid.nc, 107

constr.f, 123

DeltaRho.grid.nc, 107

DeltaRho.IN.grid.nc, 66

DM-NNNN.nc, 67

DM.nc, 67

DM_MIXED.blocked, 66

DM_OUT.blocked, 66

DMHS-NNNN.nc, 67

DMHS.nc, 67

ElectrostaticPotential.grid.nc, 107

GRAPHVIZ_atom.gv, 144

GRAPHVIZ_orbital.gv, 144

H_DMGEN, 67

H_MIXED, 67

m_new_dm.F, 74

NEXT_ITER.UCELL.ZMATRIX, 45

OUT.UCELL.ZMATRIX, 45

PEXSI_INTDOS, 89

Rho.grid.nc, 89, 106

Rho.IN.grid.nc, 65

RhoInit.grid.nc, 108

RhoXC.grid.nc, 107

Src/m_new_dm.F, 63

SystemLabel..arc, 46

SystemLabel..DM, 64

SystemLabel.alloc, 111

SystemLabel.amn, 101

SystemLabel.ANI, 46

SystemLabel.arc, 46

SystemLabel.ATOM.gv, 30

SystemLabel.BADER, 108

SystemLabel.bands, 90, 91

SystemLabel.bands.WFSX, 91

SystemLabel.BC, 100

SystemLabel.BONDS, 47

SystemLabel.BONDS_FINAL, 47

SystemLabel.CG, 117

SystemLabel.DIM, 112

SystemLabel.DM, 51, 54, 64, 66, 112, 132, 155

SystemLabel.DMF, 64

SystemLabel.DOS, 93, 94

SystemLabel.DRHO, 107

SystemLabel.EIG, 78, 89

SystemLabel.eigW, 101

SystemLabel.EPSIMG, 97

SystemLabel.FA, 121

SystemLabel.FAC, 121

SystemLabel.FC, 125

SystemLabel.FCC, 125

SystemLabel.fullBZ.WFSX, 78, 96, 97

SystemLabel.grid.nc, 66

SystemLabel.HS, 73

SystemLabel.HSX, 73, 96

SystemLabel.IOCH, 107

SystemLabel.KP, 49, 156

SystemLabel.LDOS, 94

SystemLabel.LDSI, 89

SystemLabel.LWF, 83, 112

SystemLabel.MD, 45, 120, 121

SystemLabel.MDC, 121

SystemLabel.MDE, 121

SystemLabel.MDX, 45, 120, 121

SystemLabel.mmn, 100

SystemLabel.N.TSHS, 67

SystemLabel.nc, 113

SystemLabel.nnkp, 100, 101

SystemLabel.ORB.gv, 30

SystemLabel.ORB_INDX, 121

SystemLabel.PDOS, 93, 94

SystemLabel.PDOS.xml, 94

SystemLabel.PLD, 112

SystemLabel.RHO, 106

SystemLabel.RHOINIT, 108

SystemLabel.RHOXC, 107

SystemLabel.selected.WFSX, 92

170

SystemLabel.STRUCT_IN, 45, 46

SystemLabel.STRUCT_NEXT_ITER, 45

SystemLabel.STRUCT_OUT, 45

SystemLabel.times, 111

SystemLabel.TOCH, 108

SystemLabel.TS.KP, 156

SystemLabel.TSCCEQ*, 156

SystemLabel.TSCCNEQ*, 156

SystemLabel.TSDE, 20, 132, 136, 143, 146, 149,

155

SystemLabel.TSFA, 141, 156

SystemLabel.TSFAC, 141

SystemLabel.TSGF*, 148, 149, 156

SystemLabel.TSHS, 20, 132, 134, 143, 147, 155

SystemLabel.VH, 107

SystemLabel.VNA, 107

SystemLabel.VT, 107

SystemLabel.WFS, 93, 96

SystemLabel.WFSX, 91–93, 96, 112

SystemLabel.xtl, 46

SystemLabel.XV, 45–47, 112, 117, 120

SystemLabel.xyz, 45

SystemLabel.ZM, 47

time.json, 112

TotalCharge.grid.nc, 108

TotalPotential.grid.nc, 107

TS_FERMI, 142

UNKXXXXX.Y, 101

Vna.grid.nc, 107

WFS.nc, 75, 78, 92

171

List of fdf ﬂags

AllocReportLevel, 111

AllocReportThreshold, 111

AnalyzeChargeDensityOnly, 108, 109

AtomCoorFormatOut, 41, 45, 46

AtomicCoordinatesAndAtomicSpecies, 23, 39,

41, 65, 122, 123

AtomicCoordinatesFormat, 40, 41, 45, 46

Ang, 40

Bohr, 40

Fractional, 41

NotScaledCartesianAng, 40

NotScaledCartesianBohr, 40

ScaledByLatticeVectors, 41

ScaledCartesian, 41

AtomicCoordinatesOrigin, 41, 46

AtomicMass, 24

AtomSetupOnly, 37

BandLines, 77, 90, 91

BandLinesScale, 90

BandPoints, 77, 90, 91

BasisPressure, 38

BlockSize, 75, 76, 81, 110

BornCharge, 99, 125

CDF

Compress, 113

Grid.Precision, 113

MPI, 113

Save, 113

ChangeKgridInMD, 48

ChemicalSpeciesLabel, 23–25, 34, 37, 39, 46, 47,

123

Command line options

-L, 20

-V, 20, 138

-elec, 20

-electrode, 20

-h, 20

-o, 20

-out, 20

Compat

Pre-v4-DM-H, 60, 61

Pre-v4-Dynamics, 114

Compat.Matel.NRTAB, 73

Constant

Volume, 115, 116

COOP.Write, 73, 78, 92, 96

Debug

DIIS, 62

DFTU

CutoﬀNorm, 126, 127

EnergyShift, 126, 127

FirstIteration, 127

PopTol, 127

PotentialShift, 127

Proj, 126

ProjectorGenerationMethod, 125, 126

ThresholdTol, 127

Diag

AbsTol, 77

Algorithm, 74, 76, 78

Divide-and-Conquer, 76

Divide-and-Conquer-2stage, 76

ELPA-1stage, 76

ELPA-2stage, 76

Expert, 76

Expert-2stage, 76

MRRR, 76

MRRR-2stage, 76

NoExpert, 76

NoExpert-2stage, 76

QR, 76

BlockSize, 75, 76

DivideAndConquer, 76–78

ELPA, 76–78

UseGPU, 77

Memory, 77

MRRR, 76–78

NoExpert, 76–78

OrFac, 77

ParallelOverK, 75–78

ProcessorY, 75

UpperLower, 77

Use2D, 75, 76

UseNewDiagk, 92

WFS.Cache, 75

cdf, 75, 78

172

none, 75

DirectPhi, 111

AllowExtrapolation, 65

AllowReuse, 65

FormattedFiles, 64

FormattedInput, 64

FormattedOutput, 64

History.Depth, 65

Init.Unfold, 64

InitSpin, 65

AF, 64, 65

KickMixingWeight, see

SF.Mixer.Kick.Weight58

MixingWeight, 57, see SF.Mixer.Weight57,

UseSaveDM, 55, 64

DM.EnergyTolerance, 69

DM.Init.Bulk, 139

DM.InitSpin, 53

DM.MixSCF1, 55, see SF.Mix.First55

DM.Normalization.Tolerance, 68

DM.NumberBroyden, 57, see

SF.Mixer.History57, 58

DM.NumberKick, see SF.Mixer.Kick58

DM.NumberPulay, 57, see SF.Mixer.History57,

DM.Require.Harris.Convergence, 69

DM.RequireEnergyConvergence, 68

DM.Tolerance, 68

DM.UseSaveDM, 81, 108

EggboxRemove, 71, 73

EggboxScale, 72, 73

ElectronicTemperature, 53, 79, 84, 139

ExternalElectricField, 102, 103

FilterCutoﬀ, 35–37

FilterTol, 37

ForceAuxCell, 73

Geometry

Charge, 103, 104, 106

Constraints, 122, 139

Hartree, 104, 106

Grid.CellSampling, 70, 71

Harris

Functional, 54

KB.New.Reference.Orbitals, 33

kgrid

Cutoﬀ, 47, 48, 94

MonkhorstPack, 40, 48, 94, 136, 138

kgrid.MonkhorstPack, 114

LatticeConstant, 39, 40, 52

LatticeParameters, 39, 40

LatticeVectors, 39–41, 48

LDAU

CutoﬀNorm, 126

EnergyShift, 126

FirstIteration, 127

PopTol, 127

PotentialShift, 127

Proj, 126

ProjectorGenerationMethod, 125

ThresholdTol, 127

LocalDensityOfStates, 94

LongOutput, 22, 23, 49, 120

Lua

Debug, 129

Debug.MPI, 129

Interactive, 129

Script, 128, 130

MaxBondDistance, 47

MaxSCFIterations, 54, 55

MaxWalltime, 112

Slack, 112

UseSaveXV, 46, 47

UseSaveZM, 47

MD.AnnealOption, 114, 118–120

MD.Broyden

Cycle.On.Maxit, 117

History.Steps, 117

Initial.Inverse.Jacobian, 117

MD.Broyden.Initial.Inverse.Jacobian, 116

MD.BulkModulus, 120

MD.ConstantVolume, 116

MD.FCDispl, 125

MD.FCFirst, 125

MD.FCLast, 125

MD.FinalTimeStep, 119

MD.FIRE.TimeStep, 118

173

MD.InitialTemperature, 119

MD.InitialTimeStep, 119

MD.LengthTimeStep, 118, 119

MD.MaxCGDispl, 116

MD.MaxDispl, 116, 117, 129

MD.MaxForceTol, 116, 129

MD.MaxStressTol, 115, 116

MD.NoseMass, 119

MD.NumCGsteps, 116

MD.ParrinelloRahmanMass, 119

MD.PreconditionVariableCell, 115, 116

MD.RelaxCellOnly, 116

MD.RemoveIntramolecularPressure, 118

MD.Steps, 116, 119

MD.TargetPressure, 118

MD.TargetStress, 118

MD.TargetTemperature, 119

MD.TauRelax, 120

MD.TypeOfRun, 47, 114, 118–120, 125, 127, 129

Anneal, 114, 120

Broyden, 114, 116

CG, 114–116

FC, 99, 114

FIRE, 114

Forces, 114

Lua, 113, 114

Master, 113, 114

Nose, 114

NoseParrinelloRahman, 114

ParrinelloRahman, 114

Verlet, 114

MD.UseSaveCG, 117

MD.UseSaveXV, 117

MD.VariableCell, 72, 114–116, 118

Mesh

Cutoﬀ, 36, 37, 53, 69, 70, 114, 128, 136

Sizes, 70

SubDivisions, 70

MinSCFIterations, 54

MM, 109

Cutoﬀ, 109

Grimme.D, 109, 110

Grimme.S6, 109, 110

Potentials, 109

UnitsDistance, 109

UnitsEnergy, 109

MPI

Nprocs.SIESTA, 84

MullikenInSCF, 95

MullikenInScf, 53

NeglNonOverlapInt, 73

NetCharge, 102, 103, 106

New

A.Parameter, 38

B.Parameter, 39

NonCollinearSpin, 51

NumberOfAtoms, 23, 40, 41

NumberOfEigenStates, 74, 76, 78

NumberOfSpecies, 23

OccupationFunction, 79

OccupationMPOrder, 79

OMM

BlockSize, 81

Diagon, 80, 81

DiagonFirstStep, 81

Eigenvalues, 81

LongOutput, 81

Precon, 80

PreconFirstStep, 80

ReadCoeﬀs, 81

RelTol, 81

TPreconScale, 81

Use2D, 80, 81

UseCholesky, 80

UseSparse, 80

WriteCoeﬀs, 81

Etol, 81

ON.ChemicalPotential, 82, 83

ON.ChemicalPotential.Order, 83

ON.ChemicalPotential.Rc, 83

ON.ChemicalPotential.Temperature, 83

ON.ChemicalPotential.Use, 83

ON.eta, 80, 82, 83

ON.eta.alpha, 82

ON.eta.beta, 82

ON.Etol, 82

ON.functional, 82

ON.LowerMemory, 83

ON.MaxNumIter, 82

ON.RcLWF, 82

ON.UseSaveLWF, 83

Optical.Broaden, 97

174

Optical.Energy.Maximum, 97

Optical.Energy.Minimum, 97

Optical.Mesh, 97

Optical.NumberOfBands, 97

Optical.OﬀsetMesh, 97

Optical.PolarizationType, 98

Optical.Scissor, 97

Optical.Vector, 98

OpticalCalculation, 97

PAO

Basis, 24, 26, 28–30, 34, 36

BasisSize, 29, 30, 34

DZ, 29

DZP, 29

minimal, 29

SZ, 29

SZP, 29

BasisSizes, 30

BasisType, 26, 29, 31, 34, 35

ﬁlteret, 29

nodes, 29

nonodes, 29

split, 29

splitgauss, 29

ContractionCutoﬀ, 31

EnergyCutoﬀ, 31

EnergyPolCutoﬀ, 31

EnergyShift, 29, 30, 34, 36–38

FixSplitTable, 31

NewSplitCode, 30, 31

OldStylePolOrbs, 36

SoftDefault, 28, 31, 34

SoftInnerRadius, 32

SoftPotential, 32

SplitNorm, 29, 30, 34

SplitNormH, 30, 34

SplitTailNorm, 31

PAO.Basis, 126

PAO.EnergyShift, 126

PartialChargesAtEveryGeometry, 96

PartialChargesAtEverySCFStep, 96

PDOS.kgrid.Cutoﬀ, 94

PDOS.kgrid.MonkhorstPack, 94

PEXSI

deltaE, 84

DOS, 89

Ef.Reference, 89

Emax, 89

Emin, 89

NPoints, 89

Gap, 84

Inertia-Counts, 87

Inertia-energy-width-tolerance, 88

Inertia-max-iter, 87

Inertia-min-num-shifts, 88

Inertia-mu-tolerance, 87, 88

lateral-expansion-inertia, 87

LDOS, 89

Broadening, 90

Energy, 90

NP-per-pole, 90

mu, 86

mu-max, 86, 87

mu-max-iter, 86

mu-min, 86, 87

mu-pexsi-safeguard, 86, 87

NP-per-pole, 85, 90

NP-symbfact, 85

num-electron-tolerance, 86

num-electron-tolerance-lower-bound, 86

num-electron-tolerance-upper-bound, 86

NumPoles, 84

Ordering, 85

safe-dDmax-ef-inertia, 88

safe-dDmax-ef-solver, 88

safe-dDmax-no-inertia, 87

safe-width-ic-bracket, 88

safe-width-solver-bracket, 88

Verbosity, 84, 85

PolarizationGrids, 98, 99

ProcessorY, 110

ProjectedDensityOfStates, 93

lmax, 32

PS.KBprojectors, 32

RcSpatial, 111

Reparametrize.Pseudos, 38, 39

Restricted.Radial.Grid, 38, 39

Rmax.Radial.Grid, 39

S.Only, 66

SaveBaderCharge, 108

SaveDeltaRho, 106

175

SaveElectrostaticPotential, 107, 113

SaveHS, 73

SaveInitialChargeDensity, 108

SaveIonicCharge, 107

SaveNeutralAtomPotential, 107

SaveRho, 106

SaveRhoXC, 107

SaveTotalCharge, 108

SaveTotalPotential, 107

SCF

MonitorForces, 54

MustConverge, 54, 55

RecomputeHAfterSCF, 61

RecomputeHAfterScf, 60

Want.Variational.EKS, 54

SCF.DebugRhoGMixing, 62

SCF.DM

Converge, 68, 69, 115, 139

Tolerance, 68, 139

SCF.EDM

Converge, 68

Tolerance, 68

SCF.FreeE

Converge, 68, 69

Tolerance, 69

SCF.H

Converge, 68, 69, 115, 139

Tolerance, 53, 68, 139

SCF.Harris

Converge, 69

Tolerance, 69

SCF.Kerker.q0sq, 62

SCF.Mix, 53, 55, 61

AfterConvergence, 54, 60, 61, 66, 67

First, 55, 56, 60, 103

First.Force, 55, 56

Spin, 55

SCF.MixCharge

SCF1, 62

SCF.Mixer

History, 57, 59

Kick, 58

Kick.Weight, 58

Linear.After, 58

Linear.After.Weight, 58

Method, 56–59

Restart, 58, 59

Restart.Save, 58, 59

Variant, 56, 57, 59

Weight, 57–59

SCF.Mixer.<>, 58

history, 59

iterations, 59

method, 59

next, 59

next.conv, 59

next.p, 59

restart, 59

restart.p, 59

restart.save, 59

variant, 59

weight, 59

weight.linear, 57, 59

SCF.Mixers, 58

SCF.Read.Charge.NetCDF, 65

SCF.Read.Deformation.Charge.NetCDF, 66

SCF.RhoG.DIIS.Depth, 62

SCF.RhoG.Metric.Preconditioner.Cutoﬀ, 62

SCF.RhoGMixingCutoﬀ, 62

Siesta2Wannier90.NumberOfBands, 101, 102

Siesta2Wannier90.NumberOfBandsDown, 102

Siesta2Wannier90.NumberOfBandsUp, 102

Siesta2Wannier90.UnkGrid1, 101

Siesta2Wannier90.UnkGrid2, 101

Siesta2Wannier90.UnkGrid3, 101

Siesta2Wannier90.UnkGridBinary, 101

Siesta2Wannier90.WriteAmn, 100

Siesta2Wannier90.WriteEig, 101

Siesta2Wannier90.WriteMmn, 100

Siesta2Wannier90.WriteUnk, 101

SimulateDoping, 102

SingleExcitation, 52

Slab.DipoleCorrection, 102, 103

charge, 103, 104

Origin, 103

Vacuum, 103, 104

vacuum, 103, 104

SolutionMethod, 48, 74, 78, 80, 138, 143

Spin, 51–53, 64, 65, 80

Fix, 51, 80

non-colinear, 51

non-polarized, 51

OrbitStrength, 53

polarized, 51

176

spin-orbit, 51

Spiral, 48, 51, 52

Spiral.Scale, 52

Total, 51, 80

SpinInSCF, 95

SpinOrbit, 51

SpinPolarized, 51

SuperCell, 39, 40, 48

SyntheticAtoms, 24

SystemLabel, 19, 20, 23, 45, 132

SystemName, 23

Target

Pressure, 115, 118

Stress.Voigt, 115, 118

Target.Stress.Voigt, 116

TimeReversalSymmetryForKpoints, 48

TimerReportThreshold, 111

Analyze, 133, 138, 143, 144

Analyze.Graphviz, 144

Atoms.Buﬀer, 137, 138

BTD

Guess1.Max, 145

Guess1.Min, 145

Optimize, 145

Pivot, 143, 144

Spectral, 145

ChemPot.<>, 151

chemical-shift, 151

contour.eq, 151, 153

contour.eq.pole, 151, 152

contour.eq.pole.N, 151, 152

ElectronicTemperature, 139, 151

kT, 151

mu, 151

Temp, 151

ChemPots, 148, 151

Contour.<>, 153, 155

delta, 153

from, 153

method, 153

opt, 154

part, 153

points, 153

Contour.nEq.<>, 155

Contours

Eq.Pole, 153

Eq.Pole.N, 153

Contours.nEq, 155

Eta, 155

Fermi.Cutoﬀ, 155

DE.Save, 20, 134, 143

true, 20, 143

dQ, 139, 141

Factor, 142

fermi, 141, 142, 148

Fermi.Eta, 143

Fermi.Max, 142

Fermi.Tolerance, 142

Elec.<>, 141, 147, 150

Accuracy, 149, 150

Bloch, 134, 135, 149

Bulk, 148, 150

check-kgrid, 136, 150

chemical-potential, 148

DE, 149

delta-Ef, 149

DM-init, 148, 151

DM-update, 148, 150, 155

electrode-position, 148

Eta, 149, 150

Gf, 148

Gf-Reuse, 148, 150

HS, 132, 147

Out-of-core, 149, 150

pre-expand, 149

semi-inf-direction, 147

used-atoms, 148

V-fraction, 150

Elecs, 144, 147, 151

Accuracy, 149, 150

Bulk, 150

Coord.EPS, 151

DM.Init, 139, 148, 151

DM.Update, 150

Eta, 149, 150

Gf.Reuse, 150

Neglect.Principal, 136, 150

Out-of-core, 150

ElectronicTemperature, 139, 151, 155

Fermi.Initial, 139

Forces, 141, 156

Hartree.Fix, 147

177

Frac, 147

Hartree.Oﬀset, 147

HS.Save, 20, 134, 143

true, 20, 143

kgrid

MonkhorstPack, 133, 136, 138

MUMPS

BlockingFactor, 146

Memory, 146

Ordering, 145

Poisson, 146

<ﬁle>, 146, 147

elec-box, 147

ramp, 146

S.Save, 143

SCF

DM.Tolerance, 139

dQ.Converge, 139

dQ.Tolerance, 139

H.Tolerance, 139

SCF.Initialize, 139

SIESTA.Only, 143

SolutionMethod, 138, 143

BTD, 138, 144

full, 138

MUMPS, 138

Voltage, 20, 138, 148

Weight.k.Method, 141

Weight.Method, 140

mean, 141

orb-orb, 140

sum-atom-atom, 140

sum-atom-orb, 141

tr-atom-atom, 140

tr-atom-orb, 140

Use.Blocked.WriteMat, 66, 67

UseDomainDecomposition, 110

UseNewDiagk, 75

UseParallelTimer, 112

User

Basis, 37

Basis.NetCDF, 37

User.Basis, 25

UseSaveData, 46, 47, 112, 117

UseSpatialDecomposition, 110

UseStructFile, 45–47

UseTreeTimer, 112

WarningMinimumAtomicDistance, 47

WaveFuncKPoints, 77, 92, 93, 96

WaveFuncKPointsScale, 92

WFS.Band.Max, 92, 96

WFS.Band.Min, 92, 96

WFS.Energy.Max, 92, 96, 97

WFS.Energy.Min, 92, 96

WFS.Write.For.Bands, 91

Write

Denchar, 112

DM, 66

DM.end.of.cycle, 66

DM.History.NetCDF, 67

DM.NetCDF, 67

DMHS.History.NetCDF, 67, 73

DMHS.NetCDF, 67, 73

Graphviz, 30

H, 66, 67

H.end.of.cycle, 67

TSHS.History, 67

Write.OrbitalIndex, 121

WriteBands, 91

WriteCoorCerius, 46

WriteCoorInitial, 120

WriteCoorStep, 22, 46, 120

WriteCoorXmol, 45

WriteEigenvalues, 22, 78, 93

WriteForces, 22, 121

WriteHirshfeldPop, 95

WriteIonPlotFiles, 37

WriteKbands, 22, 91

WriteKpoints, 22, 49

WriteMDHistory, 45, 120, 121

WriteMDXmol, 46, 121

WriteMullikenPop, 22, 95

WriteOrbMom, 53

WriteVoronoiPop, 95

WriteWaveFunctions, 22, 92

Authors, 49

Functional, 49

Hybrid, 50

Use.BSC.CellXC, 51

XML

Write, 161

178

UnitsAngle, 44

UnitsLength, 44

ZM.ForceTolAngle, 117

ZM.ForceTolLength, 117

ZM.MaxDisplAngle, 117

ZM.MaxDisplLength, 117

Zmatrix, 39, 41, 116, 119

179