Installation

This chapter prepares the tools used throughout the tutorial — SIESTA (including TranSIESTA and TBtrans), sisl, VASP, and pseudopotentials. The SIESTA family and sisl are free and open source; only VASP requires a commercial license. Even without VASP, you can complete the entire transport part of the tutorial (Chapter 05 onward).

Learning Objectives

• Prepare the basic build tools (compilers, MPI) for each operating system
• Install SIESTA 5.x either as a conda-forge package or from source (CMake)
• Understand that TranSIESTA and TBtrans are included in the SIESTA distribution
• Install the post-processing library sisl into a Python environment
• Download PBE scalar-relativistic .psml pseudopotentials from PseudoDojo
• Verify the installation with version checks and import tests

Component Overview

Tool	Role	License
SIESTA 5.x	LCAO DFT — SCF, bands, DOS, Hamiltonian generation	GPL (free)
TranSIESTA	NEGF self-consistent calculation — integrated into the siesta executable	GPL (free)
TBtrans	Post-processing transport — $T(E)$, DOS/PDOS	GPL (free)
sisl	Python post-processing — geometry conversion, band/transmission analysis	MPL-2.0 (free)
VASP	Plane-wave DFT — structural optimization, reference electronic structure	Commercial

TranSIESTA is not a separate executable

Since SIESTA 4.1, TranSIESTA is no longer a standalone binary; it is integrated into the siesta executable. Setting SolutionMethod transiesta in the input file switches it into NEGF mode (covered in Chapter 06). TBtrans is a separate executable named tbtrans, shipped together with the SIESTA source/package distribution.

1. Prerequisites — By Operating System

Building SIESTA from source or running it in MPI parallel requires compilers and build tools. Even if you plan to use only the conda-forge package, the common item below (conda) is still needed.

macOS

First install the Xcode Command Line Tools (which include the default compilers and git) and Homebrew.

xcode-select --install

Install Homebrew following the instructions at brew.sh, then get the tools needed for building.

brew install gcc cmake open-mpi

The gcc package includes the Fortran compiler gfortran.

Linux (Ubuntu)

sudo apt update
sudo apt install build-essential gfortran cmake openmpi-bin libopenmpi-dev

build-essential is a bundle of basic build tools including the C compiler and make. On other distributions, install the corresponding packages via their package manager (dnf, zypper, etc.).

Windows — WSL2 Recommended

SIESTA and TBtrans are developed and distributed assuming a Unix-like environment, so on Windows we recommend using WSL2 (Windows Subsystem for Linux). It can be installed with a single line in an administrator PowerShell.

wsl --install

After rebooting, once the Ubuntu environment opens, simply follow the Ubuntu procedure above. Native Windows builds have only limited official support.

Common — conda (miniforge recommended)

We use conda for the Python stack and for installing the SIESTA binaries. miniforge is a minimal conda distribution with the conda-forge channel set as default; since all packages used in this tutorial are on conda-forge, miniforge is recommended. Download and run the installer script from the conda-forge/miniforge releases page.

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

After installation, open a new terminal and the conda command will be available.

2. Setting Up the Python Environment

Create a dedicated conda environment to avoid version conflicts.

conda create -n transport python=3.11
conda activate transport

The reasons for a dedicated environment are reproducibility and isolation. Different tools require different ranges of python/numpy versions, and mixing packages into the system python or another project's environment means an upgrade on one side can break imports on the other. A dedicated environment pins this tutorial's stack (siesta, sisl, matplotlib) in one place, and recovery is simple — if something goes wrong, delete the environment and recreate it.

All subsequent installation and execution happens inside this environment. Every time you open a new terminal, run conda activate transport first.

3. Installing SIESTA

Method A — conda-forge Package (Fastest Start)

conda install -c conda-forge siesta

The siesta and tbtrans executables are installed together. conda-forge also provides MPI-parallel build variants, so if you need parallel execution, choose an MPI variant (openmpi or mpich) from the build list shown during installation. For running this tutorial's 1D chain examples on a laptop, the serial build is sufficient.

Check whether the installed build includes MPI via the build string.

conda list siesta

If the build string contains openmpi or mpich, it is a parallel build; nompi means a serial build. Following the usual conda-forge convention, you can also install a specific variant by specifying the build string.

conda install -c conda-forge "siesta=*=*openmpi*"

The trade-offs between the two methods are as follows.

Item	conda-forge package	Source build
Installation time	A few minutes	Tens of minutes (including preparing dependencies)
Performance	Generic binary — no optimization for specific CPUs or math libraries	Can choose compilers, MKL, etc. tailored to the system
Best suited for	Laptop learning, this tutorial's small examples	HPC, large-scale production calculations

Method B — Source Build (CMake)

Use this for HPC environments or when an optimized build is needed. Requirements:

• Fortran compiler (e.g., gfortran)
• CMake (3.20 or later recommended)
• BLAS/LAPACK
• For parallel builds: MPI library + ScaLAPACK

Download the latest 5.x tarball from the releases page of the SIESTA GitLab repository (gitlab.com/siesta-project/siesta). Extract it, then configure, build, and install with CMake.

tar xf siesta-5.x.y.tar.gz
cd siesta-5.x.y

FC=gfortran CC=gcc cmake -S . -B _build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt/siesta \
  -DSIESTA_WITH_MPI=ON
cmake --build _build -j 8
cmake --install _build

• The FC/CC environment variables specify the compilers to use (shown here for the gfortran + gcc combination). With MPI enabled, CMake automatically finds the system MPI installation (OpenMPI, etc.).
• -j 8 means compile in parallel with 8 cores. Adjust to the number of available cores.
• BLAS/LAPACK are auto-detected if they are in standard paths. For options to specify a particular math library such as MKL, and for the full option list, follow the official SIESTA build documentation (docs.siesta-project.org) — it is safest not to guess option names here.
• cmake --install copies the executables into the bin/ directory under CMAKE_INSTALL_PREFIX. Add the following to your shell startup file (~/.bashrc or ~/.zshrc) to set the path.

export PATH=$HOME/opt/siesta/bin:$PATH

An MPI-enabled build requires ScaLAPACK, and depending on the system you may need to point CMake to the library path — again, follow the official build documentation.

Once the build finishes, verify with ls $HOME/opt/siesta/bin that both siesta and tbtrans were installed. The CMake build of SIESTA 5.x includes TBtrans as a default target and builds it alongside. In the older 4.x make-based builds, TBtrans had to be built separately under the Util directory, so if you are inheriting a 4.x environment, always confirm that the tbtrans executable actually exists.

On HPC — Using System Modules Is the Norm

On shared HPC clusters, it is common to use a SIESTA build that administrators have already optimized and installed rather than building it yourself. Most HPC systems manage software with environment modules (or Lmod), and module load brings a specific build into the current shell environment.

module avail siesta   # list the siesta builds installed at the site
module load siesta    # module names/version labels vary by site

Module names differ from site to site (version/compiler suffixes are common), and some sites require loading dependent modules such as compilers and MPI as well. Follow each center's user documentation.

4. sisl and the Python Stack

sisl is the core post-processing tool of this tutorial. Reading fdf/band files, converting structures between VASP and SIESTA, and extracting transmission from TBtrans results (*.TBT.nc) are all handled with sisl. Install it with the conda environment activated.

pip install "sisl[analysis]"
pip install matplotlib

The [analysis] extra installs additional analysis dependencies such as netCDF4 — reading the TBtrans result file *.TBT.nc requires netCDF4, so this tutorial recommends installing with the extra. If you chose the minimal install (pip install sisl), run pip install netCDF4 separately. numpy and scipy are installed automatically as sisl dependencies. For details on installation options, consult the official sisl documentation (zerothi.github.io/sisl).

After installing, check the version.

python -c "import sisl; print(sisl.__version__)"

5. VASP

VASP is a commercial code that requires a license from VASP Software GmbH. Licenses are issued per research group rather than per individual, so if your group (principal investigator) holds a license, you register as a member of that group. Only license holders can download the source code from the VASP portal, and third-party redistribution is prohibited.

In practice, most people use the VASP module already installed at an HPC center rather than compiling it themselves. Typically the center verifies license ownership before granting access, and thereafter it is loaded the same way as the SIESTA module.

module avail vasp

If you need to build it yourself, follow your institution's or lab's procedures; usually you will end up using a vasp_std-family executable built by the system administrator.

POTCAR is licensed material

VASP's PAW pseudopotentials (POTCAR) are assets bound to the license, so this site does not distribute them. You must use the potpaw database provided by a license-holding institution, and uploading POTCAR files to public repositories is a license violation. The example repository for this tutorial likewise contains no POTCAR files and only explains how to assemble them (Chapter 03).

6. Pseudopotentials — PseudoDojo

SIESTA calculations require norm-conserving pseudopotentials. This tutorial uses the validated .psml files from PseudoDojo.

1. Go to the PseudoDojo website (pseudo-dojo.org).
2. Select the options: XC = PBE, relativistic treatment = scalar-relativistic (SR), accuracy = standard, format = psml.
3. Click C (carbon) and N (nitrogen) in the periodic table to download them. Carbon is used from Chapter 01 onward, and nitrogen in the device chapter (C19N chain).
4. Extracting the archive yields C.psml and N.psml. Keep them in an easy-to-manage location (e.g., a pseudos folder under your home directory) and copy them into each calculation directory as needed.

Matching the pseudopotential and the XC functional

The .psml file records the XC functional used to generate it. It must match the XC.Functional/XC.Authors settings in the fdf input (this tutorial uses PBE throughout); SIESTA issues a warning on mismatch.

7. Visualization and Plotting Tools

Prepare tools for inspecting results visually in advance. They are not mandatory, but they are the fastest way to catch structural errors before running a calculation.

Purpose	Tool	Notes
Structure inspection (3D)	VESTA	Free. Opens .xsf, POSCAR/CONTCAR, and cube files directly — for checking structures before submitting calculations
Structure inspection (lightweight)	XCrySDen	Linux-centric. The original .xsf viewer
Wavefunction/eigenchannel cubes	VESTA	Isosurface rendering — used in Chapter 10
Graphs (T(E), bands, I–V)	Python + matplotlib	Used by all plotting examples in this tutorial. Install in the same environment as sisl

conda activate transport
pip install matplotlib

8. Getting the Example Input Files

All input files for this tutorial (the code/ directory) live in the same repository as the site.

git clone https://github.com/nangman98/transport-tutorial.git
cd transport-tutorial/code
ls
# ch01-siesta-scf  ch02-bands  ch03-vasp  ch05-electrode  ch06-device
# ch07-tbtrans  ch09-bias  ch10-eigenchannel  miniproject

Each directory's README.md describes what its input calculates. As you follow the chapters, copy the corresponding directory and use it as your workspace.

Computational cost

All examples are 1D carbon chains (20 atoms or fewer), so they run within minutes even on a laptop. However, Chapter 09 (finite-bias chain) and the length series of the mini-project involve many repeated calculations, so it is more efficient to proceed together with the HPC usage in Chapter 12 if possible.

Installation Verification Checklist

Check the items below in order. If every command produces the expected output, you are ready.

Item	Command	Expected output
SIESTA	siesta --version	Version string (e.g., Siesta version : 5.2.0)
TBtrans	tbtrans --version	Version string — same version as SIESTA
sisl	python -c "import sisl; print(sisl.__version__)"	One line with the version number, no import errors
MPI operation	mpirun -np 2 hostname	Hostname printed on 2 lines (confirms 2 processes launched)
pseudopotentials	ls ~/pseudos	C.psml, N.psml

In a copy-and-run form:

siesta --version
tbtrans --version
python -c "import sisl; print(sisl.__version__)"
mpirun -np 2 hostname

The version numbers may differ depending on when you install. If you have an MPI build, also check SIESTA's own parallel execution once.

mpirun -np 2 siesta --version

Common Installation Problems

Symptom	Cause	Fix
CMake configure step errors that it cannot find a Fortran compiler	gfortran not installed	Install with brew install gcc on macOS or sudo apt install gfortran on Ubuntu, then delete the _build directory and reconfigure
Running mpirun -np 4 siesta ... prints the same SCF output 4 times	Serial build run under mpirun — 4 independent processes each perform the full calculation	Check the build string with conda list siesta and reinstall an MPI variant, or rebuild with SIESTA_WITH_MPI=ON
mpirun aborts with MPI library errors	Mismatch between the MPI used for the build and the mpirun implementation/version being run (e.g., mixing conda's openmpi with a system mpich)	Verify with which mpirun that the mpirun inside the conda environment is picked up, and unify to the same stack
siesta: command not found or ModuleNotFoundError: No module named 'sisl'	conda environment not activated	Retry after conda activate transport — activation is needed in every new terminal
SIESTA exits right after startup with an error that the pseudopotential file was not found	.psml file missing from the working directory, or label in ChemicalSpeciesLabel does not match the file name	Copy C.psml etc. into the same directory as input.fdf and check labels against file names one-to-one

Exercises

1. Download C.psml and N.psml from PseudoDojo and create a pseudopotential storage directory. Open the downloaded .psml files in a text editor and verify that the XC functional information is recorded as PBE.
2. In python, after import sisl, create a built-in geometry with sisl.geom.graphene() and print the number of atoms and the lattice vectors. This is the quickest way to confirm sisl is working.
3. (If you have an MPI build) Verify that both mpirun -np 2 siesta --version and mpirun -np 4 siesta --version work correctly. Parallel execution is used starting with the SCF calculation in Chapter 01.

Once you are set up, move on to Chapter 01 — First SIESTA Calculation.