math::special(3tcl)

📦
version 2.0 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 math::special — the Tcl Math Library glow-up 💖

okay bestie, so this is math::special(3tcl), straight out of the Tcl Math Library, and it's genuinely one of the most iconic pages in the whole collection. buckle up, because there's a LOT of math here and every single crumb matters. 🧚✨

✨ NAME ✨

math::special — Special mathematical functions 🎀

🌸 SYNOPSIS 🌸

package require Tcl ?8.5 9?

package require math::special ?0.5.3?

::math::special::eulerNumber index

::math::special::bernoulliNumber index

::math::special::Beta x y

::math::special::incBeta a b x

::math::special::regIncBeta a b x

::math::special::Gamma x

::math::special::digamma 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 🦋

So this package is literally the special functions package — like, the ones that get their own name in math because they're too famous to just be a normal formula, yk? the Gamma function, the Bessel functions, all of that. 🌈

Every function here has a procedure that carries its name — well, close approximation of its name, bestie, don't come for the naming conventions. 🙈 Here's the whole squad:

  • J0 — the zeroth-order Bessel function of the first kind 💅
  • J1 — the first-order Bessel function of the first kind 💅
  • Jn — the nth-order Bessel function of the first kind 💅
  • J1/2 — the half-order Bessel function of the first kind 💅
  • J-1/2 — the minus-half-order Bessel function of the first kind 💅
  • I_n — the modified Bessel function of the first kind of order n 💅
  • Gamma — the Gamma function, plus erf and erfc for the error function and the complementary error function ✨
  • fresnel_C and fresnel_S — the Fresnel integrals 🌊
  • elliptic_K and elliptic_E — the complete elliptic integrals 🥚
  • exponent_Ei and the other functions related to the so-called exponential integrals 🔥
  • legendre, hermite — some of the classical orthogonal polynomials 👑

👑 OVERVIEW 👑

Okay so the original page has this whole table, and I'm gonna walk you through every single row because the details are the moment, periodt. For each family I'm giving you the function, the domain of the argument x, the parameters, and the error bound. 💖

🧡 Bessel

  • J0, J1, Jn
    • Domain x: all of R
    • Parameter: n = integer
    • Error bound: < 1.0e-8 — and that holds for |x|<20, n<20
  • J1/2, J-1/2, I_n — wait, hold up, these are two different rows, lemme split them 🫶
  • J1/2, J-1/2
    • Domain x: x > 0
    • Parameter: n = integer
    • Error bound: exact (yes bestie, EXACT, she ate and left no crumbs)
  • I_n
    • Domain x: all of R
    • Parameter: n = integer
    • Error bound: < 1.0e-6

🥚 Elliptic functions

  • cn
    • Domain x: 0 <= x <= 1
    • Parameter: -- (none)
    • Error bound: < 1.0e-10
  • dn
    • Domain x: 0 <= x <= 1
    • Parameter: -- (none)
    • Error bound: < 1.0e-10
  • sn
    • Domain x: 0 <= x <= 1
    • Parameter: -- (none)
    • Error bound: < 1.0e-10

🥚➡️ Elliptic integrals

  • K
    • Domain x: 0 <= x < 1
    • Parameter: -- (none)
    • Error bound: < 1.0e-6
  • E
    • Domain x: 0 <= x < 1
    • Parameter: -- (none)
    • Error bound: < 1.0e-6

😭 Error functions

  • erf
    • Domain x: (not specified)
    • Parameter: -- (none)
    • Error bound: (not specified)
  • erfc
    • Domain x: (not specified)
    • Parameter: -- (none)
    • Error bound: (not specified)

🔔 Inverse normal distribution

  • invnorm
    • Domain x: 0 < x < 1
    • Parameter: -- (none)
    • Error bound: < 1.2e-9

🔥 Exponential integrals

  • Ei
    • Domain x: x != 0
    • Parameter: -- (none)
    • Error bound: < 1.0e-10 (relative)
  • En
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: as Ei
  • li
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: as Ei
  • Chi
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: < 1.0e-8
  • Shi
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: < 1.0e-8
  • Ci
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: < 2.0e-4
  • Si
    • Domain x: x > 0
    • Parameter: -- (none)
    • Error bound: < 2.0e-4

🌊 Fresnel integrals

  • C
    • Domain x: all of R
    • Parameter: -- (none)
    • Error bound: < 2.0e-3
  • S
    • Domain x: all of R
    • Parameter: -- (none)
    • Error bound: < 2.0e-3

🌈 general

  • Beta
    • Domain x: (see Gamma)
    • Parameter: -- (none)
    • Error bound: < 1.0e-9
  • Gamma
    • Domain x: x != 0,-1, -2, ...
    • Parameter: -- (none)
    • Error bound: < 1.0e-9
  • incBeta
    • Domain x: (not specified)
    • Parameter: a, b > 0
    • Error bound: < 1.0e-9
  • regIncBeta
    • Domain x: (not specified)
    • Parameter: a, b > 0
    • Error bound: < 1.0e-9
  • digamma
    • Domain x: x != 0,-1 -2, ...
    • Parameter: -- (none)
    • Error bound: < 1.0e-9
  • sinc
    • Domain x: all of R
    • Parameter: -- (none)
    • Error bound: exact

💜 orthogonal polynomials

  • Legendre
    • Domain x: all of R
    • Parameter: n = 0,1,...
    • Error bound: exact
  • Chebyshev
    • Domain x: all of R
    • Parameter: n = 0,1,...
    • Error bound: exact
  • Laguerre
    • Domain x: all of R
    • Parameter: n = 0,1,..., and alpha el. R
    • Error bound: exact
  • Hermite
    • Domain x: all of R
    • Parameter: n = 0,1,...
    • Error bound: exact
⚠️ note bestie: some of those error bounds are estimated — because there was literally no "formal" bound available with the implemented approximation method. and some of them hold for the auxiliary functions used for estimating the primary functions. so, yk, read them with that in mind. 🫶

🙈 the ones that are MISSING

not everything made it to the party, and the original is very upfront about it. 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 incomplete gamma function 💔

more parts coming, don't go anywhere bestie 💅✨

✨ PROCEDURES ✨

okay bestie, here's the whole menu of public procedures this package serves up 💖

  • ::math::special::eulerNumber index — hands you the index'th Euler number (heads up: these are integer values, no decimals here). these numbers get big fast, so only a limited set of them is available.
    • int index — which number you want back (should be between 0 and 54)
  • ::math::special::bernoulliNumber index — returns the index'th Bernoulli number. same deal as above, the values blow up quick, so only a limited amount exists.
    • int index — index of the number you want (should be between 0 and 52)
  • ::math::special::Beta x y — computes the Beta function for the arguments x and y ✨
    • float x — first argument for the Beta function
    • float y — second argument for the Beta function
  • ::math::special::incBeta a b x — computes the incomplete Beta function for argument x with parameters a and b
    • float a — first parameter for the incomplete Beta function, a > 0
    • float b — second parameter for the incomplete Beta function, b > 0
    • float x — argument for the incomplete Beta function
  • ::math::special::regIncBeta a b x — computes the regularized incomplete Beta function for argument x with parameters a and b
    • float a — first parameter for the incomplete Beta function, a > 0
    • float b — second parameter for the incomplete Beta function, b > 0
    • float x — argument for the regularized incomplete Beta function
  • ::math::special::Gamma x — computes the Gamma function for argument x 💅
    • float x — argument for the Gamma function
  • ::math::special::digamma x — computes the digamma function (that's psi, iykyk) for argument x
    • float x — argument for the digamma function
  • ::math::special::erf x — computes the error function for argument x
    • float x — argument for the error function
  • ::math::special::erfc x — computes the complementary error function for argument x
    • float x — argument for the complementary error function
  • ::math::special::invnorm p — computes 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 — computes the zeroth-order Bessel function of the first kind for the argument x
    • float x — argument for the Bessel function
  • ::math::special::J1 x — computes 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 — computes 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 — computes 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 — computes 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 — computes 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 — computes 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 — computes 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 — computes 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 — computes the complete elliptic integral of the first kind for the argument k
    • float k — argument for the function
  • ::math::special::elliptic_E k — computes the complete elliptic integral of the second kind for the argument k
    • float k — argument for the function
  • ::math::special::exponential_Ei x — computes 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 — computes 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 — computes the logarithmic integral for the argument x
    • float x — argument for the function (x > 0)
  • ::math::special::exponential_Ci x — computes the cosine integral for the argument x
    • float x — argument for the function (x > 0)
  • ::math::special::exponential_Si x — computes the sine integral for the argument x
    • float x — argument for the function (x > 0)
  • ::math::special::exponential_Chi x — computes the hyperbolic cosine integral for the argument x
    • float x — argument for the function (x > 0)
  • ::math::special::exponential_Shi x — computes the hyperbolic sine integral for the argument x
    • float x — argument for the function (x > 0)
  • ::math::special::fresnel_C x — computes the Fresnel cosine integral for real argument x
    • float x — argument for the function
  • ::math::special::fresnel_S x — computes the Fresnel sine integral for real argument x
    • float x — argument for the function
  • ::math::special::sinc x — computes the sinc function for real argument x
    • float x — argument for the function
  • ::math::special::legendre n — returns the Legendre polynomial of degree n (peep THE ORTHOGONAL POLYNOMIALS below 👇)
    • int n — degree of the polynomial
  • ::math::special::chebyshev n — returns the Chebyshev polynomial of degree n (first kind, obviously)
    • int n — degree of the polynomial
  • ::math::special::laguerre alpha n — returns 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 — returns the Hermite polynomial of degree n
    • int n — degree of the polynomial

🦋 THE ORTHOGONAL POLYNOMIALS 🦋

so for the classical families of orthogonal polynomials, this package is lowkey leaning on the math::polynomials package. if you wanna actually evaluate the polynomial at some coordinate, you use the evalPolyn command like this:

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

and fr fr, the return value from legendre and the other commands is actually the definition of the corresponding polynomial as it's used in that package. that's the whole vibe ✨

🧚 REMARKS ON THE IMPLEMENTATION 🧚

ngl you should know 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 they got implemented like that was that it was fast to do (the formulas are simple) and the computations are fast too. efficient queen 👑

the implementation of J1/2 does not suffer from this: this function can be expressed exactly in terms of elementary functions. no approximation, just math being iconic 💅

the functions J0 and J1 are the ones you'll 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 💀

okay so this document, and the package it describes, will undoubtedly contain bugs and other problems. no cap, nothing is perfect 😭 please report such in the category math :: special of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist].

please also report any ideas for enhancements you may have for either the package and/or the documentation. we wanna hear them 🫶

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. (yes, the left-most one, don't make me come find you 🙈)

🌸 KEYWORDS 🌸

Bessel functions, error function, math, special functions

👑 CATEGORY 👑

Mathematics

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

and that's a wrap bestie!! this whole thing lives in tcllib, version 0.5.4, and it's the math::special(3tcl) page 🎀 go forth and compute your special functions, you absolute main character ⭐💖

📦 where this page comes from