Prerequisites
WannierTools is written in Fortran language. In order to install WannierTools, basic UNIX knowledge is required. The user should be acquainted with the tar, gzip or git, and ideally with the make command of the UNIX environment.
For WannierTools version 2.6.0 or lower,
You need to install the following (mandatory) packages:
* Fortran compiler (Gfortran or ifort)
* MPICH higher than 2.1.5 (if -DMPI is specified)
* LAPACK and BLAS library
For WannierTools version 2.6.0 or higher,
You need to install the following (mandatory) packages:
* Fortran compilers (Gfortran or ifort)
* MPICH version higher than 2.1.5 (if -DMPI is specified)
* Intel MKL library (To support the large scale simulations)
* ARPACK library (To support the large scale simulations)
BLAS (Basic Linear Algebra Subprograms) are routines that provide standard building blocks for performing basic vectors and matrix operations, such as scalar, vector, vector-matrix operations. LAPACK (Linear Algebra Package) can help us deal with eigenvalue problems, singular value problems and other more advanced linear algebra problems.
If you want to run WannierTools in multicore system, you need an implementation of Message Passing Interface (MPI) such as MPICH.
For WannierTools version 2.6.1 or higher, we utilize ARPACK (ARnoldi Package) and MKL (Math Kernel Library) library to support the large scale simulations such as twisted graphene systems and Landau level spectrum calculations. ARPACK is an ideal tool to solve large sparse matrices and is able to solve a few eigenvalues specified by the user. MKL is designed by Intel and is a optimized library math routines for science maths, etc. Its core math function include BLAS, LAPACK, etc. We will provide a simple installation guide of ARPACK in the last section. As for the MKL library, the installation is relatively easy and you can just follow the instructions provided by Intel.
How to obtain
WannierTools is an open source software. You can download the latest version from Github repository https://github.com/quanshengwu/wannier_tools
Using git clone:
git clone https://github.com/quanshengwu/wannier_tools.gitOr download the zip or tar.gz file from https://github.com/quanshengwu/wannier_tools/releases
You can choose your favorite version in this page by clicking the Releases.
Build System
For WannierTools version 2.6.0 or lower
After uncompressing the source file, you will get a folder called wann_tools/ (we call it root directory)which contains six subfolders, bin, doc, examples, phonopyTB, src, wannhr_symm.
1. root/src
Holds the source files of WannierTools, and a low-level Makefile.
2. root/bin
Holds executable binary file wt.x after the compilation.
3. root/examples
Holds several typical examples.
4. root/doc
Holds the documentation files.
5. root/phonopyTB
Holds the python scripts to generate tight binding models for phonon system.
6. root/wannhr_symm
Holds the python scripts to symmetrize the tight binding model.
For WannierTools version 2.6.1 or higher
After uncompressing the source file, you will get a folder called wannier_tools-x.x.x/ (we call it root directory), which also contains 6 subfolders, bin, doc, examples, src, utility as well as useful_scripts.
1. root/src
Holds the source files of WannierTools, and several low-level Makefile files.
2. root/bin
Holds executable binary file wt.x after the compilation.
3. root/examples
Holds several typical examples.
4. root/doc
Holds the documentation files.
5. root/useful_scripts
Holds a few useful scripts such as one that helps you to plot Wely points the first Brillouin Zone.
6. root/utility
Holds some scripts to generate tight binding models for phonon system, twisted graphene system, kp model for twisted graphene system and to symmetrize wannier90_hr_dat.
Compile WannierTools
For WannierTools version 2.6.0 or lower
After you successfully download the WannierTools, the first thing to do is to extract the file from the compressed file.
Then Go into wannier_tools/soc directory, Choose and Edit Makefile, Change the BLAS library ” libs= ” to your LAPACK+BLAS library
At present, we prepared 3 typical Makefiles, which are squential+gfotran, sequential+ifort and mpi+ifort.
For the mpi compiler, you should switch on the compile flag “-DMPI”, see Makefile.intel-mpi
After the compliation, the binary ‘wann_tools’ is copied to wannier_tools/bin/, you can put this path to the system PATH with :
export PATH=/where/you/downloaded/wannier_tools/bin:$PATHto the “.bashrc” file in your home directory.Notice that normally “.bashrc” file is a hidden file, you can use “locate” to find it.
For wannierTools version 2.6.1 or higher
The compilation process is basically the same and the biggest difference is the Makefile.
For version 2.6.1 or higher, we prepare you with 6 different types of Makefiles, which gives you the flexibility to compile WannierTools using different compilers.
Simlarly, then choose and edit your Makefile. You need to add the path for “MKLROOT=“, which states where your MKL libary locates. Besides, the “ARPACK=” path also needs to be changed to the actual path in your computer.
The same as what you do for WannierTools version 2.6.0 or lower. After the compliation, the binary ‘wt.x’ is copied to wannier_tools/bin/, you can put this path to the system PATH with :
export PATH=/where/you/downloaded/wannier_tools/bin:$PATHto the “.bashrc” file in your home directory.
Here, we provide a tutorial of how to compile WannierTools.
1. go the to src folder in the wannier in directory by typing :$ cd /where/your/wannier_tools/is/installed/wannier_tools-2.6.2/src
2. copy one of the Makefiles as Makefile. Here, we will use Makefile.intel-seq :$ cp Makefile.intel.seq Makefile
3. edit the Makefile by vim editor :$ vi Makefile
you need to add the path by assigning the value to the variable “MKLROOT=” :MKLROOT = /where/your/MKLlib/is/installed/
4. change the path of ARPACK and the .a file according to your “ARPACK=” libary :ARPACK = /where/your/ARPACK/is/librapack_SUN4.a
Be sure that your path is correct so that the Makefile can sucuessfully locate you library.
5. Then type :$ make
in the src folder, the compilation process may take dozens of seconds.
6. If the compilation is successful, you then need to find “.bashrc“ file in your computer and add the path :$ export PATH=where/your/wannier_tools/is/installed/wannier_tools-2.6.2/bin:$PATH
7. then, use :$ source .bashrc
to execute the “.bashrc`` file. Thus, you will be able to make wt.x a executable command.
Compiler Variables
The main function of Makefile is to tell make command how to compile the source files and link them to make them an executable program. Some detailed tutorials can be found in the following links:
Makefile aims to tell the make command how to compile and link programs. More specifically, Makefile tells the make how to translate the source files, i.e .f90 files in WannierTools, into Object files, .o files and them link these .o files together to make them become an executable program.
For WannierTools version 2.6.0 or lower.
The only thing you need to do is to customize the libs path according to your computer and add “-L” before your you libs path is the “-L” is missing. “-L” together with the path tell the linker where to look for the function libraries.
We also add some comments in the Makefile.gfortran to help you understand some of the basic paramaters in this Makefile.
For WannierTools version 2.6.1 or higher
–
Here, we will show the file Makefile.intel-seq provided in the WannierTools-2.6.2 to explain how to compile WannierTools with Makefile.
Here, we would like to emphasize some important parts and how you can costomize the Makefile to compile WannierTools. We will not provide a generlized description on how to write Makefile and explain the specific details.
The first thing that needs to be emphasized is the pre-compile options specified after option “-cpp” of gfortran or “-fpp” of ifort . Those options start with “-D” include -DINTELMKL, -DMPI. “-DMPI” means that the MPI is supported. The “-DINTELMKL” means that we use MKL as the LAPACK and BLAS library. MKL is needed since the “zmat_mkldss_zgesv” subroutine is called in sparse.f90.
Secondly, you will need to specify the path of MKLROOT since we have to access the mkl_dss.f90 file specified in the INCLUDE path.
Lastly, please adjust the path of ARPACK accordingly. We just provide an example and you have to make some adjustments according to your computer.
ARPCK Installation
After you download ARPACK from the internet. The home directory in ARmake.inc file is required to be adjusted so that it allows the program to find essential directories, i.e. BLASdir, LAPACKdir, etc. Then you can make your file. Notice that it is best to use the same comiler to compile WannierTools to prevent some unexpecting errors to occur.
