Merge pull request #584 from DrTimothyAldenDavis/dev2

SPQR documentation (issue #536)

SPQR/Doc/spqr_user_guide.tex

@@ -533,11 +533,14 @@ \subsection{C++ Syntax}
 
     \item \verb'SuiteSparseQR_qmult': provides the same function as
     \verb'spqr_qmult' in the MATLAB interface, computing
-    \verb"Q'*x", \verb"Q*x", \verb"x*Q'", or \verb"x*Q".
-    It uses either a QR factorization
-    in MATLAB-style sparse matrix format, or the QR factorization object
-    returned by \newline \verb'SuiteSparseQR_factorize' or
-    \verb'SuiteSparseQR_numeric'.
+    \verb"y=Q'*x", \verb"y=Q*x", \verb"y=x*Q'", or \verb"y=x*Q".
+    It uses the efficient Householder reprensentation of \verb'Q', which
+    represents a square orthonormal matrix computed by
+    \verb'SuiteSparseQR_factorize' or \verb'SuiteSparseQR_numeric'.  The
+    Householder representation always represents a square orthonormal matrix,
+    regardless of whether \verb'Q' is a full or economy factor.
+    \verb'SuiteSparseQR_qmult' applies this square matrix to compute its result
+    \verb'y'.
 
     \item \verb'SuiteSparseQR_min2norm': finds the minimum 2-norm solution to
     an underdetermined linear system.

SPQR/MATLAB/spqr.m

@@ -92,7 +92,9 @@
 %   [Q,R,P]=spqr(A) where spqr finds P and Q is discarded instead). 'matrix'
 %   returns Q as a sparse matrix where A=Q*R or A*P=Q*R.  'Householder' returns
 %   Q as a struct containing the Householder reflections applied to A to obtain
-%   R, resulting in a far sparser Q than the 'matrix' option.  
+%   R, resulting in a far sparser Q than the 'matrix' option.  When returned as
+%   a struct, Q always represents a square orthonormal matrix, regardless of
+%   opts.econ.
 %
 %   opts.permutation: a string describing how P is to be returned.  The default
 %   is 'matrix', so that A*P=Q*R.  'vector' gives A(:,P)=Q*R instead.

SPQR/MATLAB/spqr_qmult.m

@@ -7,6 +7,11 @@
 %   method = 2: Y = X*Q'
 %   method = 3: Y = X*Q
 %
+% where Q is the struct from [Q,R,E] = spqr (A,opts) with
+% opts.Q = 'Householder'.  The struct Q always represents a square
+% orthonormal matrix, regardless of opts.econ.  spqr_qmult applies this
+% square matrix to compute Y.
+%
 % Example:
 %   These two examples both compute the min-norm solution to an
 %   under determined system, but the latter is much more efficient: