main.m

Go to the documentation of this file.

%    Eotvos Quantum Transport Utilities - Introduction to EQuUs
%    Copyright (C) 2018 Peter Rakyta, Ph.D.
%
%    This program is free software: you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation, either version 3 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see http://www.gnu.org/licenses/.

%> \LATEX_HEADER
%
%> \mainpage Introduction to @EQuUs @version
%>  
%>  @image latex logo_equus.jpg
%> 
%>  @EQuUs @version is a free software distributed under the <a href="http://www.gnu.org/licenses/">GNU General Public License</a>. 
%>  @EQuUs @version is designed for transport calculations implementing the equilibrium Greens function formalism developed in:
%>  * A. Cresti, G. Grosso and G. Pastori Parravicini, Eur. Phys. J. B <b>53</b>, 537-549 (2006).
%>  * S. Sanvito, C.~J. Lambert, J.~H. Jefferson and A. M. Bratkovsky, Phys. Rev. B <b>59</b>, 11936 (1999).
%>  * I. Rungger and S. Sanvito, Phys. Rev. B <b>78</b>, 035407 (2008).
%>  * P. Rakyta, E. T&oacute;v&aacute;ri, M. Csontos, Sz. Csonka, A. Csord&aacute;s, J. Cserti, Phys. Rev. B <b>90</b>, 125428 (2014).
%>  * P. Rakyta, A. Korm&aacute;nyos, J. Cserti, Phys. Rev. B <b>93</b>, 224510 (2016).
%>  
%>  ## @EQuUs @version comes with the following functionalities:
%>  
%>  <table id="home" style="cell-spacing: 0px;">
%>  <tr>
%>  <td id="tdhome" style="width: 400px">
%>  * Spin and charge transport in normal/superconducting systems
%>  * Multi-terminal structures
%>  * Automatically generated predefined lattice structures
%>  * Inclusion of overlap matrices.
%>  * SVD regularization of the leads.
%>  * Interface for the SIESTA package
%>  * Inclusion of custom Hamiltonians (molecular structures)
%>  * Automatic transformation to the Bogoliubov-de Gennes model
%>  </td>
%>  <td id="tdhome">
%>  @image html intro_focusing_geometry.jpg
%>  @image latex intro_focusing_geometry.jpg
%>  </td>
%>  </tr>
%>  <tr>
%>  <td id="tdhome" style="width: 400px">
%>  @image html intro_geometry.jpg
%>  @image latex intro_geometry.jpg
%>  </td>
%>  <td id="tdhome">
%>  * Efficient numerical components for large-scaled non-trivial structures using \subpage MKL
%>  * Automatic magnetic field and gauge transformation
%>  * DC Josephson current
%>  * DC Josephson current in multi-terminal structures
%>  * Self-consistent framework for electron density based functionals. </br> (self-consistent charge distribution, electron-electron interaction, s-type pair potential)
%>  </td>
%>  </tr>
%>  <tr>
%>  <td id="tdhome" style="width: 400px">
%>  * Transverse momentum resolved computations.
%>  * Computing the energy and the wave function of the eigenstates.
%>  </td>      
%>  <td id="tdhome">
%>  @image html intro_wavefunc.jpg
%>  @image latex intro_wavefunc.jpg
%>  </td>
%>  </tr>
%> 
%>  </table>
%> 
%>  ## Download and Install @EQuUs @version
%>  To download and to install stable packages of @EQuUs @version.x follow instructions at \subpage intall_guide
%> @}



 
%>  \page intall_guide Installation Guide
%> 
%>  \section requirements_sec System requirements
%>    <p class="syntax">@EQuUs @version is compatible with MATLAB R2011b (7.13.0.564) or higher and with Octave 4.0 or higher.
%>  \subsection Download
%>    <p class="syntax">Download @EQuUs @version from the list of provided <a href="download.html">stable packages</a>. Altrenatively @EQuUs @version  package can be downloaded by the shell command</p> <p class="syntax">wget http://eqt.elte.hu/EQuUs/EQuUs_@version.tar.gz </p>
%>  \subsection Unpack
%>    <p class="syntax">Unpack the downloaded package into the directory "/path/to/EQuUs" the commands </p>
%>    <p class="syntax">mkdir /path/to/EQuUs</p>
%>    <p class="syntax">and</p>
%>    <p class="syntax"> tar -xzf EQuUs_@version.tar.gz -C /path/to/EQuUs</p>
%>    <p class="syntax"> to create the output directory and unpack the package respectively.</p>
%> 
%>  \section install_sec Install
%>    <p class="syntax">Add the following lines to the "startup.m" (.octaverc) file located at the search path of MATLAB (Octave):</p>
%>    <p class="syntax" style="height: 45px">addpath('/path/to/EQuUs'); <br> addpath('/path/to/EQuUs/utils'); <br> addpath('/path/to/EQuUs/Filters'); <br> addpath('/path/to/EQuUs/MEX');</p>
%>  
%>    <p class="syntax">Alternatively add the directories "/path/to/EQuUs" and "/path/to/EQuUs/utils" to the search path of MATLAB. To this end open the file pathdef.m and add the following lines:</p> <p class="syntax"  style="height: 45px">'/path/to/EQuUs:', ... <br>'/path/to/EQuUs/utils:', ... <br>'/path/to/EQuUs/Filters:', ...<br>'/path/to/EQuUs/MEX:', ...</p>
%>  
%>    <p class="syntax">In Octave one should also download the <a href="http://xerces.apache.org/mirrors.cgi">Xerces Java XML parser libraries</a> to the installation. Without these libraries Octave would not be able to parse the input files of EQuUs. (However, it is possible to run EQuUs even without XML input file.)</p> 
%>  <p class="syntax">Then add the following lines to the .octaverc file located at the search path of Octave:</p>
%>    <p class="syntax" style="height: 25px"> javaaddpath('/path/to/EQuUs/xerces/xercesImpl.jar'); <br> javaaddpath('/path/to/EQuUs/xerces/xml-apis.jar'); </p>
%>  
%>   <p class="syntax">To install additional components (MKL, Siesta) please refer to the individual pages.</p>
%>  
%>  <p class="syntax">Now the @EQuUs @version package is successfully installed.</p>
%>  
%>  
%>  \section structure_sec The structure of @EQuUs @version
%>  <p class="syntax" style="height: 60px">@EQuUs @version is organized into interfaces. Each interface has a separated workspace consisting of
%>  related variables (e.g., the surface Greens function, the propagating and evanescent modes, the group velocities are grouped into one workspace if they belong to the same lead.). 
%>  The interfaces also provide several methods to run specific calculations on the variables of the workspace. The interfaces form two levels of abstraction.
%>  The members of the 1st level (/root) are responsible for specific elementary tasks, while the interfaces of the 2nd level (/root/utils) combine the functionalities of the 1st level interfaces, and can be used as the building blocks of the studied structure.</p>
%>  
%>  \section run_sec Run @EQuUs @version
%>  <p class="syntax">@EQuUs @version can be run by small MATLAB scripts that initialize the interfaces and combine their functionalities.
%>  Physical and other running parameters (intended not to be changed during the calculations) are read in from an xml structure.
%>  Within the @EQuUs @version package (see the directory "/path/to/EQuUs/Examples") there are provided several executable examples demonstrating the usage of the package. These examples are also invoked by the built-in automatic test procedure (automatic_test.m) of @EQuUs @version.</p>
 
 


 
%>  \page MKL @MKL component
%>  
%>  
%>  The @MKL component is an interface to the <a href="https://software.intel.com/en-us/node/470282">Intel MKL PARDISO</a> package providing a high-performance, robust, memory efficient, and easy to use software package for solving large sparse linear systems of equations on shared memory multiprocessors.
%>  @MKL component uses the <a href="http://www.mathworks.com/help/matlab/matlab_external/introducing-mex-files.html">MEX</a> technology to incorporate C, C++ and fortran libraries into Matlab and Octave packages.
%>  </br>
%>  The PARDISO package enables us to calculate individual elements of the inverse of a sparse matrix. 
%>  Calculating, for example, the Green's function between the surface points of the scattering region, or evaluating the density of states on the atomic sites enables us to treat large scale systems including disorders and other kind of inhomogeneities or performing self-consistent calculations.
%>  The PARDISO solver is based on the following publications:
%>    <ul>
%>             <li>M. Luisier, O. Schenk et.al., Euro-Par 2013, LNCS 8097, F. Wolf, B. Mohr, and D. an Ney (Eds.), Springer-Verlag Berlin Heidelberg, pp. 533-544, 2013.</li>
%>             <li> O. Schenk, M. Bollhofer, and R. Romer, SIAM Review 50 (2008), pp. 91-112.</li>
%>                 <li>O. Schenk, A. Wachter, and M. Hagemann, Journal of Computational Optimization and Applications, pp. 321-341, Volume 36, Numbers 2-3 (April, 2007).</li>
%>    </ul>
%>  </br>
%>  
%>  The @MKL component is compatible with both MATLAB and octave packages, however, one need to compile separate binaries for the two products.
%>  The implemented Intel MKL PARDISO routines can treat structurally symmetric matrices (thus the matrix does not to be Hermitian).
%>  To compile the @MKL component please following the <a href="http://eqt.elte.hu/equus/MKL/install">installation guide</a>.
%>  @MKL can be used as an independent component it does not depend on the other EQuUs components.
%>  </br>
%>  For technical support or for implementing new functionalities please do not hesitate to contact <a href="http://eqt.elte.hu/contact">us</a>.
%>  
%>  ## Usage of the @MKL component
%>  @MKL component contains of individual functions that are independent from other EQuUs components. 
%>  After a successful compilation (see section \ref install_MKL_sec) the generated MEX files can be invoked from the MATLAB/octave command line as described <a href="http://www.mathworks.com/help/matlab/matlab_external/introducing-mex-files.html">here</a>. The description of the individual functions can be found here:
%>  
%>  * dgetPartialInv.c
%>  * zgetPartialInv.c
%>  * dggev.c
%>  * zggev.c
%>  
%>  
%>  \section install_MKL_sec Installation Guide
%>  
%>    \subsection requirements_MKL System requirements
%>    @MKL was successfully compiled and tested with Intel compiler v16.0.2 including MKL v11.2.3.187 and with Intel compiler v12.1.5 including MKL v10.3.11. @MKL can also be compiled and linked with the GNU compiler)
%>    \subsection  download_MKL Download
%>    Download the @EQuUs @version from the list of provided <a href="download.html">stable packages</a>. Altrenatively @EQuUs @version package can be downloaded by the shell command
%>  wget http://eqt.elte.hu/equus/Downloads/EQuUs_@version.tar.gz
%>    \subsection unpack_MKL Unpack
%>    <p class="syntax">Unpack the downloaded package into the directory "/path/to/EQuUs" with the commands </p>
%>    <p class="syntax">mkdir /path/to/EQuUs</p>
%>    <p class="syntax">and</p>
%>    <p class="syntax"> tar -xzf @EQuUs @version.tar.gz -C /path/to/EQuUs</p>
%>    <p class="syntax"> to create the output directory and unpack the package respectively.</p>
%> 
%>   \subsection install_MKL Install
%>   Currently the configuration files for the compilation are given only for Unix system. For Windows system please create appropriate configuration files. (Binaries compiled on Unix system can not be used on other operating systems.)
%>   To compile the @MKL component one needs to setup environment variables EQUUSDIR=/path/to/EQuUs and the standard <a href="https://software.intel.com/en-us/articles/setting-up-the-build-environment-for-using-intel-c-or-fortran-compilers">built-in environment variables</a> of the Intel compiler.
%>   After the environment variables were successfully set, please open and edit the file /path/to/EQuUs/MKL/commonvars.in. This file contains some other variables needed to be also given for a successful installation:
%> 
%>   * MATLABROOT=path/to/the/MATLAB/installation
%>  * OCTAVEROOT=path/to/the/octave/installation
%>   * COMPILER_F=path/to/the/C/compiler/binary
%>   * COMPILER_C=path/to/the/C/compiler/binary
%> 
%> 
%> 
%>  For the compilation use the provided makefile in the directory /path/to/EQuUs/MKL/. The makefile can be run with the following syntax:
%>  <b>make [debug] [THREAD=SEQ/PAR/MIC] [LINKING=static/dynamic] [BUILD=matlab/octave]</b>
%> 
%>   * Use the option debug for verbose compilation.
%>   * Use the option THREAD=SEQ for single threaded compilation, THREAD=PAR for multi threaded (openMP) compilation, or THREAD=MIC for Intel MIC compilation.
%>   * Use the option LINKING=static for static linking of the produced MEX files (thus the MEX files becomes transferable) or LINKING=dynamic for dynamic linking (using shared libraries provided by the system).
%>   * Use the option BUILD=matlab for compilation for MATLAB or BUILD=octave for compilation for octave.