Mercurial > octave
changeset 24594:a81af57f6144
doc: Redo documentation of Bessel functions.
* arith.txi: Add DOCSTRING entries for bessely, besseli, besselk, besselh.
* besselj.cc (Fbesselj, Fbessely, Fbesseli, Fbesselk, Fbesselh): Expand
documentation for each function rather than referring everything back to
besselj.
* scripts/help/bessel.m: Moved from scripts/specfun.
* scripts/help/module.mk, scripts/specfun/module.mk: Update build system for
move of bessel.m
| author | Rik <rik@octave.org> |
|---|---|
| date | Sun, 14 Jan 2018 16:57:20 -0800 |
| parents | 7a0cf02ed6d5 |
| children | 56f1f60f35fd |
| files | doc/interpreter/arith.txi libinterp/corefcn/besselj.cc scripts/help/bessel.m scripts/help/module.mk scripts/specfun/bessel.m scripts/specfun/module.mk |
| diffstat | 6 files changed, 312 insertions(+), 150 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/arith.txi Sun Jan 14 18:51:21 2018 +0100 +++ b/doc/interpreter/arith.txi Sun Jan 14 16:57:20 2018 -0800 @@ -275,6 +275,14 @@ @DOCSTRING(besselj) +@DOCSTRING(bessely) + +@DOCSTRING(besseli) + +@DOCSTRING(besselk) + +@DOCSTRING(besselh) + @DOCSTRING(beta) @DOCSTRING(betainc)
--- a/libinterp/corefcn/besselj.cc Sun Jan 14 18:51:21 2018 +0100 +++ b/libinterp/corefcn/besselj.cc Sun Jan 14 16:57:20 2018 -0800 @@ -299,51 +299,81 @@ DEFUN (besselj, args, nargout, doc: /* -*- texinfo -*- -@deftypefn {} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt}) -@deftypefnx {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) -@deftypefnx {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) -@deftypefnx {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) -@deftypefnx {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) -Compute Bessel or Hankel functions of various kinds: +@deftypefn {} {@var{J} =} besselj (@var{alpha}, @var{x}) +@deftypefnx {} {@var{J} =} besselj (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{J}, @var{ierr}] =} besselj (@dots{}) +Compute Bessel functions of the first kind. + +The order of the Bessel function @var{alpha} must be real. The points for +evaluation @var{x} may be complex. + +If the optional argument @var{opt} is 1 or true, the result @var{J} is +multiplied by @w{@code{exp (-abs (imag (@var{x})))}}. + +If @var{alpha} is a scalar, the result is the same size as @var{x}. If @var{x} +is a scalar, the result is the same size as @var{alpha}. If @var{alpha} is a +row vector and @var{x} is a column vector, the result is a matrix with +@code{length (@var{x})} rows and @code{length (@var{alpha})} columns. +Otherwise, @var{alpha} and @var{x} must conform and the result will be the same +size. -@table @code -@item besselj -Bessel functions of the first kind. If the argument @var{opt} is 1 or true, -the result is multiplied by @w{@code{exp (-abs (imag (@var{x})))}}. +If requested, @var{ierr} contains the following status information and is the +same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. -@item bessely -Bessel functions of the second kind. If the argument @var{opt} is 1 or -true, the result is multiplied by @code{exp (-abs (imag (@var{x})))}. +@item +Overflow, return @code{Inf}. -@item besseli +@item +Loss of significance by argument reduction results in less than half of machine +accuracy. -Modified Bessel functions of the first kind. If the argument @var{opt} is 1 -or true, the result is multiplied by @code{exp (-abs (real (@var{x})))}. - -@item besselk +@item +Complete loss of significance by argument reduction, return @code{NaN}. -Modified Bessel functions of the second kind. If the argument @var{opt} is -1 or true, the result is multiplied by @code{exp (@var{x})}. +@item +Error---no computation, algorithm termination condition not met, return +@code{NaN}. +@end enumerate -@item besselh -Compute Hankel functions of the first (@var{k} = 1) or second (@var{k} -= 2) kind. If the argument @var{opt} is 1 or true, the result is multiplied -by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for -@var{k} = 2. -@end table +@seealso{bessely, besseli, besselk, besselh} +@end deftypefn */) +{ + return do_bessel (BESSEL_J, "besselj", args, nargout); +} + +/* +%!# Function besselj is tested along with other bessels at the end of this file +*/ -If @var{alpha} is a scalar, the result is the same size as @var{x}. -If @var{x} is a scalar, the result is the same size as @var{alpha}. -If @var{alpha} is a row vector and @var{x} is a column vector, the -result is a matrix with @code{length (@var{x})} rows and -@code{length (@var{alpha})} columns. Otherwise, @var{alpha} and -@var{x} must conform and the result will be the same size. +DEFUN (bessely, args, nargout, + doc: /* -*- texinfo -*- +@deftypefn {} {@var{Y} =} bessely (@var{alpha}, @var{x}) +@deftypefnx {} {@var{Y} =} bessely (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{Y}, @var{ierr}] =} bessely (@dots{}) +Compute Bessel functions of the second kind. + +The order of the Bessel function @var{alpha} must be real. The points for +evaluation @var{x} may be complex. -The value of @var{alpha} must be real. The value of @var{x} may be -complex. +If the optional argument @var{opt} is 1 or true, the result @var{Y} is +multiplied by @w{@code{exp (-abs (imag (@var{x})))}}. -If requested, @var{ierr} contains the following status information -and is the same size as the result. +If @var{alpha} is a scalar, the result is the same size as @var{x}. If @var{x} +is a scalar, the result is the same size as @var{alpha}. If @var{alpha} is a +row vector and @var{x} is a column vector, the result is a matrix with +@code{length (@var{x})} rows and @code{length (@var{alpha})} columns. +Otherwise, @var{alpha} and @var{x} must conform and the result will be the same +size. + +If requested, @var{ierr} contains the following status information and is the +same size as the result. @enumerate 0 @item @@ -356,29 +386,18 @@ Overflow, return @code{Inf}. @item -Loss of significance by argument reduction results in less than -half of machine accuracy. +Loss of significance by argument reduction results in less than half of machine +accuracy. @item Complete loss of significance by argument reduction, return @code{NaN}. @item -Error---no computation, algorithm termination condition not met, -return @code{NaN}. +Error---no computation, algorithm termination condition not met, return +@code{NaN}. @end enumerate -@end deftypefn */) -{ - return do_bessel (BESSEL_J, "besselj", args, nargout); -} -/* -%!# Function besselj is tested along with other bessels at the end of this file -*/ - -DEFUN (bessely, args, nargout, - doc: /* -*- texinfo -*- -@deftypefn {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) -See besselj. +@seealso{besselj, besseli, besselk, besselh} @end deftypefn */) { return do_bessel (BESSEL_Y, "bessely", args, nargout); @@ -390,9 +409,52 @@ DEFUN (besseli, args, nargout, doc: /* -*- texinfo -*- -@deftypefn {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) -See besselj. +@deftypefn {} {@var{I} =} besseli (@var{alpha}, @var{x}) +@deftypefnx {} {@var{I} =} besseli (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{I}, @var{ierr}] =} besseli (@dots{}) +Compute modified Bessel functions of the first kind. + +The order of the Bessel function @var{alpha} must be real. The points for +evaluation @var{x} may be complex. + +If the optional argument @var{opt} is 1 or true, the result @var{I} is +multiplied by @w{@code{exp (-abs (real (@var{x})))}}. + +If @var{alpha} is a scalar, the result is the same size as @var{x}. If @var{x} +is a scalar, the result is the same size as @var{alpha}. If @var{alpha} is a +row vector and @var{x} is a column vector, the result is a matrix with +@code{length (@var{x})} rows and @code{length (@var{alpha})} columns. +Otherwise, @var{alpha} and @var{x} must conform and the result will be the same +size. + +If requested, @var{ierr} contains the following status information and is the +same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. + +@item +Overflow, return @code{Inf}. + +@item +Loss of significance by argument reduction results in less than half of machine +accuracy. + +@item +Complete loss of significance by argument reduction, return @code{NaN}. + +@item +Error---no computation, algorithm termination condition not met, return +@code{NaN}. +@end enumerate + +@seealso{besselk, besselj, bessely, besselh} @end deftypefn */) + { return do_bessel (BESSEL_I, "besseli", args, nargout); } @@ -403,8 +465,51 @@ DEFUN (besselk, args, nargout, doc: /* -*- texinfo -*- -@deftypefn {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) -See besselj. +@deftypefn {} {@var{K} =} besselk (@var{alpha}, @var{x}) +@deftypefnx {} {@var{K} =} besselk (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{K}, @var{ierr}] =} besselk (@dots{}) + +Compute modified Bessel functions of the second kind. + +The order of the Bessel function @var{alpha} must be real. The points for +evaluation @var{x} may be complex. + +If the optional argument @var{opt} is 1 or true, the result @var{K} is +multiplied by @w{@code{exp (@var{x})}}. + +If @var{alpha} is a scalar, the result is the same size as @var{x}. If @var{x} +is a scalar, the result is the same size as @var{alpha}. If @var{alpha} is a +row vector and @var{x} is a column vector, the result is a matrix with +@code{length (@var{x})} rows and @code{length (@var{alpha})} columns. +Otherwise, @var{alpha} and @var{x} must conform and the result will be the same +size. + +If requested, @var{ierr} contains the following status information and is the +same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. + +@item +Overflow, return @code{Inf}. + +@item +Loss of significance by argument reduction results in less than half of machine +accuracy. + +@item +Complete loss of significance by argument reduction, return @code{NaN}. + +@item +Error---no computation, algorithm termination condition not met, return +@code{NaN}. +@end enumerate + +@seealso{besseli, besselj, bessely, besselh} @end deftypefn */) { return do_bessel (BESSEL_K, "besselk", args, nargout); @@ -416,8 +521,54 @@ DEFUN (besselh, args, nargout, doc: /* -*- texinfo -*- -@deftypefn {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) -See besselj. +@deftypefn {} {@var{H} =} besselh (@var{alpha}, @var{x}) +@deftypefnx {} {@var{H} =} besselh (@var{alpha}, @var{k}, @var{x}) +@deftypefnx {} {@var{H} =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{H}, @var{ierr}] =} besselh (@dots{}) +Compute Bessel functions of the third kind (Hankel functions). + +The order of the Bessel function @var{alpha} must be real. The kind of Hankel +function is specified by @var{k} and may be either first (@var{k} = 1) or +second (@var{k} = 2). The default is Hankel functions of the first kind. The +points for evaluation @var{x} may be complex. + +If the optional argument @var{opt} is 1 or true, the result is multiplied +by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for +@var{k} = 2. + +If @var{alpha} is a scalar, the result is the same size as @var{x}. If @var{x} +is a scalar, the result is the same size as @var{alpha}. If @var{alpha} is a +row vector and @var{x} is a column vector, the result is a matrix with +@code{length (@var{x})} rows and @code{length (@var{alpha})} columns. +Otherwise, @var{alpha} and @var{x} must conform and the result will be the same +size. + +If requested, @var{ierr} contains the following status information and is the +same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. + +@item +Overflow, return @code{Inf}. + +@item +Loss of significance by argument reduction results in less than half of machine +accuracy. + +@item +Complete loss of significance by argument reduction, return @code{NaN}. + +@item +Error---no computation, algorithm termination condition not met, return +@code{NaN}. +@end enumerate + +@seealso{besselj, bessely, besseli, besselk} @end deftypefn */) { int nargin = args.length ();
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/help/bessel.m Sun Jan 14 16:57:20 2018 -0800 @@ -0,0 +1,94 @@ +## Copyright (C) 1996-2017 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 +## <https://www.gnu.org/licenses/>. + +## -*- texinfo -*- +## @deftypefn {} {[@var{J}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt}) +## @deftypefnx {} {[@var{Y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) +## @deftypefnx {} {[@var{I}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) +## @deftypefnx {} {[@var{K}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) +## @deftypefnx {} {[@var{H}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) +## Compute Bessel or Hankel functions of various kinds: +## +## @table @code +## @item besselj +## Bessel functions of the first kind. If the argument @var{opt} is supplied, +## the result is multiplied by @code{exp (-abs (imag (x)))}. +## +## @item bessely +## Bessel functions of the second kind. If the argument @var{opt} is supplied, +## the result is multiplied by @w{@code{exp (-abs (imag (x)))}}. +## +## @item besseli +## Modified Bessel functions of the first kind. If the argument @var{opt} is +## supplied, the result is multiplied by @w{@code{exp (-abs (real (x)))}}. +## +## @item besselk +## Modified Bessel functions of the second kind. If the argument @var{opt} is +## supplied, the result is multiplied by @w{@code{exp (x)}}. +## +## @item besselh +## Compute Hankel functions of the first (@var{k} = 1) or second (@var{k} = 2) +## kind. If the argument @var{opt} is supplied, the result is multiplied by +## @w{@code{exp (-I*@var{x})}} for @var{k} = 1 or @w{@code{exp (I*@var{x})}} +## for @var{k} = 2. +## @end table +## +## If @var{alpha} is a scalar, the result is the same size as @var{x}. If +## @var{x} is a scalar, the result is the same size as @var{alpha}. If +## @var{alpha} is a row vector and @var{x} is a column vector, the result is +## a matrix with @code{length (@var{x})} rows and @code{length +## (@var{alpha})} columns. Otherwise, @var{alpha} and @var{x} must conform +## and the result will be the same size. +## +## The order of the Bessel function @var{alpha} must be real. The points for +## evaluation @var{x} may be complex. +## +## If requested, @var{ierr} contains the following status information and is +## the same size as the result. +## +## @enumerate 0 +## @item +## Normal return. +## +## @item +## Input error, return @code{NaN}. +## +## @item +## Overflow, return @code{Inf}. +## +## @item +## Loss of significance by argument reduction results in less than half of +## machine accuracy. +## +## @item +## Complete loss of significance by argument reduction, return @code{NaN}. +## +## @item +## Error---no computation, algorithm termination condition not met, return +## @code{NaN}. +## @end enumerate +## +## @seealso{besselj, bessely, besseli, besselk, besselh} +## @end deftypefn + +function bessel () + error ("bessel: you must use besselj, bessely, besseli, besselk, or besselh\n"); +endfunction + + +%!error bessel ()
--- a/scripts/help/module.mk Sun Jan 14 18:51:21 2018 +0100 +++ b/scripts/help/module.mk Sun Jan 14 16:57:20 2018 -0800 @@ -11,6 +11,7 @@ %reldir%/__makeinfo__.m \ %reldir%/__unimplemented__.m \ %reldir%/ans.m \ + %reldir%/bessel.m \ %reldir%/debug.m \ %reldir%/doc.m \ %reldir%/doc_cache_create.m \
--- a/scripts/specfun/bessel.m Sun Jan 14 18:51:21 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,91 +0,0 @@ -## Copyright (C) 1996-2017 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 -## <https://www.gnu.org/licenses/>. - -## -*- texinfo -*- -## @deftypefn {} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt}) -## @deftypefnx {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) -## @deftypefnx {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) -## @deftypefnx {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) -## @deftypefnx {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) -## Compute Bessel or Hankel functions of various kinds: -## -## @table @code -## @item besselj -## Bessel functions of the first kind. If the argument @var{opt} is supplied, -## the result is multiplied by @code{exp (-abs (imag (x)))}. -## -## @item bessely -## Bessel functions of the second kind. If the argument @var{opt} is supplied, -## the result is multiplied by @w{@code{exp (-abs (imag (x)))}}. -## -## @item besseli -## Modified Bessel functions of the first kind. If the argument @var{opt} is -## supplied, the result is multiplied by @w{@code{exp (-abs (real (x)))}}. -## -## @item besselk -## Modified Bessel functions of the second kind. If the argument @var{opt} is -## supplied, the result is multiplied by @w{@code{exp (x)}}. -## -## @item besselh -## Compute Hankel functions of the first (@var{k} = 1) or second (@var{k} = 2) -## kind. If the argument @var{opt} is supplied, the result is multiplied by -## @w{@code{exp (-I*@var{x})}} for @var{k} = 1 or @w{@code{exp (I*@var{x})}} -## for @var{k} = 2. -## @end table -## -## If @var{alpha} is a scalar, the result is the same size as @var{x}. -## If @var{x} is a scalar, the result is the same size as @var{alpha}. -## If @var{alpha} is a row vector and @var{x} is a column vector, the -## result is a matrix with @code{length (@var{x})} rows and -## @code{length (@var{alpha})} columns. Otherwise, @var{alpha} and -## @var{x} must conform and the result will be the same size. -## -## The value of @var{alpha} must be real. The value of @var{x} may be complex. -## -## If requested, @var{ierr} contains the following status information and is -## the same size as the result. -## -## @enumerate 0 -## @item -## Normal return. -## -## @item -## Input error, return @code{NaN}. -## -## @item -## Overflow, return @code{Inf}. -## -## @item -## Loss of significance by argument reduction results in less than half of -## machine accuracy. -## -## @item -## Complete loss of significance by argument reduction, return @code{NaN}. -## -## @item -## Error---no computation, algorithm termination condition not met, -## return @code{NaN}. -## @end enumerate -## @end deftypefn - -function bessel () - error ("bessel: you must use besselj, bessely, besseli, besselk, or besselh\n"); -endfunction - - -%!error bessel ()