GNU Octave  4.4.1
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
spparms.cc
Go to the documentation of this file.
1 /*
2 
3 Copyright (C) 2004-2018 David Bateman
4 Copyright (C) 1998-2004 Andy Adler
5 
6 This file is part of Octave.
7 
8 Octave is free software: you can redistribute it and/or modify it
9 under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
12 
13 Octave is distributed in the hope that it will be useful, but
14 WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17 
18 You should have received a copy of the GNU General Public License
19 along with Octave; see the file COPYING. If not, see
20 <https://www.gnu.org/licenses/>.
21 
22 */
23 
24 #if defined (HAVE_CONFIG_H)
25 # include "config.h"
26 #endif
27 
28 #include "defun.h"
29 #include "ov.h"
30 #include "pager.h"
31 #include "error.h"
32 #include "errwarn.h"
33 
34 #include "oct-spparms.h"
35 
36 DEFUN (spparms, args, nargout,
37  doc: /* -*- texinfo -*-
38 @deftypefn {} { } spparms ()
39 @deftypefnx {} {@var{vals} =} spparms ()
40 @deftypefnx {} {[@var{keys}, @var{vals}] =} spparms ()
41 @deftypefnx {} {@var{val} =} spparms (@var{key})
42 @deftypefnx {} { } spparms (@var{vals})
43 @deftypefnx {} { } spparms ("default")
44 @deftypefnx {} { } spparms ("tight")
45 @deftypefnx {} { } spparms (@var{key}, @var{val})
46 Query or set the parameters used by the sparse solvers and factorization
47 functions.
48 
49 The first four calls above get information about the current settings, while
50 the others change the current settings. The parameters are stored as pairs
51 of keys and values, where the values are all floats and the keys are one of
52 the following strings:
53 
54 @table @samp
55 @item spumoni
56 Printing level of debugging information of the solvers (default 0)
57 
58 @item ths_rel
59 Included for compatibility. Not used. (default 1)
60 
61 @item ths_abs
62 Included for compatibility. Not used. (default 1)
63 
64 @item exact_d
65 Included for compatibility. Not used. (default 0)
66 
67 @item supernd
68 Included for compatibility. Not used. (default 3)
69 
70 @item rreduce
71 Included for compatibility. Not used. (default 3)
72 
73 @item wh_frac
74 Included for compatibility. Not used. (default 0.5)
75 
76 @item autommd
77 Flag whether the LU/QR and the '\' and '/' operators will automatically
78 use the sparsity preserving mmd functions (default 1)
79 
80 @item autoamd
81 Flag whether the LU and the '\' and '/' operators will automatically
82 use the sparsity preserving amd functions (default 1)
83 
84 @item piv_tol
85 The pivot tolerance of the @sc{umfpack} solvers (default 0.1)
86 
87 @item sym_tol
88 The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001)
89 
90 @item bandden
91 The density of nonzero elements in a banded matrix before it is treated
92 by the @sc{lapack} banded solvers (default 0.5)
93 
94 @item umfpack
95 Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\' and
96 '/' operations (default 1)
97 @end table
98 
99 The value of individual keys can be set with
100 @code{spparms (@var{key}, @var{val})}.
101 The default values can be restored with the special keyword
102 @qcode{"default"}. The special keyword @qcode{"tight"} can be used to
103 set the mmd solvers to attempt a sparser solution at the potential cost of
104 longer running time.
105 @seealso{chol, colamd, lu, qr, symamd}
106 @end deftypefn */)
107 {
109  int nargin = args.length ();
110 
111  if (nargin == 0)
112  {
113  if (nargout == 0)
115  else if (nargout == 1)
117  else if (nargout == 2)
120  else
121  error ("spparms: too many output arguments");
122  }
123  else if (nargin == 1)
124  {
125  if (args(0).is_string ())
126  {
127  std::string str = args(0).string_value ();
128  int len = str.length ();
129  for (int i = 0; i < len; i++)
130  str[i] = tolower (str[i]);
131 
132  if (str == "default")
134  else if (str == "tight")
136  else
137  {
139  if (octave::math::isnan (val))
140  error ("spparms: KEY not recognized");
141 
142  retval = ovl (val);
143  }
144  }
145  else
146  {
147  NDArray vals = args(0).xarray_value ("spparms: input must be a string or a vector");
148  if (vals.numel () > OCTAVE_SPARSE_CONTROLS_SIZE)
149  error ("spparms: too many elements in vector VALS");
150 
152  }
153  }
154  else if (nargin == 2)
155  {
156  std::string str = args(0).xstring_value ("spparms: first argument must be a string");
157 
158  double val = args(1).xdouble_value ("spparms: second argument must be a real scalar");
159 
160  if (str == "umfpack")
161  warning ("spparms: request to disable umfpack solvers ignored");
162  else if (! octave_sparse_params::set_key (str, val))
163  error ("spparms: KEY not found");
164  }
165  else
166  error ("spparms: too many input arguments");
167 
168  return retval;
169 }
170 
171 /*
172 %!test
173 %! old_vals = spparms (); # save state
174 %! spparms ("default");
175 %! vals = spparms ();
176 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
177 %! [keys, vals] = spparms ();
178 %! assert (rows (keys), 13);
179 %! assert (keys(2,:), "ths_rel");
180 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
181 %! spparms ([3 2 1]);
182 %! assert (spparms ()(1:3), [3, 2, 1]');
183 %! assert (spparms ("ths_rel"), 2);
184 %! spparms ("exact_d", 5);
185 %! assert (spparms ("exact_d"), 5);
186 %! spparms (old_vals); # restore state
187 
188 ## Test input validation
189 %!error <too many input arguments> spparms (1, 2, 3)
190 %!error <too many output arguments> [x, y, z] = spparms ()
191 %!error <KEY not recognized> spparms ("UNKNOWN_KEY")
192 %!#error <input must be a string> spparms ({1, 2, 3})
193 %!error spparms ({1, 2, 3})
194 %!error <too many elements in vector VALS> spparms (ones (14, 1))
195 %!error <first argument must be a string> spparms (1, 1)
196 %!#error <second argument must be a real scalar> spparms ("ths_rel", "hello")
197 %!error spparms ("ths_rel", "hello")
198 %!error <KEY not found> spparms ("UNKNOWN_KEY", 1)
199 */
static string_vector get_keys(void)
Definition: oct-spparms.cc:73
identity matrix If supplied two scalar respectively For allows like xample val
Definition: data.cc:4986
#define OCTAVE_SPARSE_CONTROLS_SIZE
Definition: oct-spparms.h:37
bool isnan(bool)
Definition: lo-mappers.h:187
#define DEFUN(name, args_name, nargout_name, doc)
Macro to define a builtin function.
Definition: defun.h:53
void error(const char *fmt,...)
Definition: error.cc:578
static void print_info(std::ostream &os, const std::string &prefix)
Definition: oct-spparms.cc:110
static double get_key(const std::string &key)
Definition: oct-spparms.cc:97
static ColumnVector get_vals(void)
Definition: oct-spparms.cc:79
OCTAVE_EXPORT octave_value_list return the number of command line arguments passed to Octave If called with the optional argument the function xample nargout(@histc)
Definition: ov-usr-fcn.cc:997
std::string str
Definition: hash.cc:118
octave_value retval
Definition: data.cc:6246
static void defaults(void)
Definition: oct-spparms.cc:59
void warning(const char *fmt,...)
Definition: error.cc:801
#define octave_stdout
Definition: pager.h:174
OCTAVE_EXPORT octave_value_list isa nd deftypefn *return ovl(args(0).isinteger())
args.length() nargin
Definition: file-io.cc:589
for i
Definition: data.cc:5264
static bool set_key(const std::string &key, const double &val)
Definition: oct-spparms.cc:91
bool is_string(void) const
Definition: ov.h:577
static bool set_vals(const NDArray &vals)
Definition: oct-spparms.cc:85
octave_idx_type numel(void) const
Number of elements in the array.
Definition: Array.h:366
octave_idx_type length(void) const
static void tight(void)
Definition: oct-spparms.cc:66
If this string is the system will ring the terminal sometimes it is useful to be able to print the original representation of the string
Definition: utils.cc:888