# HG changeset patch # User Rik # Date 1411442341 25200 # Node ID e278c939a41917d4a7af7c1bc1bf0818d9400bcf # Parent 8b2a919d24bc4707cf91daadbc61e1c3c2d8fbe3 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. diff -r 8b2a919d24bc -r e278c939a419 NEWS --- 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 diff -r 8b2a919d24bc -r e278c939a419 doc/interpreter/sparse.txi --- 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} diff -r 8b2a919d24bc -r e278c939a419 libinterp/corefcn/luinc.cc --- 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\ diff -r 8b2a919d24bc -r e278c939a419 scripts/deprecated/luinc.m --- /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 +## . + +## @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 + diff -r 8b2a919d24bc -r e278c939a419 scripts/deprecated/module.mk --- 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 \ diff -r 8b2a919d24bc -r e278c939a419 scripts/sparse/pcg.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 ##