  ***************************************************************************
  * All the software  contained in this library  is protected by copyright. *
  * Permission  to use, copy, modify, and  distribute this software for any *
  * purpose without fee is hereby granted, provided that this entire notice *
  * is included  in all copies  of any software which is or includes a copy *
  * or modification  of this software  and in all copies  of the supporting *
  * documentation for such software.                                        *
  ***************************************************************************
  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
  * WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
  * MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
  * NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
  * MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
  * USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
  ***************************************************************************
  * ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
  * ABOVE STATEMENT.                                                        *
  ***************************************************************************

   AUTHORS:

       Tsung-Lin Lee
       National Sun Yat-sen University, Taiwan
       Email: leetsung@math.nsysu.edu.tw

       Tien-Yien Li
       Michigan State University, USA
       Email: li@math.msu.edu

       Zhonggang Zeng
       Northeastern Illinois University, USA
       Email: zzeng@neiu.edu

   REFERENCE:

       RankRev: a Matlab package for computing the numerical rank and
       updating/downdating
       NUMERICAL ALGORITHMS, 77 (2018), PP. 559-576
       DOI: https://doi.org/10.1007/s11075-017-0328-7

   SOFTWARE REVISION DATE:

       V1.0, December 2016

   SOFTWARE LANGUAGE:

       MATLAB 8.2 (R2013b)


======================================================================
SOFTWARE
======================================================================

This package provides a set of Matlab functions to compute the numerical
rank and numerical subspaces of a matrix, along with updating/downdating
capabilities for making adjustment to the results when a row or column
is inserted/deleted. The package and the underlying algorithms are
accurate, reliable, and more efficient than the singular value
decomposition, when the matrix is of low rank or low nullity.
See the help page of each function for the calling syntax.


======================================================================
PACKAGE
======================================================================

The main directory contains the following files

README.txt               : This file
NumericalRank.m          : Compute the numerical rank of a matrix
NumericalRankUpdate.m    : Update the numerical rank of an inserted matrix
NumericalRankDowndate.m  : Downdate the numerical rank of a deleted matrix
testsuite/               : Directory containing the scripts for numerical
                           experiments

The following files are in directory testsuite/

hhnois.m                 : Construct a high rank matrix with high noise level
hmnois.m                 : Construct a high rank matrix with median noise level
hlnois.m                 : Construct a high rank matrix with low noise level
hrowup01.m               : Construct a high rank matrix for row updating with
                           increasing numerical ranks
hrowup02.m               : Construct a high rank matrix for row updating
                           without changing numerical ranks
hcolup01.m               : Construct a high rank matrix for column updating
                           with increasing numerical ranks
hcolup02.m               : Construct a high rank matrix for column updating
                           without changing numerical ranks
hrowdw01.m               : Construct a high rank matrix for row downdating with
                           decreasing numerical ranks
hrowdw02.m               : Construct a high rank matrix for row downdating
                           without changing numerical ranks
hcoldw01.m               : Construct a high rank matrix for column downdating
                           with decreasing numerical ranks
hcoldw02.m               : Construct a high rank matrix for column downdating
                           without changing numerical ranks
lhnois.m                 : Construct a low rank matrix with high noise level
lmnois.m                 : Construct a low rank matrix with median noise level
llnois.m                 : Construct a low rank matrix with low noise level
lrowup01.m               : Construct a low rank matrix for row updating with
                           increasing numerical ranks
lrowup02.m               : Construct a low rank matrix for row updating without
                           changing numerical ranks
lcolup01.m               : Construct a low rank matrix for column updating with
                           increasing numerical ranks
lcolup02.m               : Construct a low rank matrix for column updating
                           without changing numerical ranks
lrowdw01.m               : Construct a low rank matrix for row downdating with
                           decreasing numerical ranks
lrowdw02.m               : Construct a low rank matrix for row downdating
                           without changing numerical ranks
lcoldw01.m               : Construct a low rank matrix for column downdating
                           with decreasing numerical ranks
lcoldw02.m               : Construct a low rank matrix for column downdating
                           without changing numerical ranks
nogap.m                  : Construct a matrix whose singular values are
                           steadily decaying
imagemx.m                : Construct an image matrix from a graphics file
cranfield.m              : Construct a 3000x1400 term-by-document matrix from
                           CRANFIELD
syl_gen.m                : Construct a Sylvester matrix of two polynomials with
                           perturbation
Demo_Rank.m              : Demonstrate the usage of NumericalRank.m
Demo_Update.m            : Demonstrate the usage of NumericalRankUpdate.m
Demo_Downdate.m          : Demonstrate the usage of NumericalRankDowndate.m
Demo_Nogap.m             : Demonstrate the computation of the low rank
                           approximation
Demo_Imagemx.m           : Demonstrate the computation of the numerical rank
                           for image matrix
Demo_Cranfield.m         : Demonstrate the computation of the numerical rank
                           for term-by-document matrix
Demo_Sylvester.m         : Demonstrate the computation of the numerical rank
                           for Sylvester matrix
image01.jpg              : the JPG file of a fingerprint
image02.jpg              : the JPG file of a cat
image03.jpg              : the JPG file of a basketball


======================================================================
HOW TO INSTALL
======================================================================

Unpack the archive file. The directory RankRev will be created with all
the needed files inside. Add the directory RankRev to the path in
Matlab, either using the menus or the "addpath" command.


======================================================================
NUMERICAL TESTS
======================================================================

Go to directory testsuite/ and run: Demo_Rank.m, Demo_Update.m,
Demo_Downdate.m, Demo_Nogap, Demo_Imagemx.m, Demo_Cranfield.m,
Demo_Sylvester.m.


