File README for covlsqr.m.

28 May 2007: Original version by Inga Schierle
             email: inga.schierle@gmx.de
             University of Heidelberg, IWR 
             (Interdisciplinary Center for Scientific Computing)

24 Dec 2010: Updated to describe the test programs more.
             Michael Saunders, saunders@stanford.edu.
-----------------------------------------------------------------------------

Purpose:
covlsqr solves sparse linear equations or least-squares problems Ax ~= b
in the same way as LSQR (Paige and Saunders 1982).  It allows A to be an
explicit sparse matrix or an operator for forming A*v and A'*u.

Special feature:
covlsqr can estimate any principal submatrix of the associated covariance
matrix inv(A'A).  It was developed to estimate the parameter covariance
matrix for large parameter estimation problems with nonlinear equality
constraints, as described in Technical Report SOL-2009-1 (see below).

Files:
covlsqr.m      The main solver.
covlsqrtest.m  A simple test program.
mytestLSQR.m   A more elaborate test program that implements the
               method described in Report SOL-2009-1.  It uses
               the following files:
                 myset.m          generates some test data
                 aprod.m          computes y = A*v or y = A'*v for some A
                 J1ZZTproduct.m   computes y = J1*v (= J1*Z*Z'*v)
                                       or  y = Z*Z'*J1'*v
                                  using covlsqr.
mytestQR.m     Same as mytestLSQR but uses direct QR factors of
               certain matrices rather than covlsqr.
mytest.m       runs both mytestQR and mytestLSQR
               and checks that their results agree.
SOL-2009-1.pdf is the following report:
               Ekaterina Kostina, Michael A. Saunders, and Inga Schierle,
               Computation of covariance matrices for constrained
               parameter estimation problems using LSQR,
               Report SOL 2009-1, Systems Optimization Laboratory,
               Stanford University, Stanford, CA 94305-4026.

To test covlsqr:
   covlsqrtest( 10, 10, 0   );   (say)
   covlsqrtest( 20, 10, 0   );
   covlsqrtest( 20, 10, 0.1 );
   mytest

