Install
Requirements
Operating system
TBPLaS has been developed and tested on Linux. Ideally, it should work on most Linux distributions. Due to compiler and library compatibility issues, native compilation of TBPLaS on Windows is difficult. If you wish to install TBPLaS on Windows, the best practice is to use virtual machines, e.g., VirtualBox or VMWare. Windows Subsystem for Linux (WSL) is also an option. Since MacOS is actually a unix-like operating system, installing TBPLaS may be possible, as long as the python environment and packages have been properly installed. But we have no experience of MacOS. You are encouraged to send us feedbacks if you have made it.
Compilers and math libraries
The performance-critical parts of TBPLaS are written in Cython and FORTRAN. Also, sparse matrices are utilized to reduce memory cost. So, you need both C and FORTRAN compilers to compile TBPLaS, and link it to vendor-provided math libraries for optimal performance. For Intel CPUs, it is recommended to use Intel compilers and Math Kernel Library (MKL), which are now bundled as oneAPI. If the Intel toolchain is not available, GNU Compiler Collection (GCC) is a general choice. In that case, TBPLaS will use the built-in sparse matrix library.
Python environment
TBPLaS requires Python>=3.7
. In addition to the python interpreter, development headers are also required.
The actual package name of development headers may vary among Linux distributions, e.g., python3-devel
on
rpm-based distributions like CentOS Stream, and python3-dev
on deb-based distributions like Debian. Check the
manual of your distribution package manager, e.g., dnf
or apt-get
, for guidelines on searching and
installing the package.
If you do not have root privileges, or if your computer cannot access the Internet, try the Anaconda offline installer, which bundles the development headers as well as other dependencies.
Dependencies
TBPLaS requires the following Python packages as mandatory dependencies:
numpy
scipy
matplotlib
cython
scikit-build-core
And the following packages as optional:
ase (for LAMMPS interface)
mpi4py (for hybrid MPI+OpenMP parallelization)
Note that scikit-build-core
requires CMake>=3.17
to be installed. We recommend to install the latest version of
the packages via the pip
or conda
commands, e.g., pip install numpy
or conda install numpy
.
If you do not have root privileges to make a system-wide installation, try either of the following solutions:
Create a virtual environment in your home direcotry and activate it before installation (recommended for most users)
Add the
--user
option, e.g.pip install --user numpy
(recommended for most users)Add the
--prefix
option, e.g.pip install --prefix=DEST numpy
, and updatePYTHONPATH
accordingly (only for advanced users)
The installation of mpi4py
is somewhat complex. You need a working MPI implementation. Since OpenMPI
suffers from a limitation on the number of OpenMP threads when there are too few MPI processes,
MPICH3 or newer is preferred. See the following links for installing
MPICH,
OpenMPI,
and MPI4PY.
Get the source code
The source code is available at this link. If you have downloading problems, send an e-mail to the development team at Developers.
Configuration
The configuration of compilation is stored in the tool.scikit-build.cmake.define
section of
pyproject.toml
in the top directory of TBPLaS source code, which should look like:
[tool.scikit-build.cmake.define]
USE_INDEX64 = "OFF"
USE_MKL = "OFF"
# GCC
CMAKE_C_COMPILER = "gcc"
CMAKE_Fortran_COMPILER = "gfortran"
CMAKE_C_FLAGS = "-march=native -mtune=native"
CMAKE_Fortran_FLAGS = "-cpp -march=native -mtune=native -fopenmp -fno-second-underscore"
## Intel
#CMAKE_C_COMPILER = "icx"
#CMAKE_Fortran_COMPILER = "ifx"
#CMAKE_C_FLAGS = "-xHost"
#CMAKE_Fortran_FLAGS = "-fpp -xHost -qopenmp -ipo -heap-arrays 32"
Here USE_INDEX64
and USE_MKL
are two switches whose value should be either ON
or OFF
. The following
lines define the C and Fortran compilers and the compilation flags. Uncomment the lines of the compiler you wish to
use. Note that the executables of Intel compiler have been recently renamed to icx
and ifx
. For older versions,
they may be icc
and ifort
. For Intel compiler, you can also use the sparse matrix library from MKL by setting
USE_MKL
to ON
.
64-bit array index
TBPLaS uses 32-bit array index by default, even if it has been compiled and installed on a 64-bit host. While the RAM
usage is reduced in this approach, segmentation fault may be raised if the model is very large (billions of orbitals).
In that case, the version with 64-bit array index should be used. To compile the 64-bit version, firstly go to
tbplas/fortran
directory and pre-process the FORTRAN source files by:
cd tbplas/fortran
../../scripts/set_int.py 64
Then set the USE_INDEX64
switch to ON
. The compilation flags will be updated automatically, so no further
configuration is required. Note that MKL DOES NOT work with 64-bit array index.
Installation
Once pyproject.toml
has been properly configured, you can build and install TBPLaS with pip install .
.
The package will be install to the default library path. If you do not have root privileges, try the solutions
aforementioned in Dependencies. After installation, go to some other directory and invoke Python, e.g.,
cd tests && python
. Since TBPLaS uses relative imports for package management, staying in the source code
directory when invoking Python may cause errors like this:
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/yhli/proj/tbplas/tbplas/__init__.py", line 2, in <module>
from .adapter import *
File "/home/yhli/proj/tbplas/tbplas/adapter/__init__.py", line 2, in <module>
from .wannier90 import *
File "/home/yhli/proj/tbplas/tbplas/adapter/wannier90.py", line 11, in <module>
from ..builder import PrimitiveCell, PCHopDiagonalError
File "/home/yhli/proj/tbplas/tbplas/builder/__init__.py", line 2, in <module>
from .advanced import *
File "/home/yhli/proj/tbplas/tbplas/builder/advanced.py", line 17, in <module>
from .primitive import PrimitiveCell, PCInterHopping
File "/home/yhli/proj/tbplas/tbplas/builder/primitive.py", line 12, in <module>
from ..cython import primitive as core
ImportError: cannot import name 'primitive' from 'tbplas.cython' (/home/yhli/proj/tbplas/tbplas/cython/__init__.py)
So it is mandatory to go to another directory. After Python has been invoked, try import tbplas
. If no error occurs,
then your installation is successful.
Testing
There are some testing scripts under the tests
directory of source code. You can test your compilation and
installation by invoking these scripts, e.g., python test_base.py
. Some output will be printed to the screen and
some figures will be saved to disk. If everything goes well, a notice will be raised saying all the tests have been
passed by the end of each script.