This directory builds a library that implements a subset of LAPACK‘s Fortran 77 interface in C++, on top of Eigen’s dense decompositions. A program that calls only the routines listed below can link it in place of reference LAPACK. Eigen's C++ API does not use it.
dgetrf_), every argument passed by pointer, column-major matrices with a leading dimension, and complex numbers stored as (real, imaginary) pairs. Dimensions, pivot indices and INFO are 32-bit int, or 64-bit in the ILP64 build (eigen_lapack_ilp64), which exports the same names and links Eigen's ILP64 BLAS library.INFO argument, an invalid i-th argument makes the routine call XERBLA and return INFO = -i, as in reference LAPACK. The auxiliary routines have no INFO argument and do not check their arguments.XERBLA that prints the error and returns, where reference XERBLA stops the program. With GNU-compatible compilers other than MinGW and Cygwin it is a weak symbol, so a program can define its own.WORK only to answer a workspace query (LWORK = -1). xSYEV still requires LWORK >= max(1, 3*N-1), and xHEEV LWORK >= max(1, 2*N-1).The library is enabled with EIGEN_BUILD_LAPACK and requires EIGEN_BUILD_BLAS. Both default to ON when Eigen is the top-level CMake project. The lapack target builds eigen_lapack_static, which links eigen_blas_static. Where the platform supports shared libraries (EIGEN_BUILD_SHARED_LIBS), it also builds eigen_lapack, which links eigen_blas. With EIGEN_BUILD_LAPACK_ILP64, which defaults to EIGEN_BUILD_BLAS_ILP64, it builds the same pair with 64-bit integers, eigen_lapack_ilp64_static and eigen_lapack_ilp64, which link Eigen's ILP64 BLAS libraries. EIGEN_INSTALL installs them all.
The tables follow the classification in Chapter 2 of the LAPACK Users' Guide, third edition:
An x in a routine name stands for a precision prefix. The Precisions column lists the prefixes that exist:
| Problem | Routine | Precisions | Computes | Implemented with |
|---|---|---|---|---|
| Symmetric eigenproblem (SEP) | xSYEV | S, D | All eigenvalues and, optionally, the eigenvectors of a symmetric matrix | SelfAdjointEigenSolver |
xHEEV | C, Z | The same for a Hermitian matrix; the imaginary part of its diagonal is ignored | SelfAdjointEigenSolver | |
| Singular value decomposition (SVD) | xGESVD | S, D, C, Z | A = U Σ V^H: the singular values and, optionally, the left and right singular vectors | JacobiSVD (two-sided Jacobi, not bidiagonal QR iteration) |
xGESDD | S, D, C, Z | The same, by divide and conquer | BDCSVD |
The library has no driver for any other problem class in §2.3:
xGESV, xPOSV, ...).| Problem | Routine | Precisions | Computes | Implemented with |
|---|---|---|---|---|
| Linear equations (§2.4.1), general matrix | xGETRF | S, D, C, Z | LU factorization with partial pivoting, A = P L U | PartialPivLU's blocked kernel |
xGETRS | S, D, C, Z | Solves A X = B, A^T X = B or A^H X = B with the factors from xGETRF | Triangular solves | |
xGETRI | S, D, C, Z | inv(A) = inv(U) inv(L) P^T from the factors of xGETRF, blocked over WORK | xTRTRI and triangular solves | |
| Linear equations (§2.4.1), symmetric or Hermitian positive definite matrix | xPOTRF | S, D, C, Z | Cholesky factorization, A = U^H U or A = L L^H | LLT's blocked kernel |
xPOTRS | S, D, C, Z | Solves A X = B with the factor from xPOTRF | Triangular solves | |
xPOTRI | S, D, C, Z | inv(A) from the factor of xPOTRF | xTRTRI, then xLAUUM | |
| Linear equations (§2.4.1), symmetric or Hermitian positive semidefinite matrix | xPSTRF | S, D, C, Z | Cholesky factorization with complete pivoting, P^T A P = U^H U or L L^H, stopping at the numerical rank | LDLT's panel kernel, pivoting on the largest diagonal entry |
| Linear equations (§2.4.1), symmetric indefinite matrix | xSYTRF | S, D | Bunch-Kaufman factorization A = U D U^T or L D L^T, D with 1x1 and 2x2 blocks | BunchKaufman‘s blocked kernel, with LAPACK’s pivot search |
xSYTRS | S, D | Solves A X = B with the factorization from xSYTRF | One block of the factorization at a time, without workspace, as reference LAPACK does | |
| Linear equations (§2.4.1), Hermitian indefinite matrix | xHETRF | C, Z | Bunch-Kaufman factorization A = U D U^H or L D L^H | BunchKaufman‘s blocked kernel, with LAPACK’s pivot search |
xHETRS | C, Z | Solves A X = B with the factorization from xHETRF | One block of the factorization at a time, without workspace, as reference LAPACK does | |
| Linear equations (§2.4.1), triangular matrix | xTRTRS | S, D, C, Z | Solves op(A) X = B, checking for a zero diagonal entry | Triangular solves |
xTRTRI | S, D, C, Z | inv(A) in place | TriangularView::inverseInPlace() | |
| Orthogonal factorizations (§2.4.2) | xGEQRF | S, D, C, Z | QR factorization A = Q R, Q as Householder reflectors | HouseholderQR's blocked kernel |
xORGQR, xUNGQR | S, D (ORGQR); C, Z (UNGQR) | Forms the leading columns of Q | Block Householder kernels | |
xORMQR, xUNMQR | S, D (ORMQR); C, Z (UNMQR) | Q C, Q^H C, C Q or C Q^H | Block Householder kernels |
Of §2.4.2 the library has only the QR factorization. It has no routines from §2.4.3 through §2.4.9, which cover generalized orthogonal factorizations, the symmetric, nonsymmetric and generalized eigenproblems, the SVD, and the generalized SVD.
The Users' Guide indexes auxiliary routines alphabetically. They are grouped here by purpose.
| Purpose | Routine | Precisions | Computes |
|---|---|---|---|
| Householder reflectors | xLARFG | S, D, C, Z | An elementary reflector H with H^H [α; x] = [β; 0], β real |
xLARF | S, D, C, Z | H C or C H for H = I - τ v v^H | |
xLARFT | S, D, C, Z | The triangular factor T of a block reflector H = I - V T V^H | |
xLARFB | S, D, C, Z | H C, H^H C, C H or C H^H for a block reflector H | |
| Triangular products | xLAUUM | S, D, C, Z | U U^H or L^H L in place, keeping a complex diagonal real |
| Matrix scanning | ILAxLR, ILAxLC | S, D, C, Z | Index of the last nonzero row or column |
| Scalar arithmetic | xLAPY2, xLAPY3 | S, D | sqrt(x^2 + y^2) and sqrt(x^2 + y^2 + z^2) without unnecessary overflow |
xLADIV | S, D, C, Z | Complex division without unnecessary overflow. S and D pass real and imaginary parts as separate arguments. | |
| Vector operations | xLACGV | C, Z | Conjugates a vector |
| Machine parameters | xLAMCH | S, D | Floating-point parameters: machine epsilon, safe minimum, ... |
xLAMC3 | S, D | a + b, forced through memory | |
| Version | ILAVER | – | The reference LAPACK release that the routines follow, 3.12.1 |
| Timing | SECOND, DSECND | – | Process CPU time in seconds |
Except for xLAUUM, which shares its kernel with LLT::inverse(), these routines are written directly to the reference LAPACK specification rather than built on Eigen's decompositions. The Householder routines support every combination of SIDE, TRANS, DIRECT and STOREV.
lapack_routines and lapack_wrappers, built with Eigen‘s other tests (EIGEN_BUILD_TESTING), check Eigen’s routines directly from C++ and need no Fortran compiler. lapack_wrappers adds what reference LAPACK's tests leave out, such as NaN and infinite input, arguments left untouched when INFO > 0 and the pivots reference LAPACK chooses; lapack_wrappers_ilp64 runs it against the ILP64 library.
The optional numerical tests (EIGEN_ENABLE_LAPACK_TESTS) require a Fortran compiler. CMake downloads the unmodified reference LAPACK release that CMakeLists.txt pins by version and SHA-256 hash.
The tests run reference LAPACK‘s own drivers on every input that reference LAPACK’s TESTING/CMakeLists.txt registers. They also run testing/[sdcz]test_large.in, which repeat the linear-equation paths that reach Eigen‘s routines at sizes above Eigen’s blocking thresholds; the reference inputs stop at N = 50. The drivers link Eigen's BLAS and LAPACK libraries. Each routine that eigen_lapack.def does not export comes from the reference sources, built into the test-only eigen_lapack_reference library, which is never installed. LAPACK_Test_Symbols checks the split: Eigen defines every routine the .def file lists, defines no Fortran-callable routine it omits, and shares none with the reference library. On ELF platforms it also checks that the shared library exports every listed routine. buildtests_lapack builds the drivers and the lapack_* C++ tests, and buildtests_blas the tests under blas/testing.
The tests and their summary run through CMake/CTest without Python. LAPACK_Test_Summary waits for the drivers and combines their output files into TESTING/testing_results.txt in the LAPACK build directory. For each output it counts numerical errors and other errors (illegal-argument, error-exit and INFO diagnostics). It fails when an output reports more of either than testing_allowed_failures.txt allows, which is none for an output the file does not list. It also fails when an expected output is missing, when no numerical tests were analyzed, and when an entry of the file names no output. TESTING/testing_failures.txt records the observed counts in the file's format. Selecting LAPACK_Test_Summary alone also runs its drivers through a CTest fixture. If a driver fails to execute successfully, CTest skips the summary.
Balancing tests contribute their example counts and fail on nonzero INFO/ILO error counts or non-finite maximum errors. Their finite maximum errors remain in the combined report; these drivers do not specify a pass/fail threshold.
The allowed counts are those of the test:linux:lapack CI job. Other compilers, flags and architectures round differently and fail a different set, mostly the eigenvalue tests that compare results computed with and without eigenvectors bit for bit (#3220). To check such a configuration, set EIGEN_LAPACK_TEST_ALLOWED_FAILURES to a file of its own, or to an empty string to allow no failures. A change that alters the job‘s counts on purpose updates the file’s entries from the job's testing_failures.txt artifact.