Mercurial > hg > octave-lyh

comparison src/DLD-FUNCTIONS/luinc.cc @ 11553:01f703952eff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
11552:6b6e9051ecb8 11553:01f703952eff
37 #include "ov-re-sparse.h" 37 #include "ov-re-sparse.h"
38 #include "ov-cx-sparse.h" 38 #include "ov-cx-sparse.h"
39 39
40 DEFUN_DLD (luinc, args, nargout, 40 DEFUN_DLD (luinc, args, nargout,
41 "-*- texinfo -*-\n\ 41 "-*- texinfo -*-\n\
42 @deftypefn {Loadable Function} {[@var{l}, @var{u}, @var{p}, @var{q}] =} luinc (@var{a}, '0')\n\ 42 @deftypefn {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, '0')\n\
43 @deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{p}, @var{q}] =} luinc (@var{a}, @var{droptol})\n\ 43 @deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{droptol})\n\
44 @deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{p}, @var{q}] =} luinc (@var{a}, @var{opts})\n\ 44 @deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{opts})\n\
45 @cindex LU decomposition\n\ 45 @cindex LU decomposition\n\
46 Produce the incomplete LU factorization of the sparse matrix @var{a}.\n\ 46 Produce the incomplete LU factorization of the sparse matrix @var{A}.\n\
47 Two types of incomplete factorization are possible, and the type\n\ 47 Two types of incomplete factorization are possible, and the type\n\
48 is determined by the second argument to @dfn{luinc}.\n\ 48 is determined by the second argument to @code{luinc}.\n\
49 \n\ 49 \n\
50 Called with a second argument of '0', the zero-level incomplete\n\ 50 Called with a second argument of '0', the zero-level incomplete\n\
51 LU factorization is produced. This creates a factorization of @var{a}\n\ 51 LU@tie{}factorization is produced. This creates a factorization of @var{A}\n\
52 where the position of the non-zero arguments correspond to the same\n\ 52 where the position of the non-zero arguments correspond to the same\n\
53 positions as in the matrix @var{a}.\n\ 53 positions as in the matrix @var{A}.\n\
54 \n\ 54 \n\
55 Alternatively, the fill-in of the incomplete LU factorization can\n\ 55 Alternatively, the fill-in of the incomplete LU@tie{}factorization can\n\
56 be controlled through the variable @var{droptol} or the structure\n\ 56 be controlled through the variable @var{droptol} or the structure\n\
57 @var{opts}. The @sc{umfpack} multifrontal factorization code by Tim A.\n\ 57 @var{opts}. The @sc{umfpack} multifrontal factorization code by Tim A.\n\
58 Davis is used for the incomplete LU factorization, (availability\n\ 58 Davis is used for the incomplete LU@tie{}factorization, (availability\n\
59 @url{http://www.cise.ufl.edu/research/sparse/umfpack/})\n\ 59 @url{http://www.cise.ufl.edu/research/sparse/umfpack/})\n\
60 \n\ 60 \n\
61 @var{droptol} determines the values below which the values in the LU\n\ 61 @var{droptol} determines the values below which the values in the\n\
62 factorization are dropped and replaced by zero. It must be a positive\n\ 62 LU@tie{} factorization are dropped and replaced by zero. It must be a\n\
63 scalar, and any values in the factorization whose absolute value are\n\ 63 positive scalar, and any values in the factorization whose absolute value\n\
64 less than this value are dropped, expect if leaving them increase the\n\ 64 are less than this value are dropped, expect if leaving them increase the\n\
65 sparsity of the matrix. Setting @var{droptol} to zero results in a\n\ 65 sparsity of the matrix. Setting @var{droptol} to zero results in a complete\n\
66 complete LU factorization which is the default.\n\ 66 LU@tie{}factorization which is the default.\n\
67 \n\ 67 \n\
68 @var{opts} is a structure containing one or more of the fields\n\ 68 @var{opts} is a structure containing one or more of the fields\n\
69 \n\ 69 \n\
70 @table @code\n\ 70 @table @code\n\
71 @item droptol\n\ 71 @item droptol\n\
72 The drop tolerance as above. If @var{opts} only contains @code{droptol}\n\ 72 The drop tolerance as above. If @var{opts} only contains @code{droptol}\n\
73 then this is equivalent to using the variable @var{droptol}.\n\ 73 then this is equivalent to using the variable @var{droptol}.\n\
74 \n\ 74 \n\
75 @item milu\n\ 75 @item milu\n\
76 A logical variable flagging whether to use the modified incomplete LU\n\ 76 A logical variable flagging whether to use the modified incomplete\n\
77 factorization. In the case that @code{milu} is true, the dropped values\n\ 77 LU@tie{} factorization. In the case that @code{milu} is true, the dropped\n\
78 are subtracted from the diagonal of the matrix U of the factorization.\n\ 78 values are subtracted from the diagonal of the matrix @var{U} of the\n\
79 The default is @code{false}.\n\ 79 factorization. The default is @code{false}.\n\
80 \n\ 80 \n\
81 @item udiag\n\ 81 @item udiag\n\
82 A logical variable that flags whether zero elements on the diagonal of U\n\ 82 A logical variable that flags whether zero elements on the diagonal of\n\
83 should be replaced with @var{droptol} to attempt to avoid singular\n\ 83 @var{U} should be replaced with @var{droptol} to attempt to avoid singular\n\
84 factors. The default is @code{false}.\n\ 84 factors. The default is @code{false}.\n\
85 \n\ 85 \n\
86 @item thresh\n\ 86 @item thresh\n\
87 Defines the pivot threshold in the interval [0,1]. Values outside that\n\ 87 Defines the pivot threshold in the interval [0,1]. Values outside that\n\
88 range are ignored.\n\ 88 range are ignored.\n\
89 @end table\n\ 89 @end table\n\
90 \n\ 90 \n\
91 All other fields in @var{opts} are ignored. The outputs from @dfn{luinc}\n\ 91 All other fields in @var{opts} are ignored. The outputs from @code{luinc}\n\
92 are the same as for @dfn{lu}.\n\ 92 are the same as for @code{lu}.\n\
93 \n\ 93 \n\
94 Given the string argument 'vector', @dfn{luinc} returns the values of @var{p}\n\ 94 Given the string argument 'vector', @code{luinc} returns the values of\n\
95 @var{q} as vector values.\n\ 95 @var{p} @var{q} as vector values.\n\
96 @seealso{sparse, lu}\n\ 96 @seealso{sparse, lu}\n\
97 @end deftypefn") 97 @end deftypefn")
98 { 98 {
99 int nargin = args.length (); 99 int nargin = args.length ();
100 octave_value_list retval; 100 octave_value_list retval;
157 thresh.resize(1,2); 157 thresh.resize(1,2);
158 thresh(1) = thresh(0); 158 thresh(1) = thresh(0);
159 } 159 }
160 else if (thresh.nelem () != 2) 160 else if (thresh.nelem () != 2)
161 { 161 {
162 error ("luinc: expecting 2 element vector for thresh"); 162 error ("luinc: expecting 2-element vector for thresh");
163 return retval; 163 return retval;
164 } 164 }
165 } 165 }
166 } 166 }
167 else 167 else
168 { 168 {
169 error ("luinc: options argument must be a scalar structure"); 169 error ("luinc: OPTS must be a scalar structure");
170 return retval; 170 return retval;
171 } 171 }
172 } 172 }
173 else 173 else
174 droptol = args(1).double_value (); 174 droptol = args(1).double_value ();
355 break; 355 break;
356 } 356 }
357 } 357 }
358 } 358 }
359 else 359 else
360 error ("luinc: first argument must be sparse"); 360 error ("luinc: matrix A must be sparse");
361 } 361 }
362 } 362 }
363 363
364 return retval; 364 return retval;
365 } 365 }