GNU Octave  4.0.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
spparms.cc
Go to the documentation of this file.
1 /*
2 
3 Copyright (C) 2004-2015 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 the
10 Free Software Foundation; either version 3 of the License, or (at your
11 option) any later version.
12 
13 Octave is distributed in the hope that it will be useful, but WITHOUT
14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 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 <http://www.gnu.org/licenses/>.
21 
22 */
23 
24 #ifdef 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 "gripes.h"
33 
34 #include "oct-spparms.h"
35 
36 DEFUN (spparms, args, nargout,
37  "-*- texinfo -*-\n\
38 @deftypefn {Built-in Function} { } spparms ()\n\
39 @deftypefnx {Built-in Function} {@var{vals} =} spparms ()\n\
40 @deftypefnx {Built-in Function} {[@var{keys}, @var{vals}] =} spparms ()\n\
41 @deftypefnx {Built-in Function} {@var{val} =} spparms (@var{key})\n\
42 @deftypefnx {Built-in Function} { } spparms (@var{vals})\n\
43 @deftypefnx {Built-in Function} { } spparms (\"default\")\n\
44 @deftypefnx {Built-in Function} { } spparms (\"tight\")\n\
45 @deftypefnx {Built-in Function} { } spparms (@var{key}, @var{val})\n\
46 Query or set the parameters used by the sparse solvers and factorization\n\
47 functions.\n\
48 \n\
49 The first four calls above get information about the current settings, while\n\
50 the others change the current settings. The parameters are stored as pairs\n\
51 of keys and values, where the values are all floats and the keys are one of\n\
52 the following strings:\n\
53 \n\
54 @table @samp\n\
55 @item spumoni\n\
56 Printing level of debugging information of the solvers (default 0)\n\
57 \n\
58 @item ths_rel\n\
59 Included for compatibility. Not used. (default 1)\n\
60 \n\
61 @item ths_abs\n\
62 Included for compatibility. Not used. (default 1)\n\
63 \n\
64 @item exact_d\n\
65 Included for compatibility. Not used. (default 0)\n\
66 \n\
67 @item supernd\n\
68 Included for compatibility. Not used. (default 3)\n\
69 \n\
70 @item rreduce\n\
71 Included for compatibility. Not used. (default 3)\n\
72 \n\
73 @item wh_frac\n\
74 Included for compatibility. Not used. (default 0.5)\n\
75 \n\
76 @item autommd\n\
77 Flag whether the LU/QR and the '\\' and '/' operators will automatically\n\
78 use the sparsity preserving mmd functions (default 1)\n\
79 \n\
80 @item autoamd\n\
81 Flag whether the LU and the '\\' and '/' operators will automatically\n\
82 use the sparsity preserving amd functions (default 1)\n\
83 \n\
84 @item piv_tol\n\
85 The pivot tolerance of the @sc{umfpack} solvers (default 0.1)\n\
86 \n\
87 @item sym_tol\n\
88 The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001)\n\
89 \n\
90 @item bandden\n\
91 The density of nonzero elements in a banded matrix before it is treated\n\
92 by the @sc{lapack} banded solvers (default 0.5)\n\
93 \n\
94 @item umfpack\n\
95 Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\\' and\n\
96 '/' operations (default 1)\n\
97 @end table\n\
98 \n\
99 The value of individual keys can be set with\n\
100 @code{spparms (@var{key}, @var{val})}.\n\
101 The default values can be restored with the special keyword\n\
102 @qcode{\"default\"}. The special keyword @qcode{\"tight\"} can be used to\n\
103 set the mmd solvers to attempt a sparser solution at the potential cost of\n\
104 longer running time.\n\
105 @seealso{chol, colamd, lu, qr, symamd}\n\
106 @end deftypefn")
107 {
108  octave_value_list retval;
109  int nargin = args.length ();
110 
111  if (nargin == 0)
112  {
113  if (nargout == 0)
115  else if (nargout == 1)
116  retval(0) = octave_sparse_params::get_vals ();
117  else if (nargout == 2)
118  {
119  retval(1) = octave_sparse_params::get_vals ();
120  retval(0) = octave_sparse_params::get_keys ();
121  }
122  else
123  error ("spparms: too many output arguments");
124  }
125  else if (nargin == 1)
126  {
127  if (args(0).is_string ())
128  {
129  std::string str = args(0).string_value ();
130  int len = str.length ();
131  for (int i = 0; i < len; i++)
132  str[i] = tolower (str[i]);
133 
134  if (str == "defaults" || str == "default")
135  {
136  // FIXME: deprecated in 4.0, remove "defaults" for 4.4 release
137  static bool warned = false;
138  if (! warned && str == "defaults")
139  {
140  warning ("spparms: use \"default\" instead of \"defaults\"");
141  warned = true;
142  }
144  }
145  else if (str == "tight")
147  else
148  {
149  double val = octave_sparse_params::get_key (str);
150  if (xisnan (val))
151  error ("spparms: KEY not recognized");
152  else
153  retval(0) = val;
154  }
155  }
156  else
157  {
158  NDArray vals = args(0).array_value ();
159 
160  if (error_state)
161  error ("spparms: input must be a string or a vector");
162  else if (vals.numel () > OCTAVE_SPARSE_CONTROLS_SIZE)
163  error ("spparms: too many elements in vector VALS");
164  else
166  }
167  }
168  else if (nargin == 2)
169  {
170  if (args(0).is_string ())
171  {
172  std::string str = args(0).string_value ();
173 
174  double val = args(1).double_value ();
175 
176  if (error_state)
177  error ("spparms: second argument must be a real scalar");
178  else if (str == "umfpack")
179  warning ("spparms: request to disable umfpack solvers ignored");
180  else if (!octave_sparse_params::set_key (str, val))
181  error ("spparms: KEY not found");
182  }
183  else
184  error ("spparms: first argument must be a string");
185  }
186  else
187  error ("spparms: too many input arguments");
188 
189  return retval;
190 }
191 
192 /*
193 %!test
194 %! old_vals = spparms (); # save state
195 %! spparms ("default");
196 %! vals = spparms ();
197 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
198 %! [keys, vals] = spparms ();
199 %! assert (rows (keys), 13);
200 %! assert (keys(2,:), "ths_rel");
201 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
202 %! spparms ([3 2 1]);
203 %! assert (spparms ()(1:3), [3, 2, 1]');
204 %! assert (spparms ("ths_rel"), 2);
205 %! spparms ("exact_d", 5);
206 %! assert (spparms ("exact_d"), 5);
207 %! spparms (old_vals); # restore state
208 
209 %% Test input validation
210 %!error <too many input arguments> spparms (1, 2, 3)
211 %!error <too many output arguments> [x, y, z] = spparms ()
212 %!error <KEY not recognized> spparms ("UNKNOWN_KEY")
213 %!#error <input must be a string> spparms ({1, 2, 3})
214 %!error spparms ({1, 2, 3})
215 %!error <too many elements in vector VALS> spparms (ones (14, 1))
216 %!error <first argument must be a string> spparms (1, 1)
217 %!#error <second argument must be a real scalar> spparms ("ths_rel", "hello")
218 %!error spparms ("ths_rel", "hello")
219 %!error <KEY not found> spparms ("UNKNOWN_KEY", 1)
220 */
static string_vector get_keys(void)
Definition: oct-spparms.cc:75
bool xisnan(double x)
Definition: lo-mappers.cc:144
octave_idx_type numel(void) const
Number of elements in the array.
Definition: Array.h:275
#define OCTAVE_SPARSE_CONTROLS_SIZE
Definition: oct-spparms.h:36
octave_idx_type length(void) const
Definition: oct-obj.h:89
#define DEFUN(name, args_name, nargout_name, doc)
Definition: defun.h:44
void error(const char *fmt,...)
Definition: error.cc:476
static void print_info(std::ostream &os, const std::string &prefix)
Definition: oct-spparms.cc:111
static double get_key(const std::string &key)
Definition: oct-spparms.cc:99
static ColumnVector get_vals(void)
Definition: oct-spparms.cc:81
bool is_string(void) const
Definition: ov.h:562
int error_state
Definition: error.cc:101
static void defaults(void)
Definition: oct-spparms.cc:61
void warning(const char *fmt,...)
Definition: error.cc:681
#define octave_stdout
Definition: pager.h:144
static bool set_key(const std::string &key, const double &val)
Definition: oct-spparms.cc:93
static bool set_vals(const NDArray &vals)
Definition: oct-spparms.cc:87
static void tight(void)
Definition: oct-spparms.cc:68