| 1 |
This program tests TSQR::Combine, which implements the computational |
| 2 |
kernels used to construct all TSQR variants. TSQR (Tall Skinny QR) |
| 3 |
computes the QR factorization of a tall and skinny matrix (with many |
| 4 |
more rows than columns) distributed in a block row layout across one |
| 5 |
or more processes. TSQR::Combine implements the following kernels: |
| 6 |
|
| 7 |
* factor_pair: compute QR factorization in place of $[R_1; R_2]$, |
| 8 |
where $R_1$ and $R_2$ are both square upper triangular matrices |
| 9 |
|
| 10 |
* apply_pair: apply the $Q$ factor computed by factor_pair and stored |
| 11 |
implicitly, to a matrix $C$ |
| 12 |
|
| 13 |
* factor_inner: compute QR factorization in place of $[R; A]$, where |
| 14 |
$R$ is square and upper triangular, and $A$ is a general dense |
| 15 |
matrix |
| 16 |
|
| 17 |
* apply_inner: apply the $Q$ factor computed by factor_inner and |
| 18 |
stored implicitly, to a matrix $C$ |
| 19 |
|
| 20 |
TSQR::Combine also has the factor_first and apply_first methods, but |
| 21 |
these are just wrappers around the LAPACK routines _GEQRF(P) resp. |
| 22 |
_ORMQR. (The underscore _ can be one of the following letters: S, D, |
| 23 |
C, Z. It represents the type of the input Scalar data.) This program |
| 24 |
does not test these methods. |
| 25 |
|
| 26 |
This program will test all four of the kernels mentioned above, for |
| 27 |
two different "back-end" implementations of TSQR::Combine: |
| 28 |
CombineNative, which is a native C++ implementation that works |
| 29 |
entirely in place, and CombineDefault, which is a wrapper around |
| 30 |
LAPACK routines and works by copying data in and out of internally |
| 31 |
allocated and maintained scratch space. If you build Trilinos with |
| 32 |
Fortran support and enable the CMake Boolean option |
| 33 |
KokkosClassic_ENABLE_TSQR_Fortran, a third back-end implementation, CombineFortran, |
| 34 |
will also be tested. It is a Fortran 2003 version of CombineNative. |
| 35 |
(Note that you will need a Fortran 2003 - compliant compiler in order |
| 36 |
to build CombineFortran.) |
| 37 |
|
| 38 |
By default, TSQR::Combine will only be tested with real arithmetic |
| 39 |
Scalar types (currently, float and double, corresponding to LAPACK's |
| 40 |
"S" resp. "D" data types). If you build Trilinos with complex |
| 41 |
arithmetic support (Teuchos_ENABLE_COMPLEX), and invoke this program |
| 42 |
with the "--complex" option, complex arithmetic Scalar types will also |
| 43 |
be tested (currently, std::complex<float> and std::complex<double>, |
| 44 |
corresponding to LAPACK's "C" resp. "Z" data types). |
| 45 |
|
| 46 |
This program tests the four kernels in pairs: (factor_pair, |
| 47 |
apply_pair), and (factor_inner, apply_inner). It does so by computing |
| 48 |
a QR factorization of a test problem using factor_*, and then using |
| 49 |
apply_* to compute the explicit version of the Q factor (by applying |
| 50 |
the implicitly stored $Q$ factor to columns of the identity matrix). |
| 51 |
That means it is only testing applying $Q$, and not $Q^T$ (or $Q^H$, |
| 52 |
the conjugate transpose, in the complex-arithmetic case). This |
| 53 |
exercises the typical use case of TSQR in iterative methods, in which |
| 54 |
the explicit $Q$ factor is desired in order to compute a |
| 55 |
rank-revealing decomposition and possibly also replace the null space |
| 56 |
basis vectors with random data. |
| 57 |
|
| 58 |
This program can test accuracy ("--verify") or performance |
| 59 |
("--benchmark"). For accuracy tests, it computes both the |
| 60 |
orthogonality $\| I - Q^* Q \|_F$ and the residual $\| A - Q R \|_F$. |
| 61 |
For performance tests, it repeats the test with the same data for a |
| 62 |
number of trials (specified by the "--ntrials=<n>" command-line |
| 63 |
option). This ensures that the test is performed with warm cache, so |
| 64 |
that kernel performance rather than memory bandwidth is being |
| 65 |
measured. |