Mercurial > octave-antonio

comparison scripts/sparse/pcg.m @ 20164:df437a52bcaf stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Update more docstrings to have one sentence summary as first line. Reviewed miscellaneous, sparse, strings in scripts directory. * scripts/miscellaneous/bzip2.m, scripts/miscellaneous/citation.m, scripts/miscellaneous/compare_versions.m, scripts/miscellaneous/computer.m, scripts/miscellaneous/debug.m, scripts/miscellaneous/dir.m, scripts/miscellaneous/edit.m, scripts/miscellaneous/error_ids.m, scripts/miscellaneous/fileattrib.m, scripts/miscellaneous/fullfile.m, scripts/miscellaneous/genvarname.m, scripts/miscellaneous/gzip.m, scripts/miscellaneous/mkoctfile.m, scripts/miscellaneous/news.m, scripts/miscellaneous/open.m, scripts/miscellaneous/parseparams.m, scripts/miscellaneous/recycle.m, scripts/miscellaneous/run.m, scripts/miscellaneous/swapbytes.m, scripts/miscellaneous/tar.m, scripts/miscellaneous/tmpnam.m, scripts/miscellaneous/unpack.m, scripts/miscellaneous/what.m, scripts/sparse/bicg.m, scripts/sparse/bicgstab.m, scripts/sparse/cgs.m, scripts/sparse/colperm.m, scripts/sparse/eigs.m, scripts/sparse/etreeplot.m, scripts/sparse/gmres.m, scripts/sparse/gplot.m, scripts/sparse/ichol.m, scripts/sparse/ilu.m, scripts/sparse/pcg.m, scripts/sparse/pcr.m, scripts/sparse/qmr.m, scripts/sparse/spaugment.m, scripts/sparse/spconvert.m, scripts/sparse/spdiags.m, scripts/sparse/spfun.m, scripts/sparse/spones.m, scripts/sparse/sprandsym.m, scripts/sparse/spstats.m, scripts/sparse/spy.m, scripts/sparse/svds.m, scripts/sparse/treelayout.m, scripts/sparse/treeplot.m, scripts/strings/base2dec.m, scripts/strings/bin2dec.m, scripts/strings/blanks.m, scripts/strings/cstrcat.m, scripts/strings/deblank.m, scripts/strings/dec2base.m, scripts/strings/dec2bin.m, scripts/strings/dec2hex.m, scripts/strings/findstr.m, scripts/strings/hex2dec.m, scripts/strings/index.m, scripts/strings/isletter.m, scripts/strings/isstrprop.m, scripts/strings/mat2str.m, scripts/strings/ostrsplit.m, scripts/strings/regexptranslate.m, scripts/strings/rindex.m, scripts/strings/str2num.m, scripts/strings/strcat.m, scripts/strings/strchr.m, scripts/strings/strjoin.m, scripts/strings/strjust.m, scripts/strings/strmatch.m, scripts/strings/strsplit.m, scripts/strings/strtok.m, scripts/strings/strtrim.m, scripts/strings/strtrunc.m, scripts/strings/substr.m, scripts/strings/untabify.m, scripts/time/datenum.m: Update more docstrings to have one sentence summary as first line.
author Rik <rik@octave.org>
date Mon, 04 May 2015 14:22:02 -0700
parents 9fc020886ae9
children
comparison
equal deleted inserted replaced
20163:075a5e2e1ba5 20164:df437a52bcaf
19 ## -*- texinfo -*- 19 ## -*- texinfo -*-
20 ## @deftypefn {Function File} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{}) 20 ## @deftypefn {Function File} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{})
21 ## @deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@dots{}) 21 ## @deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@dots{})
22 ## 22 ##
23 ## Solve the linear system of equations @w{@code{@var{A} * @var{x} = @var{b}}} 23 ## Solve the linear system of equations @w{@code{@var{A} * @var{x} = @var{b}}}
24 ## by means of the Preconditioned Conjugate Gradient iterative method. The 24 ## by means of the Preconditioned Conjugate Gradient iterative method.
25 ## input arguments are 25 ##
26 ## The input arguments are
26 ## 27 ##
27 ## @itemize 28 ## @itemize
28 ## @item 29 ## @item
29 ## @var{A} can be either a square (preferably sparse) matrix or a function 30 ## @var{A} can be either a square (preferably sparse) matrix or a function
30 ## handle, inline function or string containing the name of a function which 31 ## handle, inline function or string containing the name of a function which
50 ## @item 51 ## @item
51 ## @var{m} = @var{m1} * @var{m2} is the (left) preconditioning matrix, so that 52 ## @var{m} = @var{m1} * @var{m2} is the (left) preconditioning matrix, so that
52 ## the iteration is (theoretically) equivalent to solving by @code{pcg} 53 ## the iteration is (theoretically) equivalent to solving by @code{pcg}
53 ## @w{@code{@var{P} * @var{x} = @var{m} \ @var{b}}}, with 54 ## @w{@code{@var{P} * @var{x} = @var{m} \ @var{b}}}, with
54 ## @w{@code{@var{P} = @var{m} \ @var{A}}}. 55 ## @w{@code{@var{P} = @var{m} \ @var{A}}}.
55 ## Note that a proper choice of the preconditioner may dramatically 56 ## Note that a proper choice of the preconditioner may dramatically improve
56 ## improve the overall performance of the method. Instead of matrices 57 ## the overall performance of the method. Instead of matrices @var{m1} and
57 ## @var{m1} and @var{m2}, the user may pass two functions which return 58 ## @var{m2}, the user may pass two functions which return the results of
58 ## the results of applying the inverse of @var{m1} and @var{m2} to 59 ## applying the inverse of @var{m1} and @var{m2} to a vector (usually this is
59 ## a vector (usually this is the preferred way of using the preconditioner). 60 ## the preferred way of using the preconditioner). If @var{m1} is omitted or
60 ## If @var{m1} is omitted or empty @code{[]} then no preconditioning is 61 ## empty @code{[]} then no preconditioning is applied. If @var{m2} is
61 ## applied. If @var{m2} is omitted, @var{m} = @var{m1} will be used as 62 ## omitted, @var{m} = @var{m1} will be used as a preconditioner.
62 ## a preconditioner.
63 ## 63 ##
64 ## @item 64 ## @item
65 ## @var{x0} is the initial guess. If @var{x0} is omitted or empty then the 65 ## @var{x0} is the initial guess. If @var{x0} is omitted or empty then the
66 ## function sets @var{x0} to a zero vector by default. 66 ## function sets @var{x0} to a zero vector by default.
67 ## @end itemize 67 ## @end itemize
152 ## @example 152 ## @example
153 ## x = pcg (A, b, 1.e-6, 500, l*u) 153 ## x = pcg (A, b, 1.e-6, 500, l*u)
154 ## @end example 154 ## @end example
155 ## 155 ##
156 ## @sc{Example 4:} @code{pcg} with a preconditioner: @var{l} * @var{u}. 156 ## @sc{Example 4:} @code{pcg} with a preconditioner: @var{l} * @var{u}.
157 ## Faster than @sc{Example 3} since lower and upper triangular matrices 157 ## Faster than @sc{Example 3} since lower and upper triangular matrices are
158 ## are easier to invert 158 ## easier to invert
159 ## 159 ##
160 ## @example 160 ## @example
161 ## x = pcg (A, b, 1.e-6, 500, l, u) 161 ## x = pcg (A, b, 1.e-6, 500, l, u)
162 ## @end example 162 ## @end example
163 ## 163 ##
164 ## @sc{Example 5:} Preconditioned iteration, with full diagnostics. The 164 ## @sc{Example 5:} Preconditioned iteration, with full diagnostics. The
165 ## preconditioner (quite strange, because even the original matrix 165 ## preconditioner (quite strange, because even the original matrix @var{A} is
166 ## @var{A} is trivial) is defined as a function 166 ## trivial) is defined as a function
167 ## 167 ##
168 ## @example 168 ## @example
169 ## @group 169 ## @group
170 ## function y = apply_m (x) 170 ## function y = apply_m (x)
171 ## k = floor (length (x) - 2); 171 ## k = floor (length (x) - 2);
177 ## pcg (A, b, [], [], "apply_m"); 177 ## pcg (A, b, [], [], "apply_m");
178 ## semilogy (1:iter+1, resvec); 178 ## semilogy (1:iter+1, resvec);
179 ## @end group 179 ## @end group
180 ## @end example 180 ## @end example
181 ## 181 ##
182 ## @sc{Example 6:} Finally, a preconditioner which depends on a 182 ## @sc{Example 6:} Finally, a preconditioner which depends on a parameter
183 ## parameter @var{k}. 183 ## @var{k}.
184 ## 184 ##
185 ## @example 185 ## @example
186 ## @group 186 ## @group
187 ## function y = apply_M (x, varargin) 187 ## function y = apply_M (x, varargin)
188 ## K = varargin@{1@}; 188 ## K = varargin@{1@};