readme.txt for spqrZ and lusolZ (spqrZv, spqrZt and lusolZv, lusolZt)

The software for spqrZ, lusolZ is provided by SOL, Stanford University
under the terms of the OSI Common Public License (CPL)
   http://www.opensource.org/licenses/cpl1.0.php
or the BSD License
   http://www.opensource.org/licenses/bsd-license.php

Authors: Nick Henderson, San Kim, Ding Ma, Michael Saunders, Yuekai Sun,
         Ronan Fleming, Ines Thiele,
         Stanford University and University of Luxembourg.

Also needed:
SuiteSparseQR: http://faulty.cse.tam.edu/davis/suitesparse.html
SPQR:          Part of SuiteSparseQR
LUSOL:         http://stanford.edu/group/SOL/lusol/

05 Mar 2014: First version of lusolAZ, lusolAtZ.
10 Nov 2015: First version ready for distribution.
20 Dec 2015: Changed names to lusolZv, lusolZt.
09 Feb 2016: Added spqrZv, spqrZt.
16 Feb 2016: Current version.

Please send comments to
             Michael Saunders, SOL, Stanford University
             saunders@stanford.edu  650-723-1875
-----------------------------------------------------------------------------
The SPQR nullspace routines compute a nullspace operator Z for the
transpose of a sparse matrix S (such that S'*Z = 0), and enable
computation of products of the form w = Z*v and s = Z'*t.
   spqrZv.m computes Z from QR factors of S.
   spqrZt.m computes Z from QR factors of S'.
The QR factors are computed by the Matlab interface to SPQR
as in testspqrZ.m.  For example,
    [Q,R,P,info] = spqr(A,struct('Q','Householder'));
    Z.Q    = Q;
    Z.R    = R;
    Z.P    = P;
    Z.info = info; 
factorizes S = QR with the specified options.  Similarly for S' = QR.   
The sparsity of Q and R may be significantly different in each case.

The LUSOL nullspace routines compute a nullspace operator Z for the
transpose of a sparse matrix S (such that S'*Z = 0), and enable
computation of products of the form w = Z*v and s = Z'*t.
   lusolZv.m computes Z from LU factors of S.
   lusolZt.m computes Z from LU factors of S'.
The LU factors are computed by the Matlab interface to LUSOL
as in testlusolZ.m.  For example,
    options        = lusol();
    options.Ltol1  = factol;
    options.nzinit = round(20*nnz(A)/factol);
    options.pivot  = 'TPP';
    Z     = lusolZ(S,trans,options);
factorizes S = LU with the specified options.  Similarly for S' = LU.   
The sparsity of L and U may be significantly different in each case.

The files are organized into the following folders:

  code  Solver files: spqrZv.m,  spqrZt.m
                      lusolZv.m, lusolZt.m, lusolU.m
        Test files:   testspqrZ.m, testlusolZ.m
  data  model_*.mat   used by testspqrZ.m, testlusolZ.m
  doc   results_testspqrZ.txt, results_testlusolZ.txt

To test spqrZv, spqrZt, lusolZv, lusolZt:
Assume the SPQR, LUSOL nullspace routines are in matlab/lusolZ.
Assume they will be tested in matlab/lusolZtest.
   cd      ~/matlab/lusolZtest
   addpath ~/matlab/lusolZ
   addpath ~/matlab/lusolZ/code
   addpath ~/matlab/lusolZ/data
   testspqrZ(0)      % tests w = Z*v,  where S'*Z = 0 and S  = QR.
   testspqrZ(1)      % tests s = Z'*t, where S'*Z = 0 and S' = QR.
   testlusolZ(0)     % tests w = Z*v,  where S'*Z = 0 and S  = LU.
   testlusolZ(1)     % tests s = Z'*t, where S'*Z = 0 and S' = LU.
