tree: 4ce1495aeca518444531357633a8b5dffb56ebdd [search]
  1. testing/
  2. cholesky.inc
  3. CMakeLists.txt
  4. complex_double.cpp
  5. complex_single.cpp
  6. double.cpp
  7. dsecnd_INT_CPU_TIME.cpp
  8. eigen_lapack.def
  9. eigenvalues.inc
  10. householder.inc
  11. ilaver.cpp
  12. lapack.h
  13. lapack_common.h
  14. lapack_utils.h
  15. lu.inc
  16. qr.inc
  17. README.md
  18. second_INT_CPU_TIME.cpp
  19. single.cpp
  20. svd.inc
  21. testing_allowed_failures.txt
  22. testing_summary.cmake
  23. testing_symbols.cmake
  24. triangular.inc
  25. utilities.inc
lapack/README.md

Eigen's LAPACK library

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.

Interface

  • Symbols follow the Fortran 77 calling convention: a lowercase name with a trailing underscore (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.
  • In a routine with an 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.
  • Eigen's BLAS library provides an 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.
  • The driver routines allocate their own workspace. They use 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).

Building

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.

Routines

The tables follow the classification in Chapter 2 of the LAPACK Users' Guide, third edition:

  • A driver routine solves a complete problem.
  • A computational routine performs one step of a driver's work.
  • An auxiliary routine is a building block of the other two.

An x in a routine name stands for a precision prefix. The Precisions column lists the prefixes that exist:

  • S: real single.
  • D: real double.
  • C: complex single.
  • Z: complex double.

Driver routines (Users' Guide §2.3)

ProblemRoutinePrecisionsComputesImplemented with
Symmetric eigenproblem (SEP)xSYEVS, DAll eigenvalues and, optionally, the eigenvectors of a symmetric matrixSelfAdjointEigenSolver
xHEEVC, ZThe same for a Hermitian matrix; the imaginary part of its diagonal is ignoredSelfAdjointEigenSolver
Singular value decomposition (SVD)xGESVDS, D, C, ZA = U Σ V^H: the singular values and, optionally, the left and right singular vectorsJacobiSVD (two-sided Jacobi, not bidiagonal QR iteration)
xGESDDS, D, C, ZThe same, by divide and conquerBDCSVD

The library has no driver for any other problem class in §2.3:

  • Linear equations (xGESV, xPOSV, ...).
  • Linear least squares, and generalized linear least squares.
  • Nonsymmetric eigenproblems.
  • Generalized eigenvalue and singular value problems.

Computational routines (Users' Guide §2.4)

ProblemRoutinePrecisionsComputesImplemented with
Linear equations (§2.4.1), general matrixxGETRFS, D, C, ZLU factorization with partial pivoting, A = P L UPartialPivLU's blocked kernel
xGETRSS, D, C, ZSolves A X = B, A^T X = B or A^H X = B with the factors from xGETRFTriangular solves
xGETRIS, D, C, Zinv(A) = inv(U) inv(L) P^T from the factors of xGETRF, blocked over WORKxTRTRI and triangular solves
Linear equations (§2.4.1), symmetric or Hermitian positive definite matrixxPOTRFS, D, C, ZCholesky factorization, A = U^H U or A = L L^HLLT's blocked kernel
xPOTRSS, D, C, ZSolves A X = B with the factor from xPOTRFTriangular solves
xPOTRIS, D, C, Zinv(A) from the factor of xPOTRFxTRTRI, then xLAUUM
Linear equations (§2.4.1), symmetric or Hermitian positive semidefinite matrixxPSTRFS, D, C, ZCholesky factorization with complete pivoting, P^T A P = U^H U or L L^H, stopping at the numerical rankLDLT's panel kernel, pivoting on the largest diagonal entry
Linear equations (§2.4.1), symmetric indefinite matrixxSYTRFS, DBunch-Kaufman factorization A = U D U^T or L D L^T, D with 1x1 and 2x2 blocksBunchKaufman‘s blocked kernel, with LAPACK’s pivot search
xSYTRSS, DSolves A X = B with the factorization from xSYTRFOne block of the factorization at a time, without workspace, as reference LAPACK does
Linear equations (§2.4.1), Hermitian indefinite matrixxHETRFC, ZBunch-Kaufman factorization A = U D U^H or L D L^HBunchKaufman‘s blocked kernel, with LAPACK’s pivot search
xHETRSC, ZSolves A X = B with the factorization from xHETRFOne block of the factorization at a time, without workspace, as reference LAPACK does
Linear equations (§2.4.1), triangular matrixxTRTRSS, D, C, ZSolves op(A) X = B, checking for a zero diagonal entryTriangular solves
xTRTRIS, D, C, Zinv(A) in placeTriangularView::inverseInPlace()
Orthogonal factorizations (§2.4.2)xGEQRFS, D, C, ZQR factorization A = Q R, Q as Householder reflectorsHouseholderQR's blocked kernel
xORGQR, xUNGQRS, D (ORGQR); C, Z (UNGQR)Forms the leading columns of QBlock Householder kernels
xORMQR, xUNMQRS, D (ORMQR); C, Z (UNMQR)Q C, Q^H C, C Q or C Q^HBlock 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.

Auxiliary routines (Users' Guide, Index of Auxiliary Routines)

The Users' Guide indexes auxiliary routines alphabetically. They are grouped here by purpose.

PurposeRoutinePrecisionsComputes
Householder reflectorsxLARFGS, D, C, ZAn elementary reflector H with H^H [α; x] = [β; 0], β real
xLARFS, D, C, ZH C or C H for H = I - τ v v^H
xLARFTS, D, C, ZThe triangular factor T of a block reflector H = I - V T V^H
xLARFBS, D, C, ZH C, H^H C, C H or C H^H for a block reflector H
Triangular productsxLAUUMS, D, C, ZU U^H or L^H L in place, keeping a complex diagonal real
Matrix scanningILAxLR, ILAxLCS, D, C, ZIndex of the last nonzero row or column
Scalar arithmeticxLAPY2, xLAPY3S, Dsqrt(x^2 + y^2) and sqrt(x^2 + y^2 + z^2) without unnecessary overflow
xLADIVS, D, C, ZComplex division without unnecessary overflow. S and D pass real and imaginary parts as separate arguments.
Vector operationsxLACGVC, ZConjugates a vector
Machine parametersxLAMCHS, DFloating-point parameters: machine epsilon, safe minimum, ...
xLAMC3S, Da + b, forced through memory
VersionILAVER–The reference LAPACK release that the routines follow, 3.12.1
TimingSECOND, 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.

Tests

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.