What Is SIESTA

SIESTA is the primary DFT code of this tutorial. The name stands for Spanish Initiative for Electronic Simulations with Thousands of Atoms — the design goal of "electronic-structure simulations at the scale of thousands of atoms" is written right into the name. This chapter surveys what kind of code SIESTA is, how a calculation flows, and what the inputs and outputs look like. Hands-on practice starts in Chapter 01.

What SIESTA Is

• A DFT code with a numerical atomic-orbital (LCAO) basis. Instead of plane waves, it uses localized orbitals (numerical atomic orbitals) attached to each atom. The orbitals are cut off to be exactly zero beyond an atomic radius, making the Hamiltonian and overlap matrices sparse.
• This sparsity enabled a design aimed at linear scaling, i.e., $O(N)$ calculations — the "Thousands of Atoms" in the name points to exactly this. Even in the standard diagonalization mode, the basis size is much smaller than a plane-wave calculation of the same accuracy.
• TranSIESTA and TBtrans are included in the same distribution. TranSIESTA handles NEGF (nonequilibrium Green's function) open-boundary calculations, and TBtrans handles the post-processing that computes transmission and current from those results. A localized-orbital basis allows the system to be spatially partitioned into electrodes/scattering region, so transport calculations effectively require an LCAO code — the fundamental reason this tutorial uses SIESTA.
• It is open source and free. In the past an academic license registration was required, but it is now GPL open source and anyone can download and build it. Installation was covered in the installation chapter.

Positioning Relative to Plane-Wave Codes

Item	LCAO (SIESTA)	Plane-wave (VASP, Quantum ESPRESSO)
Basis functions	Localized orbitals attached to atoms	Plane waves spread over all space
Basis size	A few to a few tens per atom — small	Tens to hundreds of thousands depending on cutoff
Basis convergence control	System-dependent — adjust the SZ/DZ/DZP levels and orbital radii	Systematic with a single cutoff energy
Large systems	Favorable (sparse matrices, $O(N)$-oriented)	Cost grows quickly with atom count
Transport (NEGF)	Possible — spatial partitioning is natural	Hard without a localization transform (Wannier, etc.)
Vacuum regions	No cost where there are no orbitals	Vacuum must also be filled with plane waves

The advantages are summarized by the left column of the table — favorable for large systems, and NEGF transport is possible because the orbitals are localized. The disadvantages also stem from the same locality.

• Basis convergence is system-dependent. Plane waves converge monotonically as the cutoff increases, but LCAO has several tuning parameters — the basis level (SZ/DZ/DZP) and the orbital radii — whose optimal values differ from system to system.
• BSSE (basis set superposition error) exists. When two fragments approach, each "borrows" the other's basis functions and the binding energy is overestimated — an error intrinsic to localized bases. Care is needed when dealing with adsorption and binding energies.

This tutorial exploits this complementarity directly — structures are finalized with plane waves (VASP), and transport is done with LCAO (SIESTA/TranSIESTA). Cross-validation between the two codes is practiced in Chapter 03.

How a Calculation Flows

A single SIESTA calculation proceeds in the following order.

1. Read input — the fdf input file and the per-species pseudopotential files (C.psml, etc.) are read from the working directory.
2. Generate the basis — the numerical atomic-orbital basis is generated from the pseudopotentials (saved as .ion files).
3. SCF loop — iterates until the density matrix becomes self-consistent.
4. Output — energies, forces, and requested properties (bands, DOS, etc.) are written to stdout and to files.

Execution follows the stdin/stdout convention — feed the input through standard input and capture standard output into a file.

siesta < input.fdf > siesta.out
mpirun -np 4 siesta < input.fdf > siesta.out    # MPI parallel

Recent versions also accept the input as an argument, as in siesta input.fdf, but this tutorial standardizes on the stdin/stdout convention above. The meaning of the redirections was explained in Linux and Terminal Basics.

Pseudopotential files — the other half of the calculation

If the fdf defines "what to compute and how," the pseudopotential defines "how each element is represented." SIESTA reads the .psml or .psf formats, and this tutorial uses .psml files (PBE, scalar-relativistic) from the PseudoDojo database. Always check two things — ① does the file name match the label in %block ChemicalSpeciesLabel (C → C.psml)? ② does the XC functional the pseudopotential was generated with match the input's XC.Functional/XC.Authors? A mismatch in the latter still runs, but the consistency of the results is broken.

Anatomy of the Input — fdf

The input is a single fdf (flexible data format) text file. Syntax summary:

• Keyword–value pairs, one per line: MeshCutoff 300. Ry. Keywords are case-insensitive and ignore ., -, _.
• Physical quantities carry units: 1.29 Ang, 0.01 eV/Ang.
• Multi-line data is wrapped in %block name ... %endblock name — lattice vectors, atomic coordinates, k-grid.
• %include filename lets you split the input — the convention of separating the structure into struct.fdf and including it from the main input is used in the transport chapters.
• Everything after # is a comment.

The required inputs organize into five groups.

Group	Representative keywords	Role
System definition	SystemLabel, NumberOfAtoms, %block ChemicalSpeciesLabel	Output file prefix, linking species to pseudopotentials
Structure	LatticeConstant, %block LatticeVectors, %block AtomicCoordinatesAndAtomicSpecies	Lattice and atomic coordinates
Basis & grid	PAO.BasisSize, MeshCutoff	LCAO basis size, real-space grid fineness
Exchange-correlation	XC.Functional, XC.Authors	XC functional (e.g., GGA/PBE)
k-points & SCF	%block kgrid_Monkhorst_Pack, SCF.DM.Tolerance, MaxSCFIterations	Brillouin zone sampling, SCF convergence criteria

The meaning of each keyword and the choice of actual values are explained line by line in Chapter 01.

Output File Dictionary

SIESTA creates files prefixed with the value of SystemLabel (below assumes SystemLabel siesta). At first the flood of files is disorienting, but only a handful actually matter.

File	Contents	When to use
siesta.out	stdout redirect — full SCF history, energies, forces, warnings	First thing to check for every calculation
siesta.DM	Density matrix	Restart — reused as initial density if DM.UseSaveDM T
siesta.XV	Final atomic coordinates + velocities	Restart — continuing a relaxation, inheriting a structure
siesta.STRUCT_OUT	Final structure (lattice + fractional coordinates)	Structure post-processing, conversion to other codes
siesta.FA	Per-atom forces	Relaxation convergence check
siesta.bands	Eigenvalues along the band path	Band plots (Chapter 02)
siesta.EIG	Eigenvalues at the sampled k-points — first line is the Fermi energy	DOS calculation, Fermi energy check
siesta.KP	The k-points actually used, with weights	Checking k-point sampling
siesta.DOS, siesta.PDOS	Density of states (PDOS in xml format)	DOS/PDOS plots
siesta.HSX	Hamiltonian and overlap matrices (sparse storage)	Input to post-processing tools such as sisl
siesta.TSHS	Hamiltonian and overlap for TranSIESTA	Electrode/device transport (Chapter 05 onward)
C.ion, C.ion.xml	Generated basis orbitals	Basis inspection, orbital reconstruction in post-processing
MESSAGES	Summary of warnings/errors	Diagnosing abnormal termination
INPUT_TMP.*, fdf-*.log	Input echo temp files	Not needed except for debugging

The minimal restart set — .DM and .XV

The minimal set needed to continue a calculation or to start a follow-up calculation of the same system is siesta.DM (converged density) and siesta.XV (final structure). With just these two, the SCF can restart near the converged state, drastically reducing the iteration count. When retrieving results from a server, whatever else you skip, always grab these two along with siesta.out and the input fdf.

How to Read the stdout

siesta.out is organized as header (version, input echo) → basis generation log → SCF cycles → final energies and forces. The excerpts below are all examples to show the format; numbers and column layouts vary slightly by version.

SCF cycle table — one line per iteration.

        iscf     Eharris(eV)        E_KS(eV)     FreeEng(eV)     dDmax    Ef(eV)  dHmax(eV)
   scf:    1     -621.383914     -598.130561     -598.152804  1.240718 -8.309820  4.879274
   scf:    2     -600.560423     -611.238379     -611.260622  0.421559 -5.410181  1.680392
   ...

The key column is dDmax (maximum change of the density matrix between iterations). Convergence is reached when this value falls below SCF.DM.Tolerance. Eharris and E_KS coming into agreement is also an intuitive gauge of convergence.

Convergence verdict line — this one line must be present for the results to be usable.

SCF cycle converged after 34 iterations

A calculation stopped by hitting MaxSCFIterations has not converged. A warning is left on convergence failure, so always check with grep -i converge siesta.out.

Final energy block — the summary near the end of the file.

siesta: Final energy (eV):
...
siesta:         Total =    -616.283719
siesta:         Fermi =      -4.591428

The total energy is referenced to the pseudopotential, so its absolute value is meaningless by itself; only differences between calculations under the same conditions carry physical meaning. The Fermi energy is used from here on as the energy reference ($E - E_F$) for bands and transmission.

Force block — per-atom forces printed when WriteForces T.

siesta: Atomic forces (eV/Ang):
siesta:      1   -0.000000    0.000000    0.000214
siesta:      2    0.000000   -0.000000   -0.000198
...

In relaxation calculations, whether the maximum force has fallen below MD.MaxForceTol is the termination criterion.

That is the big picture of SIESTA. In Chapter 01 you run your first SCF calculation on a carbon chain yourself, and the representative code of the plane-wave camp is surveyed next in What Is VASP.