~nickpapior/siesta/trunk-buds-format0.92

% Manual for the TBtrans program

%

% To generate the printed version:

%

% pdflatex tbtrans

% pdflatex tbtrans

% splitidx tbtrans.idx (optional if you want a split index)

% makeindex tbtrans    (optional if you have a current siesta.ind)

% pdflatex tbtrans

%

%

% Include settings appropriate for tbtrans

\input{tex/init.tex}

% Set the date

\date{November 29, 2016}

\begin{document}

% TITLE PAGE --------------------------------------------------------------

\begin{titlepage}

\begin{center}

\vspace{1cm}

\ifdeveloper

 {\Huge \textsc{D e v e l o p e r' s \, \, G u i d e}}

\else

 {\Huge \textsc{U s e r' s \, \, G u i d e}}

\fi

\vspace{1cm}

\hrulefill

\vspace{1cm}

{\Huge \textbf{T B t r a n s \, \, 4.1-b3}}

\vspace{1cm}

\hrulefill

\vspace{0.5cm}

{\Large \printdate}

\vspace{1.5cm}

{\Large \url{https://launchpad.net/siesta}}

\end{center}

\end{titlepage}

% END TITLE PAGE --------------------------------------------------------------

\newpage

\section*{Contributors to \tbtrans}

\addcontentsline{toc}{section}{Contributors to \siesta}

\tbtrans\ is Copyright \copyright\ 2016-2016 by Nick R. Papior. The

original \tbtrans\ code was implemented by Mads Brandbyge, Jose

L. Mozos, Jeremy Taylor, Pablo Ordejon and Kurt Stokbro. The current

\tbtrans\ is implemented by the following contributors:

Nick R. Papior.

\tableofcontents

\newpage

\section{Introduction}

\textit{This Reference Manual contains descriptions of all the input,

    output and execution features of \tbtrans, but is not a tutorial

    introduction to the program.}

\tbtrans\ (Tight-Binding transport) is a generic computer program

which calculates transport and other physical quantities using the

Green function formalism. 

%

It is a stand-alone program which allows \emph{extreme} scale

tight-binding calculations. 

\begin{itemize}

  \item%

  It uses the basic non-equilibrium Green function formalism and

  allows extensive customizability and analysis forms.

  \item%

  \tbtrans\ may be given any type of local-orbital Hamiltonian and

  calculate transport properties of arbitrary geometries and/or number

  of electrodes. 

  \item%

  The \phtrans\ variant may be compiled to obtain thermal (phonon)

  transport using the same Green function formalism and \emph{all} the

  same functionalities as those presented in this manual.

\end{itemize}

A list of the currently implemented features are:

\begin{itemize}

  \item Density of states (orbital resolved)

  \begin{itemize}

    \item Green function DOS

    \item Scattering DOS

  \end{itemize}

  \item Hamiltonian interpolation at different voltages

  \item Selective wide-band limit of the electrode(s)

  \item Transmission eigenvalues

  \item Bulk electrode density of state and transmission (directly

  from the electrode Hamiltonian)

  \item Projected transmission of eigenstates

  \item Orbital resolved ``bond-currents'' which may subsequently be

  analyzed to yield actual bond-currents.

\end{itemize}

\vspace{0.5cm}

{\large \textbf{References:} }

\begin{itemize}

  \item%

  Description of the \tbtrans\ and \tsiesta\ code in the $N$ terminal

  generic implementation \cite{Papior2017}.

  \item%

  \sisl\ is a data extraction utility for \tbtrans\ which enables easy

  access to the data stored in the output NetCDF-4 file \cite{sisl}.

\end{itemize}

\section{Compilation}

\tbtrans\ may be compiled in the \shell{Util/TS/TBtrans} directory.

To compile \tbtrans\ simply go to the directory and type:

\begin{shellexample}

  $ make

\end{shellexample}

%$

This will default to use the \file{arch.make} file in the \shell{Obj}

directory. To use a different directory you may do:

\begin{shellexample}

  $ make OBJDIR=AnotherObjDir

\end{shellexample}

%$

\tbtrans\ is tightly intertwined with the \siesta\ source to reduce

code duplication.

Please see the \siesta\ manual for installing NetCDF easily.

\subsection{The \texttt{arch.make}\ file}

\label{sec:arch-make}

The compilation is done using a \shell{Makefile} that is provided with

the code\index{Makefile}. This \shell{Makefile} will generate the

executable for any of several architectures, with a minimum of tuning

required from the user and encapsulated in a separate file called

\file{arch.make}.

\tbtrans\ relies on the following libraries

\begin{description}

  \item[BLAS] %

  it is recommended to use a high-performance library

  (\href{https://github.com/xianyi/OpenBLAS}{OpenBLAS} or the MKL

  library from Intel)

  \begin{itemize}

    \item 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.

  \end{itemize}

  To add BLAS to the \file{arch.make} file you need to add the

  required linker flags to the \shell{LIBS} variable in the

  \file{arch.make} file.

  Example variables

\begin{shellexample}

  # OpenBLAS:

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

  # or for MKL

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

\end{shellexample}

  \item[LAPACK]%

  it is recommended to use a high-performance library

  (\href{https://github.com/xianyi/OpenBLAS}{OpenBLAS}\footnote{OpenBLAS

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

  or the MKL library from Intel)

  Example variables

\begin{shellexample}

  # OpenBLAS (OpenBLAS will default to build in LAPACK 3.6)

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

  # or for MKL

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

\end{shellexample}

\end{description}

The above are the minimally required libraries. 

Highly encouraged libraries

\begin{description}

  \item[\href{https://www.unidata.ucar.edu/software/netcdf}{NetCDF}] %

  Note that it should a NetCDF4 compliant compiled

  library\footnote{Remark that a NetCDF-3 compliant library is not

      sufficient for \tbtrans.}. This library is required for a

  multitude of advanced analysis methods such as orbital resolved DOS,

  bond-currents, $\delta \mathbf H$, eigenstate projections, etc.

  To use this library add these variables to your \file{arch.make}

  file

\begin{shellexample}

  COMP_LIBS += libncdf.a

  FPPFLAGS += -DCDF -DNCDF -DNCDF_4

  LIBS += -lnetcdff -lnetcdf -lhdf5_fortran -lhdf5 -lz

\end{shellexample}

  If you have compiled NetCDF4 with parallel IO you may benefit from

  parallel IO by adding this compilation flag:

\begin{shellexample}

  FPPFLAGS += -DNCDF_PARALLEL

\end{shellexample}

  To easily install \program{NetCDF} please see the installation file:

  \shell{Docs/install\_netcdf4.bash}.

\end{description}

Importantly, \tbtrans\ is compatible with hybrid parallelism using MPI

and OpenMP or either of them alone. 

\paragraph{MPI}

To compile using MPI add this to your \file{arch.make} file

\begin{shellexample}

 FPPFLAGS += -DMPI

\end{shellexample}

\paragraph{OpenMP}

To compile using OpenMP add this to your \file{arch.make} file

\begin{shellexample}

 FFLAGS += -fopenmp

 LIBS += -fopenmp

\end{shellexample}

change the corresponding flag according to your compiler.

\paragraph{Running Hybrid parallel \tbtrans}

%

Running \tbtrans\ using hybrid parallelism is difficult due to the

complexity of controlling the threads and processors.

To achieve good performance one \emph{must} ensure that the threads

and processors are not oversubscribe and are not overlapping.

For instance if using OpenMPI $\ge1.8.4$ one may run \tbtrans\

using this command:

\begin{shellexample}

 mpirun -np $((PBS_NP/OMP_NUM_THREADS)) \

   -x OMP_NUM_THREADS \

   -x OMP_PROC_BIND=true \

   --map-by ppr:1:socket:pe=$OMP_NUM_THREADS

\end{shellexample}

where \shell{PBS\_NP} is the total number of processors,

\shell{OMP\_NUM\_THREADS} is the number of threads per processor. The

above command assumes using 1 MPI processor per socket with each

socket having \shell{OMP\_NUM\_THREADS} cores.

\subsubsection{BLAS GEMM3M kernel}

Several modern BLAS implementations allow the use of GEMM3M kernels

for complex linear algebra. They should provide a performance

enhancement for large matrices. To use these routines add this to your

\file{arch.make} file:

\begin{shellexample}

  FPPFLAGS += -DUSE_GEMM3M

\end{shellexample}

Note that OpenMP threaded BLAS libraries are known to fail with the

GEMM3M kernels. 

\subsubsection{Intel MKL libraries}

The MKL libraries are very efficient, but may be difficult to obtain a

correct linking. Here is a short tutorial for linking the MKL BLAS and

LAPACK libraries correctly.

In the following assume that \shell{MKL\_ROOT} points to the root of

the MKL installation directory, for instance one may install MKL into

\shell{/opt/intel/mkl}:

\begin{shellexample}

  MKL_ROOT = /opt/intel/mkl

\end{shellexample}

where \shell{MKL\_ROOT/lib/intel64} contains the libraries.

The linking depends on the used compiler:

\begin{description}

  \item[Intel compiler] %

  \index{compile!Intel}

  The MKL libraries are parallelized using threads and you may also

  enable threads in \tbtrans:

  \begin{description}

    \item[No threading] \mbox{}%

\begin{shellexample}

  LIBS += -L$(MKL_ROOT)/lib/intel64 -lmkl_lapack95_lp64

  -lmkl_blas95_lp64 -lmkl_intel_lp64 -lmkl_core -lmkl_sequential

\end{shellexample}

%$

    \item[OpenMP threading] \mbox{}%

    \index{OpenMP!Intel}

\begin{shellexample}

  LIBS += -openmp -L$(MKL_ROOT)/lib/intel64 -lmkl_lapack95_lp64

  -lmkl_blas95_lp64 -lmkl_intel_lp64 -lmkl_core -lmkl_intel_thread

\end{shellexample}

  %$  

  \end{description}

  \item[GNU compiler] %

  \index{compile!GNU}

  The MKL libraries are parallelized using threads and you may also

  enable threads in \tbtrans:

  \begin{description}

    \item[No threading] \mbox{}%

\begin{shellexample}

  LIBS += -L$(MKL_ROOT)/lib/intel64 -lmkl_lapack95_lp64

  -lmkl_blas95_lp64 -lmkl_gf_lp64 -lmkl_core -lmkl_sequential

\end{shellexample}

%$

    \item[OpenMP threading] \mbox{}%

    \index{OpenMP!GNU}

\begin{shellexample}

  LIBS += -fopenmp -L$(MKL_ROOT)/lib/intel64 -lmkl_lapack95_lp64

  -lmkl_blas95_lp64 -lmkl_gf_lp64 -lmkl_core -lmkl_gnu_thread

\end{shellexample}

  %$  

  \end{description}

\end{description}

\section{Execution of the Program}

\tbtrans\ should be called with an input file which defines what

\emph{it should do}. This may either be piped or simply added on the

input line. The latter method is preferred as one may use flags for

the executable.

\begin{shellexample}

  $ tbtrans < RUN.fdf

  $ tbtrans RUN.fdf

\end{shellexample}

Note that if \tbtrans\ is compiled with MPI support one may call it

like 

\begin{shellexample}

  $ mpirun -np 4 tbtrans RUN.fdf

\end{shellexample}

%$

for $4$ MPI-processors.

\tbtrans\ has these optional flags:

\begin{description}

  \item[\fdf*{-h}] print a help instruction

  \item[\fdf*{-L}] override \fdf{SystemLabel} flag

  \item[\fdf*{-V}] override \fdf{TBT.Voltage} flag. To denote the

  unit do as this example: \fdf*{-V 0.2:eV} which sets the voltage to $0.2\,\mathrm{eV}$.

  \item[\fdf*{-D}] override \fdf{TBT.Directory} flag, all output

  of \tbtrans\ will be put in the corresponding folder (it will be

  created if non-existing)

  \item[\fdf*{-HS}] specify the \fdf{TBT.HS} variable, quickly

  override the used Hamiltonian

  \item[\fdf*{-fdf}] specify any given fdf flag on the command line,

  example \fdf*{-fdf TBT.Voltage:0.2:eV}

\end{description}

Note that for all flags one may use ``:'' as a replacement for `` '',

although one may use quotation marks when having a space in the argument.

\section{fdf-flags}

Although \tbtrans\ is a fully independent Green function transport

code, it is hard-wired with the \tsiesta\ \fdflib\ flags and

options. If you are familiar with \tsiesta\ and its input flags, then

the use of \tbtrans\ should be easy.

All fdf-flags for \tbtrans\ are defaulted to their equivalent

\tsiesta\ flag. Thus if you are using \tsiesta\ as a back-end you

should generally not change any flags. For instance \fdf{TBT.Voltage}

defaults to \fdf*{TS.Voltage} if not supplied.

\begin{fdfentry}{SystemLabel}[string]<siesta>

  The label defining this calculation. All relevant output will be

  prefixed with the \fdf*{SystemLabel}.

  One may start several \tbtrans\ calculations in the same directory

  if they have different labels.

\end{fdfentry}

\begin{fdfentry}{TBT.Voltage}[energy]<$0\,\mathrm{eV}$>

  Define the applied bias in the scattering region. 

\end{fdfentry}

\begin{fdfentry}{TBT.Directory}[directory]<./>

  Define the output directory of files from \tbtrans. This allow

  execution of several \tbtrans\ instances in the same folder and

  writing their result to different, say, sub-folders. It is

  particularly useful for interpolation of Hamiltonian's and for

  testing purposes.

\end{fdfentry}

\begin{fdfentry}{TBT.Verbosity}[integer]<5>

  Specify how much information \tbtrans\ will print-out (range 0-10).

  For smaller numbers, less information will be printed, and for

  larger values, more information is printed.

\end{fdfentry}

\begin{fdfentry}{TBT.Progress}[real]<5.>

  \tbtrans\ prints out an estimated time of completion (ETA) for the

  calculation. By default this is printed out every 5\% of the

  total loops ($k$-point $\times$ energy loops). Setting this to 0

  will print out after every energy loop.

\end{fdfentry}

\subsection{Define electronic structure}

\begin{fdfentry}{TBT.HS}[file]<\fdf*{<SystemLabel>}.TSHS>

  Define the Hamiltonian file which contains information regarding the

  Hamiltonian and geometry.

\end{fdfentry}

\begin{fdfentry}{TBT.HS.Files}[block]

  A list of files which each contain the Hamiltonian for the same

  geometry at different bias'. 

  % 

  Each line has three entries, 1) the \fdf{TBT.HS} file, 2) the value

  of the bias applied, 3) the unit of the bias.

  \note if this is existing it will assume that you will perform an

  interpolation of the Hamiltonians to the corresponding bias

  (\fdf{TBT.Voltage}). 

\end{fdfentry}

\begin{fdfentry}{TBT.HS.Interp}[string]<spline|linear>

  \fdfdepend{TBT.HS.Files}

  Interpolate all files defined in \fdf{TBT.HS.Files} to the

  corresponding applied bias.

  Generally \fdf*{spline} produces the best interpolated values and

  its use is encouraged. The linear interpolation scheme is mainly

  used for comparison to the \fdf*{spline}. If they are very different

  from each other then one may be required to perform additional

  self-consistent calculations at the specific bias due to large

  changes in the electronic structure.

\end{fdfentry}

Say you have calculated the SCF solution of a certain system at 5

different applied bias':

\begin{fdfexample}

  %block TBT.HS.Files

    ../V0/siesta.TSHS     0.  eV

    ../V-0.5/siesta.TSHS -0.5 eV

    ../V0.5/siesta.TSHS   0.5 eV

    ../V-1.0/siesta.TSHS -1.0 eV

    ../V1.0/siesta.TSHS   1.0 eV

  %endblock

\end{fdfexample}

and you wish to calculate the interpolated transmissions and currents

at steps of $0.1\,\mathrm{eV}$, then you may use this simple loop

\begin{shellexample}

  for V in `seq -1.5 0.1 1.5` ; do

     tbtrans -V $V:eV -D V$V RUN.fdf

  done

\end{shellexample}

which at each execution of \tbtrans\ interpolates the Hamiltonian to

the corresponding applied bias and store all output files in the

\shell{V\$V} folder.

\subsubsection{Changing the electronic structure via

    \texorpdfstring{$\delta\mathbf H$}{dH}}

The electronic structure may be altered by changing the Hamiltonian

elements via a simple additive term

\begin{equation}

  \mathbf H \leftarrow \mathbf H + \delta\mathbf H,

\end{equation}

which allows easy changes to the electronic structure or adding

additional terms such as imaginary self-energies. One may also use it

to add magnetic fields etc.

To use this feature at $k$ points it is important to know that phases

in \tbtrans\ are defined using the lattice vectors (and \emph{not}

inter-atomic distances)

\begin{equation}

  \mathbf H_k = \mathbf H \cdot e^{-i k \cdot \mathbf R}.

\end{equation}

\begin{fdfentry}{TBT.dH}[file]

  Denote a file which contains the $\delta\mathbf H$ information. This

  file \emph{must} adhere to these file format notations and is

  required to be supplied in a NetCDF4 format

  \begin{shellexample}

netcdf file.dH {

dimensions:

	one = 1 ;

	n_s = 9 ;

	xyz = 3 ;

	no_u = 900 ;

	spin = 1 ;

variables:

	int nsc(xyz) ;

		nsc:info = "Number of supercells in each unit-cell direction" ;

group: LEVEL-1 {

  dimensions:

  	nnzs = 2670 ;

  variables:

  	int n_col(no_u) ;

  		n_col:info = "Number of non-zero elements per row" ;

  	int list_col(nnzs) ;

  		list_col:info = "Supercell column indices in the sparse format" ;

  	int isc_off(n_s, xyz) ;

  		isc_off:info = "Index of supercell coordinates" ;

  	double RedH(spin, nnzs) ;

  		RedH:info = "Real part of dH" ;

  		RedH:unit = "Ry" ;

  	double ImdH(spin, nnzs) ;

  		ImdH:info = "Imaginary part of dH" ;

  		ImdH:unit = "Ry" ;

  } // group LEVEL-1

group: LEVEL-2 {

  dimensions:

  	nkpt = UNLIMITED ;

  	nnzs = 2670 ;

  variables:

  	double kpt(nkpt, xyz) ;

  		kpt:info = "k-points for dH values" ;

  		kpt:unit = "b**-1" ;

  	... n_col list_col isc_off ...

  	double dH(nkpt, spin, nnzs) ;

  		dH:info = "dH" ;

  		dH:unit = "Ry" ;

  } // group LEVEL-2

group: LEVEL-3 {

  dimensions:

  	ne = UNLIMITED ;

  	nnzs = 2670 ;

  variables:

  	double E(ne) ;

  		E:info = "Energy points for dH values" ;

  		E:unit = "Ry" ;

  	... n_col list_col isc_off ...

  	double dH(ne, spin, nnzs) ;

  		dH:info = "dH" ;

  		dH:unit = "Ry" ;

  } // group LEVEL-3

group: LEVEL-4 {

  dimensions:

  	nkpt = UNLIMITED ;

  	ne = UNLIMITED ;

  	nnzs = 2670 ;

  variables:

  	double kpt(nkpt, xyz) ;

  		kpt:info = "k-points for dH values" ;

  		kpt:unit = "b**-1" ;

  	double E(ne) ;

  		E:info = "Energy points for dH values" ;

  		E:unit = "Ry" ;

  	... n_col list_col isc_off ...

  	double dH(nkpt, ne, spin, nnzs) ;

  		dH:info = "dH" ;

  		dH:unit = "Ry" ;

  } // group LEVEL-4

}

  \end{shellexample}

  This example file shows how the file should be formatted. Note that

  one may either define the Hamiltonian as \shell{dH} or as

  \shell{RedH} and \shell{ImdH}. The former is defining $\delta\mathbf

  H$ as a real quantity while the latter makes it an imaginary

  $\delta\mathbf H$.

  The levels are defined because they have precedence from each other,

  if the energy point and $k$ point is found in LEVEL-4 it will use

  this, if not, it will check for the energy point in LEVEL-3, and so

  on. 

\end{fdfentry}

The remaining options are only applicable if \fdf{TBT.dH} has been

set. 

\begin{fdflogicalT}{TBT.dH!Parallel}

  Whether the $\delta\mathbf H$ file should be read in parallel. If

  your architecture supports parallel IO it is beneficial to do so. 

  %

  \tbtrans\ performs a basic check whether parallel IO may be

  possible, if it cannot assert this it will be turned off.

\end{fdflogicalT}

\begin{fdfentry}{TBT.dH!Algorithm}[string]<sparse|block>

  Define the algorithm for inserting the matrix elements in the

  Hamiltonian.

  \begin{fdfoptions}

    \option[sparse]%

    \fdfindex{TBT.dH!Algorithm!sparse}%

    The inner loop is across the sparsity pattern of $\delta\mathbf

    H$, thus searching in the local matrix block sparsity pattern.  

    This should generally perform better when the matrix blocks to

    insert in are relatively small. 

    \option[block]%

    \fdfindex{TBT.dH!Algorithm!block}%

    The inner loop is across the local matrix block size, thus

    searching in the $\delta\mathbf H$ sparsity pattern.

    This should generally perform better when the $\delta\mathbf H$

    sparsity pattern is nearly the same size as the original

    Hamiltonian sparsity pattern.

  \end{fdfoptions}

\end{fdfentry}

\subsection{Determine calculated physical quantities}

\label{sec:physical}

\tbtrans\ can calculate a large variety of physical

quantities. By default it will only calculate the transmission between

the electrodes. Calculating as few quantities as possible will

increase throughput, while requesting many quantities will result in

much longer run-times.

You are heavily encouraged to compile \tbtrans\ with NetCDF4 support,

see Sec.~\ref{sec:arch-make}, as quantities will be orbital resolved. 

If \tbtrans\ has been compiled with NetCDF4 support, one may extract

the projected DOS from the \sysfile{TBT.nc} using \sisl\ (or manual

scripting). The calculated DOS can \emph{only} be extracted from the

atoms in the device region (atoms in block

\fdf{TBT.Atoms!Device}). Hence the \fdf{TBT.Atoms!Device} block is

\emph{extremely} important when conducting detailed DOS analysis. 

For instance if the input file has this:

\begin{fdfexample}

  %block TBT.Atoms.Device 

    atom [20 -- 40]

  %endblock

\end{fdfexample}

one may extract the PDOS on a subset of atoms using this \sisl\

command

\begin{shellexample}

  sdata siesta.TBT.nc --atom 20-30 --dos --ados Left --out dos_20-30.dat

  sdata siesta.TBT.nc --atom 20-30[1-3] --dos --ados Left --out dos_20-30_1-3.dat

\end{shellexample}

where the former is the total PDOS on atoms $20$ through $30$, and the

latter is the PDOS on orbitals 1, 2 and 3 on atoms $20$ through

$30$. It thus is extremely easy to extract different PDOS once the

calculation has completed. 

\begin{fdflogicalF}{TBT.T!Bulk}

  Calculate the bulk (pristine) electrode transmission if

  \fdftrue.

  This generates \sysfile{BTRANS\_<>} and \sysfile{AVBTRANS\_<>}.

  \note implicitly enables \fdf{TBT.DOS!Elecs} if \fdftrue.

\end{fdflogicalF}

\begin{fdflogicalF}{TBT.DOS!Elecs}

  Calculate the bulk (pristine) electrode DOS if

  \fdftrue. 

  This generates \sysfile{BDOS\_<>} and \sysfile{AVBDOS\_<>}.

  \note implicitly enables \fdf{TBT.T!Bulk} if \fdftrue.

\end{fdflogicalF}

\begin{fdflogicalF}{TBT.DOS!Gf}

  \fdfdepend{TBT.Atoms!Device}

  Calculate the DOS from the Green function on the atoms in the device

  region. 

  \note this flag should only be used if there are bound states in the

  scattering region (or if one wish to uncover whether there are bound

  states). Due to internal algorithms the DOS from the Green function

  is computationally more demanding than using \fdf{TBT.DOS!A} an

  \fdf{TBT.DOS!A.All}.

  This generates \sysfile{DOS} and \sysfile{AVDOS}.

  See \fdf{TBT.Atoms!Device.Connect}.

\end{fdflogicalF}

\begin{fdflogicalF}{TBT.DOS!A}

  \fdfdepend{TBT.Atoms!Device}

  Calculate the DOS from the spectral function. This will not

  calculate the DOS from the last electrode (last in the list

  \fdf{TBT.Elecs}), see \fdf{TBT.DOS!A.All}. 

  This generates \sysfile{ADOS\_<>} and \sysfile{AVADOS\_<>}.

  See \fdf{TBT.Atoms!Device.Connect}.

\end{fdflogicalF}

\begin{fdflogicalF}{TBT.DOS!A.All}

  \fdfdepend{TBT.Atoms!Device}

  Calculate the DOS from the spectral function and do so with

  \emph{all} electrodes.

  This additionally generates \sysfile{ADOS\_<>} and

  \sysfile{AVADOS\_<>} for the last electrode in \fdf{TBT.Elecs}.

  \note if \fdftrue, this implicitly sets \fdf{TBT.DOS!A} to \fdftrue.

\end{fdflogicalF}

Setting the flags \fdf{TBT.DOS!Gf} and \fdf{TBT.DOS!A.All} to

\fdftrue\ enables the estimation of bound states in the scattering

region via this simple expression

\begin{equation}

  \rho_{\mathrm{bound-states}} = \rho_{\mathbf G} - 

  \sum_i \rho_{\mathbf A_i},

\end{equation}

where the sum is over all electrodes, $\mathbf G$ and $\mathbf A$ are

the Green and spectral function, respectively. Note that typically

$\rho_{\mathrm{bound-states}}=0$. 

\begin{fdfentry}{TBT.T!Eig}[integer]<0>

  Specify how many of the transmission eigenvalues will be

  calculated. 

  This generates \sysfile{TEIG\_<1>\_<2>} and

  \sysfile{AVTEIG\_<1>\_<2>}, however, only for the non-equivalent

  electrode combinations (\tbtrans\ intrinsically assumes

  time-reversal symmetry).

  \note if you specify a number of eigenvalues above the available

  number of eigenvalues, \tbtrans\ will automatically truncate it to a

  reasonable number.

\end{fdfentry}

\begin{fdflogicalF}{TBT.T!All}

  By default \tbtrans\ only calculates transmissions in \emph{one}

  direction because time-reversal symmetry makes $T_{ij}=T_{ji}$. If

  one wishes to assert this, or if time-reversal symmetry does not

  apply for your system, one may set this to \fdftrue\ to explicitly

  calculate all transmissions.

  This additionally generates \sysfile{TRANS\_<1>\_<2>} and

  \sysfile{AVTRANS\_<1>\_<2>} for all electrode combinations (and the

  equivalent eigenvalue files if \fdf{TBT.T!Eig} is \fdftrue.

\end{fdflogicalF}