


math::special(n)         Tcl Math Library        math::special(n)


______________________________________________________________________________

NAME
       math::special - Special mathematical functions

SYNOPSIS
       package require Tcl  ?8.3?

       package require math::special  ?0.2?

       ::math::special::Beta x y

       ::math::special::Gamma x y

       ::math::special::erf x

       ::math::special::erfc x

       ::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                           0.2                              1





math::special(n)         Tcl Math Library        math::special(n)


       ::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):

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

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

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

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

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

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

       o      Gamma  for  the Gamma function, erf and erfc for the error func-
              tion and the complementary error function

       o      fresnel_C and fresnel_S for the Fresnel integrals

       o      elliptic_K and elliptic_E (complete elliptic integrals)

       o      exponent_Ei and other functions related to the  so-called  expo-
              nential integrals

       o      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.




math                           0.2                              2





math::special(n)         Tcl Math Library        math::special(n)


       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        |             |             |
                    | ierfc_n     |             |             |
                    |             |             |             |
       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 pack-
       age:

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

       o      Bessel functions of arbitrary order (and hence  the  Airy  func-
              tions)

       o      Chebyshev polynomials of the second kind (U_n)

       o      The digamma function (psi)



math                           0.2                              3





math::special(n)         Tcl Math Library        math::special(n)


       o      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 y
              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::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"



math                           0.2                              4





math::special(n)         Tcl Math Library        math::special(n)


              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 param-
              eter "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 param-
              eter "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 param-
              eter "k".





math                           0.2                              5





math::special(n)         Tcl Math Library        math::special(n)


              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 argu-
              ment "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                           0.2                              6





math::special(n)         Tcl Math Library        math::special(n)


       ::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



math                           0.2                              7





math::special(n)         Tcl Math Library        math::special(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  poly-
       nomial 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) accu-
       racy 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 combina-
       torics package, whereas that of  the  error  functions  relies  on  the
       statistics package.

       The  computation  of the complete elliptic integrals uses the AGM algo-
       rithm.

       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     SF    Trackers    [http://source-
       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       Bessel functions, error function, math, special functions




math                           0.2                              8





math::special(n)         Tcl Math Library        math::special(n)


CATEGORY
       Mathematics

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




















































math                           0.2                              9


