home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 10 / 10.iso / l / l460 / 2.ddi / SPARFUN.DI$ / SPPARMS.M < prev    next >
Encoding:
Text File  |  1993-03-07  |  7.6 KB  |  231 lines
  1. function [return1,return2] = spparms(arg1,arg2)
  2. %SPPARMS Set parameters for sparse matrix routines.
  3. %
  4. %    SPPARMS('key',value) sets one or more of the "tunable" parameters 
  5. %    used in the sparse linear equation operators, \ and /, and the
  6. %    minimum degree orderings, COLMMD and SYMMMD.
  7. %
  8. %    SPPARMS, by itself, prints a description of the current settings.
  9. %
  10. %    If no input argument is present, values = SPPARMS returns a
  11. %    vector whose components give the current settings.
  12. %    [keys,values] = SPPARMS returns that vector, and also returns
  13. %    a character matrix whose rows are the keywords for the parameters.
  14. %
  15. %    SPPARMS(values), with no output argument, sets all the parameters
  16. %    to the values specified by the argument vector.
  17. %
  18. %    value = SPPARMS('key') returns the current setting of one parameter.
  19. %
  20. %    SPPARMS('default') sets all the parameters to their default settings.
  21. %    SPPARMS('tight') sets the minimum degree ordering parameters to their 
  22. %    "tight" settings, which may lead to orderings with less fill-in, but 
  23. %    which makes the ordering functions themselves use more execution time.
  24. %
  25. %    The parameters with the default and "tight" values are:
  26. %
  27. %                     keyword       default       tight
  28. %
  29. %       values(1)     'spumoni'      0
  30. %       values(2)     'thr_rel'      1.1          1.0
  31. %       values(3)     'thr_abs'      1.0          0.0
  32. %       values(4)     'exact_d'      0            1
  33. %       values(5)     'supernd'      3            1
  34. %       values(6)     'rreduce'      3            1
  35. %       values(7)     'wh_frac'      0.5          0.5
  36. %       values(8)     'autommd'      1            
  37. %       values(9)     'aug_rel'      0.001      
  38. %       values(10)    'aug_abs'      0   
  39. %
  40. %    The meanings of the parameters are
  41. %
  42. %       spumoni:  The Sparse Monitor Flag controls diagnostic output;
  43. %                 0 means none, 1 means some, 2 means too much.
  44. %       thr_rel,
  45. %       thr_abs:  Minimum degree threshold is thr_rel*mindegree + thr_abs.
  46. %       exact_d:  Nonzero to use exact degrees in minimum degree,
  47. %                 Zero to use approximate degrees.
  48. %       supernd:  If > 0, MMD amalgamates supernodes every supernd stages.
  49. %       rreduce:  If > 0, MMD does row reduction every rreduce stages.
  50. %       wh_frac:  Rows with density > wh_frac are ignored in COLMMD.
  51. %       autommd:  Nonzero to use minimum degree orderings with \ and /.
  52. %       aug_rel,
  53. %       aug_abs: Residual scaling parameter for augmented equations is
  54. %                aug_rel*max(max(abs(A))) + aug_abs.
  55. %                For example, aug_rel = 0, aug_abs = 1 puts an unscaled
  56. %                identity matrix in the (1,1) block of the augmented matrix.
  57. %               
  58. %    See also COLMMD, SYMMMD, SPAUGMENT.
  59.  
  60. %    John Gilbert and Cleve Moler, 7-21-91.
  61. %    Copyright (c) 1984-93 by The MathWorks, Inc.
  62.  
  63. % The following are "constants".
  64.  
  65. allkeys = ['spumoni'
  66.            'thr_rel'
  67.            'thr_abs'
  68.            'exact_d'
  69.            'supernd'
  70.            'rreduce'
  71.            'wh_frac'
  72.            'autommd'
  73.            'aug_rel'
  74.            'aug_abs' ];
  75. nparms = size(allkeys,1);
  76. spuparmrange = 1:1;   % Which parameters pertain to SPUMONI?
  77. mmdparmrange = 2:7;   % Which parameters pertain to minimum degree?
  78. bslparmrange = 8:10;  % Which parameters pertain to sparse backslash?
  79. defaultparms = [0 1.1 1.0 0 3 3 0.5 1 0.001 0]';
  80. tightmmdparms   = [1.0 0.0 1 1 1 0.5]';
  81.  
  82. % First find out what the current parameters are.
  83.  
  84. oldvalues = zeros(nparms,1);
  85. oldvalues(spuparmrange) = sparsfun('spumoni');
  86. oldvalues(mmdparmrange) = sparsfun('mmdset');
  87. oldvalues(bslparmrange) = sparsfun('slashset');
  88.  
  89. % No input args, no output args:  Describe current settings.
  90. if nargin == 0 & nargout == 0
  91.     a = num2str(oldvalues(1));
  92.     if oldvalues(1) 
  93.         disp(['SParse MONItor output level ' a '.'])
  94.     else 
  95.         disp(['No SParse MONItor output.'])
  96.     end
  97.     a = num2str(oldvalues(2));
  98.     b = num2str(oldvalues(3));
  99.         disp(['mmd: threshold = ' a ' * mindegree + ' b ','])
  100.     if oldvalues(4) 
  101.         disp(['     using exact degrees in A''*A,'])
  102.     else 
  103.         disp(['     using approximate degrees in A''*A,'])
  104.     end
  105.     s = int2str(oldvalues(5));
  106.     if oldvalues(5)
  107.         disp(['     supernode amalgamation every ' s ' stages,'])
  108.     else
  109.         disp(['     no supernode amalgamation,'])
  110.     end
  111.     s = int2str(oldvalues(6));
  112.     if oldvalues(6) 
  113.         disp(['     row reduction every ' s ' stages,'])
  114.     else
  115.         disp(['     no row reduction,'])
  116.     end
  117.     a = num2str(100*oldvalues(7));
  118.     if oldvalues(7)
  119.         disp(['     withhold rows at least ' a '% dense in colmmd.'])
  120.     else
  121.         disp(['     no row withholding in colmmd.'])
  122.     end
  123.     if oldvalues(8)
  124.         disp(['Minimum degree orderings used by \ and /.'])
  125.     else
  126.         disp(['No automatic orderings used by \ and /.'])
  127.     end
  128.     a = num2str(oldvalues(9));
  129.     b = num2str(oldvalues(10));
  130.     if oldvalues(9) & oldvalues(10)
  131.         disp(['Residual scale parameter = ' a ' * max(abs(A)) + ' b '.']);
  132.     elseif oldvalues(9)
  133.         disp(['Residual scale parameter = ' a ' * max(abs(A)).']);
  134.     else
  135.         disp(['Residual scale parameter = ' b '.'])
  136.     end
  137.     return;
  138.  
  139. % No input args, one or two output args:  Return current settings.
  140. elseif nargin == 0 & nargout > 0
  141.     if nargout <= 1
  142.         return1 = oldvalues;
  143.     else
  144.         return1 = allkeys;
  145.         return2 = oldvalues;
  146.     end
  147.     return;
  148.  
  149. % One input arg of suitable size:  Reset all parameters.
  150. elseif nargin == 1 & max(size(arg1)) == nparms & min(size(arg1)) == 1
  151.     if nargout > 0 
  152.         error ('Too many output arguments.')
  153.     end
  154.     sparsfun('spumoni',arg1(spuparmrange));
  155.     sparsfun('mmdset',arg1(mmdparmrange));
  156.     sparsfun('slashset',arg1(bslparmrange));
  157.     return;
  158.  
  159. % Input arg 'tight':  Reset minimum degree parameters.
  160. elseif nargin == 1 & strcmp(lower(arg1),'tight')
  161.     if nargout > 0
  162.         error ('Too many output arguments.')
  163.     end
  164.     newvalues = oldvalues;
  165.     newvalues(mmdparmrange) = tightmmdparms;
  166.     spparms(newvalues);
  167.     return;
  168.  
  169. % Input arg 'default':  Reset all parameters.
  170. elseif nargin == 1 & strcmp(lower(arg1),'default')
  171.     if nargout > 0
  172.         error ('Too many output arguments.')
  173.     end
  174.     spparms(defaultparms);
  175.     return;
  176.  
  177. % One input arg:  Return one current setting.
  178. elseif (nargin == 1)
  179.     if ~isstr(arg1)
  180.         error ('Option argument must be a string.')
  181.     end
  182.     if nargout > 1
  183.         error ('Too many output arguments')
  184.     end
  185.     if size(arg1,1) > 1
  186.         error ('Must query one parameter by keyword at a time')
  187.     end
  188.     key = lower(arg1);
  189.     for i = 1:nparms
  190.         if strcmp (key, allkeys(i,:))
  191.             return1 = oldvalues(i);
  192.             return;
  193.         end
  194.     end
  195.     error (['Unknown keyword parameter "' key '"']);
  196.  
  197. % Two input args:  Reset some parameters.
  198. elseif (nargin == 2)
  199.     if ~isstr(arg1)
  200.         error ('Option argument must be a string.')
  201.     end
  202.     if nargout > 0
  203.         error ('Too many output arguments.')
  204.     end
  205.     if size(arg1,1) ~= max(size(arg2))
  206.         error ('Number of parameters and keywords must agree')
  207.     end
  208.     newvalues = oldvalues;
  209.     for k = 1:size(arg1,1)
  210.         key = lower(arg1(k,:));
  211.         value = arg2(k);
  212.         found = 0;
  213.         for i = 1:nparms
  214.             if strcmp (key, allkeys(i,:))
  215.                 newvalues(i) = value;
  216.                 found = 1;
  217.                 break
  218.             end
  219.         end
  220.         if ~found
  221.             disp (['Warning:  Unknown keyword parameter "' key '" in SPPARMS.']);
  222.         end
  223.     end
  224.     spparms(newvalues);
  225.     return;
  226.    
  227. % No error is possible here.
  228. else
  229.     error ('Invalid arguments')
  230. end
  231.