1function [ number_fail, SJid_fail ] = test_spqr_rank (ids, figures)
2%TEST_SPQR_RANK extensive functionality test of spqr_rank functions
3% Returns the number of failures and, optionally, a list of matrices where
4% failure occurred.  The first argument can be a negative scalar
5% -k, in which case the k smallest matrices in the SJ Collection
6% are tested.  Otherwise, the first argument gives a list of matrix IDs
7% (as defined by SJget) that are used for the tests. If the optional second
8% parameter is zero no plots are produced, if the second parameter is 1 then
9% runs which produce no figures and which produce one figure are carried out
10% and if the second parameter is 2 then runs producing zero, one and four
11% figures (illustrating numerical ranks, null space accuracy, basic solutions,
12% and psuedoinverse solutions) are carried out. The last option is the default
13% option. It can be slower than runs with figures = 0 or 1.
14%
15% Example
16%
17%   test_spqr_rank ;            % test with 100 smallest sample matrices
18%   test_spqr_rank (-200) ;     % test with 200 smallest sample matrices
19%   test_spqr_rank (-5, 0) ;    % test with 5 matrices, and do not plot anything
20%
21%   test_spqr_rank (list) ;     % run tests with a set of matrices.  Each
22%                               % matrix is defined by an ID by SJget, and
23%                               % 'list' is a vector of matrix IDs to test with.
24%
25% See also demo_spqr_rank, test_spqr_coverage
26
27% Copyright 2012, Leslie Foster and Timothy A Davis
28
29% Potential run times:
30%        test_spqr_rank can require half an hour
31%        test_spqr_rank(-200) can require 1.5 hours
32%        test_spqr_rank(-200,1) can require an hour
33%        test_spqr_rank(-400,0) can require ten hours
34
35if (nargin < 1)
36    ids = -100 ;
37end
38if (isscalar (ids) && ids < 0)
39    nsamples_run = -ids ;
40else
41    nsamples_run = length (ids) ;
42end
43
44if (nargin < 2)
45    figures = 2 ;
46end
47
48nfail = 0 ;
49
50%-------------------------------------------------------------------------------
51% extensive tests
52%-------------------------------------------------------------------------------
53
54ncases = 0 ;
55cnt_fail = 0 ;
56SJid_fail = [ ] ;
57for figures_to_plot = 0:figures
58   demo_opts.figures = figures_to_plot ;
59   if figures_to_plot == 2
60       null_spaces_limits = 1:2 ; %for figures_to_plot=2, null_spaces>0 required
61   else
62       null_spaces_limits = 0:2 ;
63   end
64   for repeatable = 0:1
65       demo_opts.repeatable = repeatable;
66       for null_spaces = null_spaces_limits
67          demo_opts.null_spaces = null_spaces ;
68          for start_with_A_transpose = 0:1
69             demo_opts.start_with_A_transpose = start_with_A_transpose ;
70             for implicit_null_space_basis = 0:1
71               demo_opts.implicit_null_space_basis = implicit_null_space_basis ;
72               for nsvals = [1 3]
73                  demo_opts.nsvals = nsvals ;
74                  if (nsamples_run == 1)
75                      demo_opts.doprint = -1 ;
76                  else
77                      demo_opts.doprint = 0 ;
78                      fprintf (['\nTest %4d matrices, figures: %d null ' ...
79                      'spaces: %d A_trans: %d implicit: %d repeatable: %d ' ...
80                      'nsvals: %d\n'], nsamples_run, figures_to_plot, ...
81                      null_spaces, start_with_A_transpose, ...
82                      implicit_null_space_basis, repeatable, nsvals) ;
83                  end
84                  demo_opts.tol_norm_type = 0 ; % fixed at 0 to reduce cases
85                  [nfail_run, SJid_fail_run] = demo_spqr_rank (ids, demo_opts) ;
86                  nfail = nfail + nfail_run ;
87                  ncases = ncases + nsamples_run * 4 ;  % 4 for four methods
88                  if nfail_run > 0
89                     SJid_fail = union(SJid_fail, SJid_fail_run) ;
90                     cnt_fail = cnt_fail + 1;
91                     % To save statistics files in (rare) case of failure
92                     % in files with names demo_spqr_rank_failure_(#).mat
93                     % uncomment the following four lines:
94                     %dest = ['''demo_spqr_rank_failure_',int2str(cnt_fail),...
95                     %    '.mat'')'] ;
96                     %com = ['copyfile(''save_samples_demo_spqr_rank.mat'',',...
97                     %    dest] ;
98                     %eval( com ) ;
99                  end
100               end
101            end
102          end
103      end
104   end
105end
106
107if (nsamples_run > 1 || nfail > 0)
108    fprintf (['\nTests complete.  Total number of failures: %d for %d ' ...
109    'matrix / option choices.\n'], nfail, ncases) ;
110    if ( nfail > 0 )
111       disp (['Failures for matrices with SJid = ', int2str(SJid_fail),'.']) ;
112    end
113end
114
115if nargout > 0
116    number_fail = nfail ;
117end
118
119