Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       math::special - Special mathematical functions

SYNOPSIS

       package require Tcl  ?8.3?

       package require math::special  ?0.3?

       ::math::special::Beta x y

       ::math::special::Gamma x

       ::math::special::erf x

       ::math::special::erfc x

       ::math::special::invnorm p

       ::math::special::J0 x

       ::math::special::J1 x

       ::math::special::Jn n x

       ::math::special::J1/2 x

       ::math::special::J-1/2 x

       ::math::special::I_n x

       ::math::special::cn u k

       ::math::special::dn u k

       ::math::special::sn u k

       ::math::special::elliptic_K k

       ::math::special::elliptic_E k

       ::math::special::exponential_Ei x

       ::math::special::exponential_En n x

       ::math::special::exponential_li x

       ::math::special::exponential_Ci x

       ::math::special::exponential_Si x

       ::math::special::exponential_Chi x

       ::math::special::exponential_Shi x

       ::math::special::fresnel_C x

       ::math::special::fresnel_S x

       ::math::special::sinc x

       ::math::special::legendre n

       ::math::special::chebyshev n

       ::math::special::laguerre alpha n

       ::math::special::hermite n

_________________________________________________________________________________________________

DESCRIPTION

       This  package implements several so-called special functions, like the Gamma function, the
       Bessel functions and such.

       Each function is  implemented  by  a  procedure  that  bears  its  name  (well,  in  close
       approximation):

       •      J0 for the zeroth-order Bessel function of the first kind

       •      J1 for the first-order Bessel function of the first kind

       •      Jn for the nth-order Bessel function of the first kind

       •      J1/2 for the half-order Bessel function of the first kind

       •      J-1/2 for the minus-half-order Bessel function of the first kind

       •      I_n for the modified Bessel function of the first kind of order n

       •      Gamma  for  the  Gamma  function,  erf  and  erfc  for  the  error function and the
              complementary error function

       •      fresnel_C and fresnel_S for the Fresnel integrals

       •      elliptic_K and elliptic_E (complete elliptic integrals)

       •      exponent_Ei and other functions related to the so-called exponential integrals

       •      legendre, hermite: some of the classical orthogonal polynomials.

OVERVIEW

       In the following table several characteristics  of  the  functions  in  this  package  are
       summarized: the domain for the argument, the values for the parameters and error bounds.

              Family       | Function    | Domain x    | Parameter   | Error bound
              -------------+-------------+-------------+-------------+--------------
              Bessel       | J0, J1,     | all of R    | n = integer |   < 1.0e-8
                           | Jn          |             |             |  (|x|<20, n<20)
              Bessel       | J1/2, J-1/2,|  x > 0      | n = integer |   exact
              Bessel       | I_n         | all of R    | n = integer |   < 1.0e-6
                           |             |             |             |
              Elliptic     | cn          | 0 <= x <= 1 |     --      |   < 1.0e-10
              functions    | dn          | 0 <= x <= 1 |     --      |   < 1.0e-10
                           | sn          | 0 <= x <= 1 |     --      |   < 1.0e-10
              Elliptic     | K           | 0 <= x < 1  |     --      |   < 1.0e-6
              integrals    | E           | 0 <= x < 1  |     --      |   < 1.0e-6
                           |             |             |             |
              Error        | erf         |             |     --      |
              functions    | erfc        |             |             |
                           |             |             |             |
              Inverse      | invnorm     | 0 < x < 1   |     --      |   < 1.2e-9
              normal       |             |             |             |
              distribution |             |             |             |
                           |             |             |             |
              Exponential  | Ei          |  x != 0     |     --      |   < 1.0e-10 (relative)
              integrals    | En          |  x >  0     |     --      |   as Ei
                           | li          |  x > 0      |     --      |   as Ei
                           | Chi         |  x > 0      |     --      |   < 1.0e-8
                           | Shi         |  x > 0      |     --      |   < 1.0e-8
                           | Ci          |  x > 0      |     --      |   < 2.0e-4
                           | Si          |  x > 0      |     --      |   < 2.0e-4
                           |             |             |             |
              Fresnel      | C           |  all of R   |     --      |   < 2.0e-3
              integrals    | S           |  all of R   |     --      |   < 2.0e-3
                           |             |             |             |
              general      | Beta        | (see Gamma) |     --      |   < 1.0e-9
                           | Gamma       |  x != 0,-1, |     --      |   < 1.0e-9
                           |             |  -2, ...    |             |
                           | sinc        |  all of R   |     --      |   exact
                           |             |             |             |
              orthogonal   | Legendre    |  all of R   | n = 0,1,... |   exact
              polynomials  | Chebyshev   |  all of R   | n = 0,1,... |   exact
                           | Laguerre    |  all of R   | n = 0,1,... |   exact
                           |             |             | alpha el. R |
                           | Hermite     |  all of R   | n = 0,1,... |   exact

       Note:  Some  of  the error bounds are estimated, as no "formal" bounds were available with
       the implemented approximation method, others hold for the  auxiliary  functions  used  for
       estimating the primary functions.

       The following well-known functions are currently missing from the package:

       •      Bessel functions of the second kind (Y_n, K_n)

       •      Bessel functions of arbitrary order (and hence the Airy functions)

       •      Chebyshev polynomials of the second kind (U_n)

       •      The digamma function (psi)

       •      The incomplete gamma and beta functions

PROCEDURES

       The package defines the following public procedures:

       ::math::special::Beta x y
              Compute the Beta function for arguments "x" and "y"

              float x
                     First argument for the Beta function

              float y
                     Second argument for the Beta function

       ::math::special::Gamma x
              Compute the Gamma function for argument "x"

              float x
                     Argument for the Gamma function

       ::math::special::erf x
              Compute the error function for argument "x"

              float x
                     Argument for the error function

       ::math::special::erfc x
              Compute the complementary error function for argument "x"

              float x
                     Argument for the complementary error function

       ::math::special::invnorm p
              Compute the inverse of the normal distribution function for argument "p"

              float p
                     Argument  for  the  inverse  normal distribution function (p must be greater
                     than 0 and lower than 1)

       ::math::special::J0 x
              Compute the zeroth-order Bessel function of the first kind for the argument "x"

              float x
                     Argument for the Bessel function

       ::math::special::J1 x
              Compute the first-order Bessel function of the first kind for the argument "x"

              float x
                     Argument for the Bessel function

       ::math::special::Jn n x
              Compute the nth-order Bessel function of the first kind for the argument "x"

              integer n
                     Order of the Bessel function

              float x
                     Argument for the Bessel function

       ::math::special::J1/2 x
              Compute the half-order Bessel function of the first kind for the argument "x"

              float x
                     Argument for the Bessel function

       ::math::special::J-1/2 x
              Compute the minus-half-order Bessel function of the first kind for the argument "x"

              float x
                     Argument for the Bessel function

       ::math::special::I_n x
              Compute the modified Bessel function of the first kind of order n for the  argument
              "x"

              int x  Positive integer order of the function

              float x
                     Argument for the function

       ::math::special::cn u k
              Compute the elliptic function cn for the argument "u" and parameter "k".

              float u
                     Argument for the function

              float k
                     Parameter

       ::math::special::dn u k
              Compute the elliptic function dn for the argument "u" and parameter "k".

              float u
                     Argument for the function

              float k
                     Parameter

       ::math::special::sn u k
              Compute the elliptic function sn for the argument "u" and parameter "k".

              float u
                     Argument for the function

              float k
                     Parameter

       ::math::special::elliptic_K k
              Compute the complete elliptic integral of the first kind for the argument "k"

              float k
                     Argument for the function

       ::math::special::elliptic_E k
              Compute the complete elliptic integral of the second kind for the argument "k"

              float k
                     Argument for the function

       ::math::special::exponential_Ei x
              Compute the exponential integral of the second kind for the argument "x"

              float x
                     Argument for the function (x != 0)

       ::math::special::exponential_En n x
              Compute the exponential integral of the first kind for the argument "x" and order n

              int n  Order of the integral (n >= 0)

              float x
                     Argument for the function (x >= 0)

       ::math::special::exponential_li x
              Compute the logarithmic integral for the argument "x"

              float x
                     Argument for the function (x > 0)

       ::math::special::exponential_Ci x
              Compute the cosine integral for the argument "x"

              float x
                     Argument for the function (x > 0)

       ::math::special::exponential_Si x
              Compute the sine integral for the argument "x"

              float x
                     Argument for the function (x > 0)

       ::math::special::exponential_Chi x
              Compute the hyperbolic cosine integral for the argument "x"

              float x
                     Argument for the function (x > 0)

       ::math::special::exponential_Shi x
              Compute the hyperbolic sine integral for the argument "x"

              float x
                     Argument for the function (x > 0)

       ::math::special::fresnel_C x
              Compute the Fresnel cosine integral for real argument x

              float x
                     Argument for the function

       ::math::special::fresnel_S x
              Compute the Fresnel sine integral for real argument x

              float x
                     Argument for the function

       ::math::special::sinc x
              Compute the sinc function for real argument x

              float x
                     Argument for the function

       ::math::special::legendre n
              Return the Legendre polynomial of degree n (see THE ORTHOGONAL POLYNOMIALS)

              int n  Degree of the polynomial

       ::math::special::chebyshev n
              Return the Chebyshev polynomial of degree n (of the first kind)

              int n  Degree of the polynomial

       ::math::special::laguerre alpha n
              Return the Laguerre polynomial of degree n with parameter alpha

              float alpha
                     Parameter of the Laguerre polynomial

              int n  Degree of the polynomial

       ::math::special::hermite n
              Return the Hermite polynomial of degree n

              int n  Degree of the polynomial

THE ORTHOGONAL POLYNOMIALS

       For  dealing  with the classical families of orthogonal polynomials, the package relies on
       the math::polynomials package. To evaluate the polynomial  at  some  coordinate,  use  the
       evalPolyn command:

                 set leg2 [::math::special::legendre 2]
                 puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]"

       The  return  value  from the legendre and other commands is actually the definition of the
       corresponding polynomial as used in that package.

REMARKS ON THE IMPLEMENTATION

       It should be noted, that the actual implementation of J0 and J1 depends on straightforward
       Gaussian  quadrature  formulas.  The  (absolute)  accuracy  of the results is of the order
       1.0e-4 or better. The main reason to implement them like that was that it was fast  to  do
       (the formulas are simple) and the computations are fast too.

       The  implementation  of  J1/2  does  not  suffer from this: this function can be expressed
       exactly in terms of elementary functions.

       The functions J0 and J1 are the ones you will encounter most frequently in practice.

       The computation of I_n is based on Miller's algorithm for computing the  minimal  function
       from recurrence relations.

       The  computation  of  the  Gamma  and  Beta functions relies on the combinatorics package,
       whereas that of the error functions relies on the statistics package.

       The computation of the complete elliptic integrals uses the AGM algorithm.

       Much information about these functions can be found in:

       Abramowitz and Stegun: Handbook of Mathematical Functions (Dover, ISBN 486-61272-4)

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.   Please  report  such  in  the  category math :: special of the Tcllib Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       Bessel functions, error function, math, special functions

CATEGORY

       Mathematics

COPYRIGHT

       Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net>