blob: 375c68d5089602e8a7a0603ca075a4ca1673aa32 [file] [view] [edit]
# 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](https://www.netlib.org/lapack/lug/), 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)
| 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:
- 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)
| 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.
### Auxiliary routines (Users' Guide, Index of Auxiliary Routines)
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`.
## 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](https://gitlab.com/libeigen/eigen/-/work_items/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.