changeset 19148:e278c939a419

Deprecate luinc. * NEWS: Announce deprecation * luinc.cc (F__luinc__): Rename luinc to internal function __luinc__. * scripts/deprecated/luinc.m: New m-file to issue deprecation warning. * scripts/deprecated/module.mk: Add luinc.m to build system. * sparse.txi: Remove function from manual. * pcg.m: Replace luinc example in docstring with ilu.
author Rik <rik@octave.org>
date Mon, 22 Sep 2014 20:19:01 -0700
parents 8b2a919d24bc
children 8b3b35fda568
files NEWS doc/interpreter/sparse.txi libinterp/corefcn/luinc.cc scripts/deprecated/luinc.m scripts/deprecated/module.mk scripts/sparse/pcg.m
diffstat 6 files changed, 98 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Sun Sep 21 23:27:27 2014 +0100
+++ b/NEWS	Mon Sep 22 20:19:01 2014 -0700
@@ -106,6 +106,7 @@
       flipdim            | flip
       fmod               | rem
       fnmatch            | glob or regexp
+      luinc              | ilu or ichol
       nfields            | numfields
       syl                | sylvester
       usage              | print_usage
--- a/doc/interpreter/sparse.txi	Sun Sep 21 23:27:27 2014 +0100
+++ b/doc/interpreter/sparse.txi	Mon Sep 22 20:19:01 2014 -0700
@@ -489,7 +489,7 @@
   @dfn{normest}, @dfn{sprank}, @dfn{spaugment}, @dfn{svds}
 
 @item Iterative techniques:
-  @dfn{ichol}, @dfn{ilu}, @dfn{luinc}, @dfn{pcg}, @dfn{pcr}
+  @dfn{ichol}, @dfn{ilu}, @dfn{pcg}, @dfn{pcr}
 @c @dfn{bicg}, @dfn{bicgstab}, @dfn{cholinc}, @dfn{cgs}, @dfn{gmres}, 
 @c @dfn{lsqr}, @dfn{minres}, @dfn{qmr}, @dfn{symmlq}
 
--- a/libinterp/corefcn/luinc.cc	Sun Sep 21 23:27:27 2014 +0100
+++ b/libinterp/corefcn/luinc.cc	Mon Sep 22 20:19:01 2014 -0700
@@ -37,7 +37,7 @@
 #include "ov-re-sparse.h"
 #include "ov-cx-sparse.h"
 
-DEFUN (luinc, args, nargout,
+DEFUN (__luinc__, args, nargout,
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, '0')\n\
 @deftypefnx {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{droptol})\n\
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/luinc.m	Mon Sep 22 20:19:01 2014 -0700
@@ -0,0 +1,93 @@
+## Copyright (C) 2014 John W. Eaton
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## @deftypefn  {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, '0')
+## @deftypefnx {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{droptol})
+## @deftypefnx {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{opts})
+##
+## @code{luinc} is deprecated and will be removed in Octave version 4.6.
+## Please use @code{ilu} or @code{ichol} in all new code.
+##
+## Produce the incomplete LU@tie{}factorization of the sparse matrix @var{A}.
+## Two types of incomplete factorization are possible, and the type
+## is determined by the second argument to @code{luinc}.
+## 
+## Called with a second argument of @qcode{'0'}, the zero-level incomplete
+## LU@tie{}factorization is produced.  This creates a factorization of @var{A}
+## where the position of the nonzero arguments correspond to the same
+## positions as in the matrix @var{A}.
+## 
+## Alternatively, the fill-in of the incomplete LU@tie{}factorization can
+## be controlled through the variable @var{droptol} or the structure
+## @var{opts}.  The @sc{umfpack} multifrontal factorization code by Tim A.
+## Davis is used for the incomplete LU@tie{}factorization, (availability
+## @url{http://www.cise.ufl.edu/research/sparse/umfpack/})
+## 
+## @var{droptol} determines the values below which the values in the
+## LU@tie{} factorization are dropped and replaced by zero.  It must be a
+## positive scalar, and any values in the factorization whose absolute value
+## are less than this value are dropped, expect if leaving them increase the
+## sparsity of the matrix.  Setting @var{droptol} to zero results in a complete
+## LU@tie{}factorization which is the default.
+## 
+## @var{opts} is a structure containing one or more of the fields
+## 
+## @table @code
+## @item droptol
+## The drop tolerance as above.  If @var{opts} only contains @code{droptol}
+## then this is equivalent to using the variable @var{droptol}.
+## 
+## @item milu
+## A logical variable flagging whether to use the modified incomplete
+## LU@tie{} factorization.  In the case that @code{milu} is true, the dropped
+## values are subtracted from the diagonal of the matrix @var{U} of the
+## factorization.  The default is @code{false}.
+## 
+## @item udiag
+## A logical variable that flags whether zero elements on the diagonal of
+## @var{U} should be replaced with @var{droptol} to attempt to avoid singular
+## factors.  The default is @code{false}.
+## 
+## @item thresh
+## Defines the pivot threshold in the interval [0,1].  Values outside that
+## range are ignored.
+## @end table
+## 
+## All other fields in @var{opts} are ignored.  The outputs from @code{luinc}
+## are the same as for @code{lu}.
+## 
+## Given the string argument @qcode{\"vector\"}, @code{luinc} returns the
+## values of @var{p} @var{q} as vector values.
+## @seealso{ilu, ichol, lu, sparse}
+## @end deftypefn
+
+## Deprecated in version 4.2
+
+function retval = usage (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "luinc is obsolete and will be removed from a future version of Octave, please use ilu or ichol instead");
+  endif
+
+  retval = __luinc__ (varargin{:});
+
+endfunction
+
--- a/scripts/deprecated/module.mk	Sun Sep 21 23:27:27 2014 +0100
+++ b/scripts/deprecated/module.mk	Mon Sep 22 20:19:01 2014 -0700
@@ -8,6 +8,7 @@
   deprecated/fmod.m \
   deprecated/fnmatch.m \
   deprecated/isstr.m \
+  deprecated/luinc.m \
   deprecated/nfields.m \
   deprecated/strmatch.m \
   deprecated/syl.m \
--- a/scripts/sparse/pcg.m	Sun Sep 21 23:27:27 2014 +0100
+++ b/scripts/sparse/pcg.m	Mon Sep 22 20:19:01 2014 -0700
@@ -124,7 +124,7 @@
 ## n = 10;
 ## A = diag (sparse (1:n));
 ## b = rand (n, 1);
-## [l, u, p, q] = luinc (A, 1.e-3);
+## [l, u, p] = ilu (A, struct ("droptol", 1.e-3));
 ## @end group
 ## @end example
 ##