Debian Codegraph @

packages/anasazi/doc/TSQR/test/Tsqr_TestCombine.txt

raw
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.