Mercurial > octave
annotate src/DLD-FUNCTIONS/spparms.cc @ 11553:01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Use same variable names in error() strings and in documentation.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Sun, 16 Jan 2011 22:13:23 -0800 |
parents | fd0a3ac60b0e |
children | 12df7854fa7c |
rev | line source |
---|---|
5164 | 1 /* |
2 | |
11523 | 3 Copyright (C) 2004-2011 David Bateman |
4 Copyright (C) 1998-2004 Andy Adler | |
5164 | 5 |
7016 | 6 This file is part of Octave. |
7 | |
8 Octave is free software; you can redistribute it and/or modify it | |
5164 | 9 under the terms of the GNU General Public License as published by the |
7016 | 10 Free Software Foundation; either version 3 of the License, or (at your |
11 option) any later version. | |
5164 | 12 |
7016 | 13 Octave is distributed in the hope that it will be useful, but WITHOUT |
5164 | 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 | |
7016 | 19 along with Octave; see the file COPYING. If not, see |
20 <http://www.gnu.org/licenses/>. | |
5164 | 21 |
22 */ | |
23 | |
24 #ifdef HAVE_CONFIG_H | |
25 #include <config.h> | |
26 #endif | |
27 | |
28 #include "defun-dld.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_DLD (spparms, args, nargout, | |
37 "-*- texinfo -*-\n\ | |
10840 | 38 @deftypefn {Loadable Function} { } spparms ()\n\ |
5164 | 39 @deftypefnx {Loadable Function} {@var{vals} =} spparms ()\n\ |
40 @deftypefnx {Loadable Function} {[@var{keys}, @var{vals}] =} spparms ()\n\ | |
41 @deftypefnx {Loadable Function} {@var{val} =} spparms (@var{key})\n\ | |
42 @deftypefnx {Loadable Function} { } spparms (@var{vals})\n\ | |
43 @deftypefnx {Loadable Function} { } spparms ('defaults')\n\ | |
44 @deftypefnx {Loadable Function} { } spparms ('tight')\n\ | |
45 @deftypefnx {Loadable Function} { } spparms (@var{key}, @var{val})\n\ | |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
46 Query or set the parameters used by the sparse solvers and factorization\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
47 functions. The first four calls above get information about the current\n\ |
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
48 settings, while the others change the current settings. The parameters are\n\ |
5164 | 49 stored as pairs of keys and values, where the values are all floats and the\n\ |
8828 | 50 keys are one of the following strings:\n\ |
5164 | 51 \n\ |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
52 @table @samp\n\ |
5164 | 53 @item spumoni\n\ |
54 Printing level of debugging information of the solvers (default 0)\n\ | |
10840 | 55 \n\ |
5164 | 56 @item ths_rel\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
57 Included for compatibility. Not used. (default 1)\n\ |
10840 | 58 \n\ |
5164 | 59 @item ths_abs\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
60 Included for compatibility. Not used. (default 1)\n\ |
10840 | 61 \n\ |
5164 | 62 @item exact_d\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
63 Included for compatibility. Not used. (default 0)\n\ |
10840 | 64 \n\ |
5164 | 65 @item supernd\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
66 Included for compatibility. Not used. (default 3)\n\ |
10840 | 67 \n\ |
5164 | 68 @item rreduce\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
69 Included for compatibility. Not used. (default 3)\n\ |
10840 | 70 \n\ |
5164 | 71 @item wh_frac\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
72 Included for compatibility. Not used. (default 0.5)\n\ |
10840 | 73 \n\ |
5164 | 74 @item autommd\n\ |
75 Flag whether the LU/QR and the '\\' and '/' operators will automatically\n\ | |
76 use the sparsity preserving mmd functions (default 1)\n\ | |
10840 | 77 \n\ |
5164 | 78 @item autoamd\n\ |
79 Flag whether the LU and the '\\' and '/' operators will automatically\n\ | |
80 use the sparsity preserving amd functions (default 1)\n\ | |
10840 | 81 \n\ |
5164 | 82 @item piv_tol\n\ |
10711
fbd7843974fa
Periodic grammar check of documentation files to ensure common format.
Rik <octave@nomad.inbox5.com>
parents:
10155
diff
changeset
|
83 The pivot tolerance of the @sc{umfpack} solvers (default 0.1)\n\ |
10840 | 84 \n\ |
7515
f3c00dc0912b
Eliminate the rest of the dispatched sparse functions
David Bateman <dbateman@free.fr>
parents:
7017
diff
changeset
|
85 @item sym_tol\n\ |
10711
fbd7843974fa
Periodic grammar check of documentation files to ensure common format.
Rik <octave@nomad.inbox5.com>
parents:
10155
diff
changeset
|
86 The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001)\n\ |
10840 | 87 \n\ |
5164 | 88 @item bandden\n\ |
7515
f3c00dc0912b
Eliminate the rest of the dispatched sparse functions
David Bateman <dbateman@free.fr>
parents:
7017
diff
changeset
|
89 The density of non-zero elements in a banded matrix before it is treated\n\ |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9064
diff
changeset
|
90 by the @sc{lapack} banded solvers (default 0.5)\n\ |
10840 | 91 \n\ |
5164 | 92 @item umfpack\n\ |
10711
fbd7843974fa
Periodic grammar check of documentation files to ensure common format.
Rik <octave@nomad.inbox5.com>
parents:
10155
diff
changeset
|
93 Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\\' and\n\ |
5164 | 94 '/' operations (default 1)\n\ |
8828 | 95 @end table\n\ |
5164 | 96 \n\ |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
97 The value of individual keys can be set with\n\ |
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
98 @code{spparms (@var{key}, @var{val})}.\n\ |
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
99 The default values can be restored with the special keyword\n\ |
9064
7c02ec148a3c
Check grammar on all .cc files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
100 'defaults'. The special keyword 'tight' can be used to set the mmd solvers\n\ |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
101 to attempt a sparser solution at the potential cost of longer running\n\ |
5164 | 102 time.\n\ |
103 @end deftypefn") | |
104 { | |
105 octave_value_list retval; | |
106 int nargin = args.length (); | |
107 | |
108 if (nargin == 0) | |
109 { | |
110 if (nargout == 0) | |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
111 octave_sparse_params::print_info (octave_stdout, ""); |
5164 | 112 else if (nargout == 1) |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
113 retval(0) = octave_sparse_params::get_vals (); |
5164 | 114 else if (nargout == 2) |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
115 { |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
116 retval (0) = octave_sparse_params::get_keys (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
117 retval (1) = octave_sparse_params::get_vals (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
118 } |
5164 | 119 else |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
120 error ("spparms: too many output arguments"); |
5164 | 121 } |
122 else if (nargin == 1) | |
123 { | |
124 if (args(0).is_string ()) | |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
125 { |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
126 std::string str = args(0).string_value (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
127 int len = str.length (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
128 for (int i = 0; i < len; i++) |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
129 str [i] = tolower (str [i]); |
5164 | 130 |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
131 if (str == "defaults") |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
132 octave_sparse_params::defaults (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
133 else if (str == "tight") |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
134 octave_sparse_params::tight (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
135 else |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
136 { |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
137 double val = octave_sparse_params::get_key (str); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
138 if (xisnan (val)) |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
139 error ("spparams: KEY not recognized"); |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
140 else |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
141 retval (0) = val; |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
142 } |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
143 } |
5164 | 144 else |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
145 { |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
146 NDArray vals = args(0).array_value (); |
5164 | 147 |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
148 if (error_state) |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
149 error ("spparms: input must be a string or a vector"); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
150 else if (vals.numel () > OCTAVE_SPARSE_CONTROLS_SIZE) |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
151 error ("spparams: too many elements in vector VALS"); |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
152 else |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
153 octave_sparse_params::set_vals (vals); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
154 } |
5164 | 155 } |
156 else if (nargin == 2) | |
157 { | |
158 if (args(0).is_string ()) | |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
159 { |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
160 std::string str = args(0).string_value (); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
161 |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
162 double val = args(1).double_value (); |
5164 | 163 |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
164 if (error_state) |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
165 error ("spparms: second argument must be a real scalar"); |
5164 | 166 else if (str == "umfpack") |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
167 warning ("spparms: request to disable umfpack solvers ignored"); |
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
168 else if (!octave_sparse_params::set_key (str, val)) |
11553
01f703952eff
Improve docstrings for functions in DLD-FUNCTIONS directory.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
169 error ("spparms: KEY not found"); |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
170 } |
5164 | 171 else |
10154
40dfc0c99116
DLD-FUNCTIONS/*.cc: untabify
John W. Eaton <jwe@octave.org>
parents:
9209
diff
changeset
|
172 error ("spparms: first argument must be a string"); |
5164 | 173 } |
174 else | |
175 error ("spparms: too many input arguments"); | |
176 | |
177 return retval; | |
178 } |