GNU Octave  4.2.1
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-2017 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 #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)
116  retval = ovl (octave_sparse_params::get_vals ());
117  else if (nargout == 2)
118  retval = ovl (octave_sparse_params::get_keys (),
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 == "defaults" || str == "default")
133  {
134  // FIXME: deprecated in 4.0, remove "defaults" for 4.4 release
135  static bool warned = false;
136  if (! warned && str == "defaults")
137  {
138  warning ("spparms: use \"default\" instead of \"defaults\"");
139  warned = true;
140  }
142  }
143  else if (str == "tight")
145  else
146  {
147  double val = octave_sparse_params::get_key (str);
148  if (octave::math::isnan (val))
149  error ("spparms: KEY not recognized");
150 
151  retval = ovl (val);
152  }
153  }
154  else
155  {
156  NDArray vals = args(0).xarray_value ("spparms: input must be a string or a vector");
157  if (vals.numel () > OCTAVE_SPARSE_CONTROLS_SIZE)
158  error ("spparms: too many elements in vector VALS");
159 
161  }
162  }
163  else if (nargin == 2)
164  {
165  std::string str = args(0).xstring_value ("spparms: first argument must be a string");
166 
167  double val = args(1).xdouble_value ("spparms: second argument must be a real scalar");
168 
169  if (str == "umfpack")
170  warning ("spparms: request to disable umfpack solvers ignored");
171  else if (! octave_sparse_params::set_key (str, val))
172  error ("spparms: KEY not found");
173  }
174  else
175  error ("spparms: too many input arguments");
176 
177  return retval;
178 }
179 
180 /*
181 %!test
182 %! old_vals = spparms (); # save state
183 %! spparms ("default");
184 %! vals = spparms ();
185 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
186 %! [keys, vals] = spparms ();
187 %! assert (rows (keys), 13);
188 %! assert (keys(2,:), "ths_rel");
189 %! assert (vals, [0 1 1 0 3 3 0.5 1.0 1.0 0.1 0.5 1.0 0.001]');
190 %! spparms ([3 2 1]);
191 %! assert (spparms ()(1:3), [3, 2, 1]');
192 %! assert (spparms ("ths_rel"), 2);
193 %! spparms ("exact_d", 5);
194 %! assert (spparms ("exact_d"), 5);
195 %! spparms (old_vals); # restore state
196 
197 %% Test input validation
198 %!error <too many input arguments> spparms (1, 2, 3)
199 %!error <too many output arguments> [x, y, z] = spparms ()
200 %!error <KEY not recognized> spparms ("UNKNOWN_KEY")
201 %!#error <input must be a string> spparms ({1, 2, 3})
202 %!error spparms ({1, 2, 3})
203 %!error <too many elements in vector VALS> spparms (ones (14, 1))
204 %!error <first argument must be a string> spparms (1, 1)
205 %!#error <second argument must be a real scalar> spparms ("ths_rel", "hello")
206 %!error spparms ("ths_rel", "hello")
207 %!error <KEY not found> spparms ("UNKNOWN_KEY", 1)
208 */
static string_vector get_keys(void)
Definition: oct-spparms.cc:71
OCTAVE_EXPORT octave_value_list isa nd deftypefn *return ovl(args(0).is_integer_type())
octave_idx_type numel(void) const
Number of elements in the array.
Definition: Array.h:363
identity matrix If supplied two scalar respectively For allows like xample val
Definition: data.cc:5068
#define OCTAVE_SPARSE_CONTROLS_SIZE
Definition: oct-spparms.h:38
bool isnan(double x)
Definition: lo-mappers.cc:347
#define DEFUN(name, args_name, nargout_name, doc)
Definition: defun.h:46
void error(const char *fmt,...)
Definition: error.cc:570
static void print_info(std::ostream &os, const std::string &prefix)
Definition: oct-spparms.cc:108
static double get_key(const std::string &key)
Definition: oct-spparms.cc:95
static ColumnVector get_vals(void)
Definition: oct-spparms.cc:77
JNIEnv void * args
Definition: ov-java.cc:67
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:935
int nargin
Definition: graphics.cc:10115
bool is_string(void) const
Definition: ov.h:578
std::string str
Definition: hash.cc:118
octave_value retval
Definition: data.cc:6294
static void defaults(void)
Definition: oct-spparms.cc:57
void warning(const char *fmt,...)
Definition: error.cc:788
#define octave_stdout
Definition: pager.h:146
=val(i)}if ode{val(i)}occurs in table i
Definition: lookup.cc:239
static bool set_key(const std::string &key, const double &val)
Definition: oct-spparms.cc:89
static bool set_vals(const NDArray &vals)
Definition: oct-spparms.cc:83
static void tight(void)
Definition: oct-spparms.cc:64
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:854