<T>LAPACK

C++ Template Linear Algebra PACKage

About

First things to know about <T>LAPACK:

1. We write   <T>LAPACK   whenever it is possible. This includes all software documentation, discussions, and presentation.
2. We say it   T-L-A-PACK   .
3. We use   tlapack   for files, folders, and links, to make it more portable and easier to use.

<T>LAPACK provides:

• Precision-neutral function template implementation

Supported in part by NSF ACI 2004850.

Installation

<T>LAPACK is built and installed with CMake.

Getting CMake

You can either download binaries for the latest stable or previous release of CMake, or build the current development distribution from source. CMake is also available in the APT repository on Ubuntu 16.04 or higher.

Building and Installing <T>LAPACK

<T>LAPACK can be build following the standard CMake recipe

mkdir build
cmake -B build -D CMAKE_INSTALL_PREFIX=/path/to/install . # configuration step
cmake --build build                  # build step
cmake --build build --target install # install step

CMake options

Standard environment variables affect CMake. Some examples are

CXX                 C++ compiler
CXXFLAGS            C++ compiler flags
LDFLAGS             linker flags

The Fortran and C wrappers to <T>LAPACK also use, among others,

CC                  C compiler
CFLAGS              C compiler flags
FC                  Fortran compiler
FFLAGS              Fortran compiler flags

• This page lists the environment variables that have special meaning to CMake.

It is also possible to pass variables to CMake during the configuration step using the -D flag. The following example builds <T>LAPACK in debug mode inside the directory build

mkdir build
cmake -B build -DCMAKE_BUILD_TYPE=Debug .
cmake --build build

• This page documents variables that are provided by CMake or have meaning to CMake when set by project code.

<T>LAPACK options

Here are the <T>LAPACK specific options and their default values

# Option                            # Default

BUILD_BLASPP_TESTS                  OFF

    Build BLAS++ tests. If enabled, please inform the path with the test sources of BLAS++ in the CMake variable blaspp_TEST_DIR.
    REQUIRES: BUILD_TESTING=ON

BUILD_EXAMPLES                      ON
    
    Build examples

BUILD_LAPACKPP_TESTS                OFF

    Build LAPACK++ tests. If enabled, please inform the path with the test sources of LAPACK++ in the CMake variable lapackpp_TEST_DIR.
    REQUIRES: BUILD_TESTING=ON

BUILD_testBLAS_TESTS                ON

    Build testBLAS tests.
    REQUIRES: BUILD_TESTING=ON

BUILD_TESTING                       ON

    Build the testing tree
    
BUILD_C_WRAPPERS                          OFF

    Build and install C wrappers (Work In Progress)

BUILD_CBLAS_WRAPPERS                      OFF

    Build and install CBLAS wrappers (Work In Progress)
    
BUILD_Fortran_WRAPPERS                    OFF

    Build and install Fortran wrappers (Work In Progress)

TLAPACK_CHECK_INPUT                 ON

    Enable checks on input arguments.
    REQUIRES: TLAPACK_NDEBUG=OFF

TLAPACK_DEFAULT_INFCHECK            ON

    Default behavior of checks for Infs. Checks can be activated/deactivated at runtime.
    REQUIRES: TLAPACK_NDEBUG=OFF
              TLAPACK_ENABLE_INFCHECK=ON

TLAPACK_DEFAULT_NANCHECK            ON

    Default behavior of checks for NaNs. Checks can be activated/deactivated at runtime.
    REQUIRES: TLAPACK_NDEBUG=OFF
              TLAPACK_ENABLE_NANCHECK=ON

TLAPACK_ENABLE_INFCHECK             OFF

    Enable check for Infs as specified in the documentation of each routine.
    REQUIRES: TLAPACK_NDEBUG=OFF

TLAPACK_ENABLE_NANCHECK             OFF

    Enable check for NaNs as specified in the documentation of each routine.
    REQUIRES: TLAPACK_NDEBUG=OFF

TLAPACK_INT_T                       int64_t

    Type of all non size-related integers in libtlapack_c, libtlapack_cblas, libtlapack_fortran, and in the routines of the legacy API. It is the type
    used for the array increments, e.g., incx and incy.
    Supported types:
        int, short, long, long long, int8_t, int16_t,
        int32_t, int64_t, int_least8_t, int_least16_t,
        int_least32_t, int_least64_t, int_fast8_t, 
        int_fast16_t, int_fast32_t, int_fast64_t, 
        intmax_t, intptr_t, ptrdiff_t
    NOTE: TLAPACK_INT_T=int64_t if USE_LAPACKPP_WRAPPERS=ON

TLAPACK_NDEBUG                      OFF

    Disable all error checks.

TLAPACK_SIZE_T                      size_t

    Type of all size-related integers in libtlapack_c, libtlapack_cblas, libtlapack_fortran, and in the routines of the legacy API.
    Supported types:
        int, short, long, long long, int8_t, int16_t,
        int32_t, int64_t, int_least8_t, int_least16_t,
        int_least32_t, int_least64_t, int_fast8_t, 
        int_fast16_t, int_fast32_t, int_fast64_t, 
        intmax_t, intptr_t, ptrdiff_t,
        size_t, uint8_t, uint16_t, uint32_t, uint64_t
    NOTE: TLAPACK_SIZE_T=int64_t if USE_LAPACKPP_WRAPPERS=ON

USE_LAPACKPP_WRAPPERS               OFF

    Use LAPACK++ wrappers to link with optimized BLAS and LAPACK libraries.
    Mind that LAPACK++ needs BLAS++.
    Branches compatible with <T>LAPACK:
        https://bitbucket.org/weslleyspereira/blaspp/branch/tlapack
        https://bitbucket.org/weslleyspereira/lapackpp/branch/tlapack

Testing

<T>LAPACK is continuously tested on Ubuntu, MacOS and Windows using GNU compilers. See the latest test results in the (Github Actions)[https://github.com/tlapack/tlapack/actions/workflows/cmake.yml] webpage for <T>LAPACK. The tests split into three categories:

• Test routines in test/src using

  1. various precision types: float, double, std::complex<float>, std::complex<double> and Eigen::half.

  2. various matrix and vector data structures: tlapack::legacyMatrix, Eigen::Matrix and std::experimental::mdspan (the latter from https://github.com/kokkos/mdspan).

• Tests from testBLAS for good conformance with BLAS standards.

• BLAS++ testers and LAPACK++ testers for measuring performance and accuracy compared to LAPACKE.

To test <T>LAPACK, build with BUILD_TESTING=ON. Then, run ctest inside the build directory.

Documentation

• Online documentation for the master branch at https://tlapack.github.io/tlapack.

• Run doxygen docs/Doxyfile to generate the <T>LAPACK documentation via Doxygen in your local machine.

License

BSD 3-Clause License

Copyright (c) 2021-2023, University of Colorado Denver. All rights reserved.

Copyright (c) 2017-2021, University of Tennessee. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.