.. _install: Install ======= Get the packages ---------------- The packages are available at `this link `_. If you have downloading problems, contact the :ref:`developers`. From version 2.0, TBPLaS will be released as two separate packages, namely ``tbplas-cpp`` and ``tbplas-py``, which contain the C++ and Python APIs, respectively. ``tbplas-py`` is originally the ``tbplas`` package, and inherits the version number, i.e., the first release will have the version number of 2.0. On the contrary, ``tbplas-cpp`` is a new package, and will be versioned from zero. That's to say, the first release will have the version number of 0.0. Both packages need to be installed for full functionality. Pre-compiled installers are also available. For ``tbplas-py`` the wheel installer is cross-platform, while for ``tbplas-cpp`` the pre-compiled installer is Windows-only. For optimal performance and full functionality, native build from source code is recommended for ``tbplas-cpp``. If you prefer native build, proceed with the following sections. Otherwise, go ahead to :ref:`installers`. Prerequisites ------------- Operating system ^^^^^^^^^^^^^^^^ TBPLaS has been developed and tested on Linux. Ideally, it should work on most Linux distributions. Since MacOS is also a unix-like operating system, installation may be possible if the required packages have been properly installed. For Windows, it is recommend to use virtual machines, e.g., `VirtualBox `_ or `VMWare `_. `WSL `_ is also an alternative. If you insist on native build on Windows, try `MSYS2 `_. Compilers ^^^^^^^^^ TBPLaS requires a C++ compiler supporting ``C++17`` standard and ``OpenMP 4.0`` specifications. The following compilers have been tested: * GCC 7.5.0 * Intel oneAPI 2023.1.0 * AMD AOCL 5.0.0 (Clang 17.0.6) .. admonition:: Compatibility Notice :class: important MSVC (Microsoft Visual C++ Compiler) does not fully support OpenMP 4.0. We recommend GCC of the ``UCRT64`` environment of MSYS2 on Windows. Actually, we use that environment to build the pre-compiled installers. Builder ^^^^^^^ ``CMake>=3.15`` is required to build TBPLaS. We have tested version 3.29. Parallel / GPU computation framework (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ GPU computation support requires either ``NVIDIA CUDA toolkit`` or ``NVIDIA HPC SDK``. Parallelization over k-points and random samples requires ``MPI``. The following versions have been tested: * NVIDIA CUDA toolkit 12.4, 12.8 * NVIDIA HPC SDK 23.5 * MPICH 4.1.2 * Intel oneAPI 2023.1.0 Math libraries (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^ TBPLaS utilizes the ``Eigen`` library for dense linear algebra calculations, which can use ``BLAS`` and ``LAPACK`` as backends under the hood. We have also implemented interfaces to call BLAS and LAPACK directly. Vendor-provided sparse matrix libraries supporting ``CSR`` format can be utilized for optimal performance in TBPM calculations, while searching for eigenvalues within a specific energy range requires ``FEAST>=4.0``. The following versions have been tested: * Netlib LAPACK 3.12.0 * OpenBLAS 0.3.28 * Intel oneAPI 2023.1.0 * AOCL 5.0.0 * FEAST 4.0 I/O (optional) ^^^^^^^^^^^^^^ Binary I/O requires the ``HDF5`` library with ``C++ interface``. If not available, TBPLaS will use the default text-based I/O. We have tested version 1.14.2. Python environment ^^^^^^^^^^^^^^^^^^ TBPLaS requires ``Python>=3.7``. In addition to the Python interpreter, development headers are also required, as well as ``NumPy``, ``SciPy``, ``Matplotlib``, ``Cython``, ``setuptools>=40.8.0`` and ``build>=1.2.2`` packages. LAMMPS and DeepH-pack interfaces requires ``ASE`` and ``h5py`` as optional dependencies. The following versions have been tested: * Python 3.12.9 * NumPy 1.26.3, 2.2.4 * SciPy 1.11.4, 1.15.2 * Matplotlib 3.8.0, 3.10.0 * Cython 3.0.6, 3.0.11 * setuptools 40.8.0 * build 1.2.2 * ASE 3.24.0 * h5py 3.12.1 The most convenient approach to install the packages is to use the `Anaconda `_ or `WinPython `_ distributions. After installation, firstly create a virtual environment, then proceed with the package manager to install the packages, e.g., ``conda`` or ``pip``. Setting up the environment variables ------------------------------------ To ensure that the installation guide function correctly, we assume that all the dependencies, EXCEPT the Python environment, should be compiled from source code and installed into the ``$HOME/tbplas_dev`` directory. This is typically achieved by specifying the installation destination using the ``--prefix`` or ``CMAKE_INSTALL_PREFIX`` options. Note that some dependencies may have their own prefix options, or do not provide any such options at all. Discussion on these cases will be beyond the scope of this installation guide. The users are recommended to consult the installation guides of these packages for correctly installing them into the ``$HOME/tbplas_dev``. After the installation of the dependencies, especially from source code, some relevant environment variables need to be configured, such that the compiler and CMake can find the headers and libraries. We offer a bash script ``tbplas-cpp-VERSION_CPP/tools/init.sh`` (replace VERSION_CPP with the actually version number) for configuring the environment variables, which can be installed by: .. code-block:: bash :emphasize-lines: 0 # Unpack the source code, replace VERSION_CPP with the actually version number tar -xf tbplas-cpp-VERSION_CPP.tar.bz2 # Install to tbplas_dev directory cp tbplas-cpp-VERSION_CPP/tools/init.sh $HOME/tbplas_dev source $HOME/tbplas_dev/init.sh # Update shell settings echo "source $HOME/tbplas_dev/init.sh" >> $HOME/.bashrc Suppose we are going to build TBPLaS with ``OpenBLAS 0.3.28``, ``HDF5 1.14.2`` and ``FEAST 4.0``. The dependencies have been built from source code and installed into the ``$HOME/tbplas_dev`` directory, and the Python virtual environment we have prepared for the installation is named ``tbplas``. Then the following bash commands will set up the relevant environment variables: .. code-block:: bash :emphasize-lines: 0 # HDF5 dest=$HOME/tbplas_dev/hdf5-1.14.2 set_mod add pkg $dest set_env add CMAKE_PREFIX_PATH $dest # OpenBLAS dest=$HOME/tbplas_dev/openblas-0.3.28 set_mod add pkg $dest set_env add CMAKE_PREFIX_PATH $dest set_env add CMAKE_MODULE_PATH $dest/lib/cmake/openblas unset dest # FEAST reset_env add FEASTROOT $HOME/tbplas_dev/FEAST/4.0 # Python environment conda activate tbplas Add the settings to ``$HOME/.bashrc`` if you want them to be permanently effective. If the dependencies have been installed from software repository, probably their paths are already included in the environment variables. In that case, skip the settings for HDF5, OpenBLAS and FEAST. Some dependencies may have their own instructions on setting up the environment variables, e.g., Intel oneAPI, AOCC, AOCL, CUDA toolkit and HPC SDK. Check the official installation guides of these dependencies for more details. Installation ------------ The two packages ``tbplas-cpp`` and ``tbplas-py`` can be installed independently from each other, enabling the decoupling of C++ and Python API. The aim of this design is to have a unified Python frontend that can be dynamically switched between C++ backends with different features, e.g., one with CUDA and the other with MPI support. tbplas-cpp ^^^^^^^^^^ To compile ``tbplas-cpp``, create the build directory and change to it: .. code-block:: bash :emphasize-lines: 0 cd tbplas-cpp-VERSION_CPP test -d build && rm -rf build mkdir build && cd build Then invoke CMake with the following options to configure the build: .. code-block:: bash :emphasize-lines: 0 cmake .. \ -DCMAKE_INSTALL_PREFIX=$HOME/tbplas_dev/tbplas-cpp-VERSION_CPP \ -DCMAKE_C_COMPILER=gcc \ -DCMAKE_CXX_COMPILER=g++ \ -DCMAKE_BUILD_TYPE=Release \ -DBUILD_SHARED_LIBS=on \ -DBUILD_EXAMPLES=on \ -DBUILD_TESTS=off \ -DBUILD_PYTHON_INTERFACE=on \ -DWITH_OPENMP=on \ -DWITH_MPI=off \ -DWITH_CUDA=off \ -DWITH_FEAST=off \ -DWITH_HDF5=off \ -DEIGEN_BACKEND=default \ -DDIAG_BACKEND=default \ -DTBPM_BACKEND=default Interpretation of the options: * ``CMAKE_INSTALL_PREFIX``: installation destination * ``CMAKE_C_COMPILER``: C compiler * ``CMAKE_CXX_COMPILER``: C++ compiler * ``BUILD_EXAMPLES``: whether to build the example programs * ``WITH_OPENMP``: whether to enable OpenMP-based parallelization * ``WITH_MPI``: whether to enable MPI-based parallelization * ``WITH_CUDA``: whether to enable GPU computation based on CUDA * ``WITH_FEAST``: whether to enable interface to FEAST library * ``EIGEN_BACKEND``: math library for general linear algebra operations * ``DIAG_BACKEND``: math library for Hamiltonian diagonalization * ``TBPM_BACKEND``: math library for time propagation For example, setting ``WITH_MPI`` to ``on`` will enable MPI-based parallelization, while setting ``DIAG_BACKEND`` to ``openblas`` will utilize OpenBLAS for diagonalization-based calculations. For more details, see :ref:`misc`. Customize the options according to your needs. Note that some of the options are mutually exclusive. If the configuration succeeds, proceed with the compilation: .. code-block:: bash :emphasize-lines: 0 make -j The example programs, libraries and extensions will be produced in the ``bin`` and ``lib`` subdirectories of the build directory, respectively. Finally, install the files to ``CMAKE_INSTALL_PREFIX`` by: .. code-block:: bash :emphasize-lines: 0 make install And set up the environments variables by: .. code-block:: bash :linenos: :emphasize-lines: 0 reset_env add TBPLAS_CPP_INSTALL_PATH $HOME/tbplas_dev/tbplas-cpp-VERSION_CPP reset_env add TBPLAS_CORE_PATH $TBPLAS_CPP_INSTALL_PATH/lib64 The 1st line defines the installation directory of ``tbplas-cpp``, and the 2nd line sets the location of extensions. Add the settings to ``$HOME/.bashrc`` if you want them to be permanently effective. GPU version ^^^^^^^^^^^ To build ``tbplas-cpp`` with GPU support, set the ``WITH_CUDA`` option to ``on`` when configuring the build. Also, add the ``CUDA_ARCHITECTURES`` option to the configuration options. Here is an example: .. code-block:: bash :emphasize-lines: 0 cmake .. \ -DCMAKE_INSTALL_PREFIX=$HOME/tbplas_dev/tbplas-cpp-VERSION_CPP \ -DCMAKE_C_COMPILER=gcc \ -DCMAKE_CXX_COMPILER=g++ \ -DCMAKE_BUILD_TYPE=Release \ -DBUILD_SHARED_LIBS=on \ -DBUILD_EXAMPLES=on \ -DBUILD_TESTS=off \ -DBUILD_PYTHON_INTERFACE=on \ -DWITH_OPENMP=on \ -DWITH_MPI=off \ -DWITH_CUDA=on \ -DCUDA_ARCHITECTURES=61 \ -DWITH_FEAST=off \ -DWITH_HDF5=off \ -DEIGEN_BACKEND=default \ -DDIAG_BACKEND=default \ -DTBPM_BACKEND=default The ``CUDA_ARCHITECTURES`` option controls the target of code generation via the ``CUDA_NVCC_FLAGS`` flag: .. code-block:: cmake :emphasize-lines: 0 set(_cuda_arch "compute_${CUDA_ARCHITECTURES}") set(_cuda_code "sm_${CUDA_ARCHITECTURES}") set(CUDA_NVCC_FLAGS " ${CUDA_NVCC_FLAGS} --compile -Xcompiler=-fPIC; -std=c++17 -gencode arch=${_cuda_arch},code=${_cuda_code}") You must set the correct architecture of your GPU device, other ``tbplas-cpp`` will not work. For better compatibility, ``gcc`` and ``g++`` are recommend as C/C++ compilers. tbplas-py ^^^^^^^^^ The installation of ``tbplas-py`` is much simpler. Unpack the source code and run ``pip`` by: .. code-block:: bash :emphasize-lines: 0 # Replace VERSION_PY with the actual version number tar -xf tbplas_py-VERSION_PY.tar.bz2 cd tbplas_py-VERSION_PY pip install . which will install ``tbplas-py`` into the virtual environment of ``tbplas``. Testing ------- Finally, run the test suite under ``tbplas_py-VERSION_PY/tests`` by: .. code-block:: bash :emphasize-lines: 0 cd tests ./run_tests.sh The band structure, density of states and many other capabilities will be demonstrated by the test suite. If everything goes well, then the installation is successful. .. _installers: Pre-compiled installers ----------------------- tbplas-cpp ^^^^^^^^^^ Pre-compiled installer for ``tbplas-cpp`` is available on Windows. To install the package, unpack the installer to a path without spaces and non-ascii characters, e.g., ``D:\tbplas-cpp-VERSION_CPP-win64``, then create a new environment variable in the following approach: 1. Open ``PowerShell`` and invoke the registry editor by typing ``regedit.exe``. 2. Navigate to ``Computer\HKEY_CURRENT_USER\Environment``. 3. Right-click to create a new key ``TBPLAS_CORE_PATH`` with the value being the installation path, e.g., ``D:\tbplas-cpp-VERSION_CPP-win64``. 4. Reboot for the environment variables to take effect. tbplas-py ^^^^^^^^^ Open ``PowerShell`` and change to the directory containing the installer. Then install the package by: .. code-block:: PowerShell :emphasize-lines: 0 pip install .\tbplas_py-VERSION_PY-py3-none-any.whl