### 17.6 Special Functions

Built-in Function: [a, ierr] = airy (k, z, opt)

  Compute Airy functions of the first and second kind, and their derivatives.

       K   Function   Scale factor (if "opt" is supplied)
      ---  --------   ---------------------------------------
       0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
       1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
       2   Bi (Z)     exp (-abs (real ((2/3) * Z * sqrt (Z))))
       3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z * sqrt (Z))))

  The function call `airy (z)` is equivalent to `airy (0, z)`.

  The result is the same size as z.

  If requested, ierr contains the following status information and is the same size as the result.

  1. Normal return.
  2. Input error, return `NaN`.
  3. Overflow, return `Inf`.
  4. Loss of significance by argument reduction results in less than half of machine accuracy.
  5. Complete loss of significance by argument reduction, return `NaN`.
  6. Error—no computation, algorithm termination condition not met, return `NaN`.

Built-in Function: [j, ierr] = besselj (alpha, x, opt)
Built-in Function: [y, ierr] = bessely (alpha, x, opt)
Built-in Function: [i, ierr] = besseli (alpha, x, opt)
Built-in Function: [k, ierr] = besselk (alpha, x, opt)
Built-in Function: [h, ierr] = besselh (alpha, k, x, opt)

  Compute Bessel or Hankel functions of various kinds:

  `besselj`

    Bessel functions of the first kind. If the argument opt is supplied, the result is multiplied by `exp (-abs (imag (x)))`.

  `bessely`

    Bessel functions of the second kind. If the argument opt is supplied, the result is multiplied by `exp (-abs (imag (x)))`.

  `besseli`

    Modified Bessel functions of the first kind. If the argument opt is supplied, the result is multiplied by `exp (-abs (real (x)))`.

  `besselk`

    Modified Bessel functions of the second kind. If the argument opt is supplied, the result is multiplied by `exp (x)`.

  `besselh`

    Compute Hankel functions of the first (k = 1) or second (k = 2) kind. If the argument opt is supplied, the result is multiplied by `exp (-I*x)` for k = 1 or `exp (I*x)` for k = 2.

  If alpha is a scalar, the result is the same size as x. If x is a scalar, the result is the same size as alpha. If alpha is a row vector and x is a column vector, the result is a matrix with `length (x)` rows and `length (alpha)` columns. Otherwise, alpha and x must conform and the result will be the same size.

  The value of alpha must be real. The value of x may be complex.

  If requested, ierr contains the following status information and is the same size as the result.

  1. Normal return.
  2. Input error, return `NaN`.
  3. Overflow, return `Inf`.
  4. Loss of significance by argument reduction results in less than half of machine accuracy.
  5. Complete loss of significance by argument reduction, return `NaN`.
  6. Error—no computation, algorithm termination condition not met, return `NaN`.

Mapping Function: beta (a, b)

  Compute the Beta function for real inputs a and b.

  The Beta function definition is

      beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

  The Beta function can grow quite large and it is often more useful to work with the logarithm of the output rather than the function directly. See betaln, for computing the logarithm of the Beta function in an efficient manner.

  See also: betaln, betainc, betaincinv.

Mapping Function: betainc (x, a, b)

  Return the regularized incomplete Beta function,

                                         x
                                1       /
      betainc (x, a, b) = -----------   | t^(a-1) (1-t)^(b-1) dt.
                          beta (a, b)   /
                                     t=0

  If x has more than one component, both a and b must be scalars. If x is a scalar, a and b must be of compatible dimensions.

  See also: betaincinv, beta, betaln.

Mapping Function: betaincinv (y, a, b)

  Compute the inverse of the incomplete Beta function, i.e., x such that

      y == betainc (x, a, b)

  See also: betainc, beta, betaln.

Mapping Function: betaln (a, b)

  Compute the natural logarithm of the Beta function for real inputs a and b.

  `betaln` is defined as

      betaln (a, b) = log (beta (a, b))

  and is calculated in a way to reduce the occurrence of underflow.

  The Beta function can grow quite large and it is often more useful to work with the logarithm of the output rather than the function directly.

  See also: beta, betainc, betaincinv, gammaln.

Mapping Function: bincoeff (n, k)

  Return the binomial coefficient of n and k, defined as

       /   \
       | n |    n (n-1) (n-2) … (n-k+1)
       |   |  = -------------------------
       | k |               k!
       \   /

  For example:

      bincoeff (5, 2)
         ⇒ 10

  In most cases, the `nchoosek` function is faster for small scalar integer arguments. It also warns about loss of precision for big arguments.

  See also: nchoosek.

Function File: commutation_matrix (m, n)

  Return the commutation matrix K(m,n) which is the unique m*n by m*n matrix such that K(m,n) * vec(A) = vec(A') for all m by n matrices A.

  If only one argument m is given, K(m,m) is returned.

  See Magnus and Neudecker (1988), Matrix Differential Calculus with Applications in Statistics and Econometrics.

Function File: duplication_matrix (n)

  Return the duplication matrix Dn which is the unique n^2 by n*(n+1)/2 matrix such that Dn vech (A) = vec (A) for all symmetric n by n matrices A.

  See Magnus and Neudecker (1988), Matrix Differential Calculus with Applications in Statistics and Econometrics.

Mapping Function: dawson (z)

  Compute the Dawson (scaled imaginary error) function,

      (sqrt (pi) / 2) * exp (-z^2) * erfi (z)

  See also: erfc, erf, erfcx, erfi, erfinv, erfcinv.

Built-in Function: [sn, cn, dn, err] = ellipj (u, m)
Built-in Function: [sn, cn, dn, err] = ellipj (u, m, tol)

  Compute the Jacobi elliptic functions sn, cn, and dn of complex argument u and real parameter m.

  If m is a scalar, the results are the same size as u. If u is a scalar, the results are the same size as m. If u is a column vector and m is a row vector, the results are matrices with `length (u)` rows and `length (m)` columns. Otherwise, u and m must conform in size and the results will be the same size as the inputs.

  The value of u may be complex. The value of m must be 0 ≤ m ≤ 1.

  The optional input tol is currently ignored (MATLAB uses this to allow faster, less accurate approximation).

  If requested, err contains the following status information and is the same size as the result.

  1. Normal return.
  2. Error—no computation, algorithm termination condition not met, return `NaN`.

  Reference: Milton Abramowitz and Irene A Stegun, Handbook of Mathematical Functions, Chapter 16 (Sections 16.4, 16.13, and 16.15), Dover, 1965.

  See also: ellipke.

Function File: k = ellipke (m)
Function File: k = ellipke (m, tol)
Function File: [k, e] = ellipke (…)

  Compute complete elliptic integrals of the first K(m) and second E(m) kind.

  m must be a scalar or real array with -Inf ≤ m ≤ 1.

  The optional input tol controls the stopping tolerance of the algorithm and defaults to `eps (class (m))`. The tolerance can be increased to compute a faster, less accurate approximation.

  When called with one output only elliptic integrals of the first kind are returned.

  Mathematical Note:

  Elliptic integrals of the first kind are defined as

               1
              /               dt
      K (m) = | ------------------------------
              / sqrt ((1 - t^2)*(1 - m^2*t^2))
             0

  Elliptic integrals of the second kind are defined as

               1
              /  sqrt (1 - m^2*t^2)
      E (m) = |  ------------------ dt
              /  sqrt (1 - t^2)
             0

  Reference: Milton Abramowitz and Irene A. Stegun, Handbook of Mathematical Functions, Chapter 17, Dover, 1965.

  See also: ellipj.

Mapping Function: erf (z)

  Compute the error function,

                              z
                    2        /
      erf (z) = --------- *  | e^(-t^2) dt
                sqrt (pi)    /
                          t=0

  See also: erfc, erfcx, erfi, dawson, erfinv, erfcinv.

Mapping Function: erfc (z)

  Compute the complementary error function, `1 - erf (z)`.

  See also: erfcinv, erfcx, erfi, dawson, erf, erfinv.

Mapping Function: erfcx (z)

  Compute the scaled complementary error function,

      exp (z^2) * erfc (z)

  See also: erfc, erf, erfi, dawson, erfinv, erfcinv.

Mapping Function: erfi (z)

  Compute the imaginary error function,

      -i * erf (i*z)

  See also: erfc, erf, erfcx, dawson, erfinv, erfcinv.

Mapping Function: erfinv (x)

  Compute the inverse error function, i.e., y such that

      erf (y) == x

  See also: erf, erfc, erfcx, erfi, dawson, erfcinv.

Mapping Function: erfcinv (x)

  Compute the inverse complementary error function, i.e., y such that

      erfc (y) == x

  See also: erfc, erf, erfcx, erfi, dawson, erfinv.

Function File: expint (x)

  Compute the exponential integral:

                 infinity
                /
      E_1 (x) = | exp (-t)/t dt
                /
               x

  Note: For compatibility, this functions uses the MATLAB definition of the exponential integral. Most other sources refer to this particular value as E_1 (x), and the exponential integral is

                  infinity
                 /
      Ei (x) = - | exp (-t)/t dt
                 /
               -x

  The two definitions are related, for positive real values of x, by `E_1 (-x) = -Ei (x) - i*pi`.

Mapping Function: gamma (z)

  Compute the Gamma function,

                   infinity
                  /
      gamma (z) = | t^(z-1) exp (-t) dt.
                  /
               t=0

  Programming Note: The gamma function can grow quite large even for small input values. In many cases it may be preferable to use the natural logarithm of the gamma function (`gammaln`) in calculations to minimize loss of precision. The final result is then `exp (result_using_gammaln).`

  See also: gammainc, gammaln, factorial.

Mapping Function: gammainc (x, a)
Mapping Function: gammainc (x, a, "lower")
Mapping Function: gammainc (x, a, "upper")

  Compute the normalized incomplete gamma function,

                                      x
                             1       /
      gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                        gamma (a)    /
                                  t=0

  with the limiting value of 1 as x approaches infinity. The standard notation is P(a,x), e.g., Abramowitz and Stegun (6.5.1).

  If a is scalar, then `gammainc (x, a)` is returned for each element of x and vice versa.

  If neither x nor a is scalar, the sizes of x and a must agree, and `gammainc` is applied element-by-element.

  By default the incomplete gamma function integrated from 0 to x is computed. If `"upper"` is given then the complementary function integrated from x to infinity is calculated. It should be noted that

      gammainc (x, a) ≡ 1 - gammainc (x, a, "upper")

  See also: gamma, gammaln.

Function File: l = legendre (n, x)
Function File: l = legendre (n, x, normalization)

  Compute the Legendre function of degree n and order m = 0 … n.

  The value n must be a real non-negative integer. x is a vector with real-valued elements in the range [-1, 1].

  The optional argument normalization may be one of `"unnorm"`, `"sch"`, or `"norm"`. The default if no normalization is given is `"unnorm"`.

  When the optional argument normalization is `"unnorm"`, compute the Legendre function of degree n and order m and return all values for m = 0 … n. The return value has one dimension more than x.

  The Legendre Function of degree n and order m:

       m         m      2  m/2   d^m
      P(x) = (-1) * (1-x  )    * ----  P(x)
       n                         dx^m   n

  with Legendre polynomial of degree n:

                1    d^n   2    n
      P(x) = ------ [----(x - 1) ]
       n     2^n n!  dx^n

  `legendre (3, [-1.0, -0.9, -0.8])` returns the matrix:

       x  |   -1.0   |   -0.9   |   -0.8
      ------------------------------------
      m=0 | -1.00000 | -0.47250 | -0.08000
      m=1 |  0.00000 | -1.99420 | -1.98000
      m=2 |  0.00000 | -2.56500 | -4.32000
      m=3 |  0.00000 | -1.24229 | -3.24000

  When the optional argument `normalization` is `"sch"`, compute the Schmidt semi-normalized associated Legendre function. The Schmidt semi-normalized associated Legendre function is related to the unnormalized Legendre functions by the following:

  For Legendre functions of degree n and order 0:

        0      0
      SP(x) = P(x)
        n      n

  For Legendre functions of degree n and order m:

        m      m         m    2(n-m)! 0.5
      SP(x) = P(x) * (-1)  * [-------]
        n      n              (n+m)!

  When the optional argument normalization is `"norm"`, compute the fully normalized associated Legendre function. The fully normalized associated Legendre function is related to the unnormalized Legendre functions by the following:

  For Legendre functions of degree n and order m

        m      m         m    (n+0.5)(n-m)! 0.5
      NP(x) = P(x) * (-1)  * [-------------]
        n      n                  (n+m)!

Mapping Function: gammaln (x)
Mapping Function: lgamma (x)

  Return the natural logarithm of the gamma function of x.

  See also: gamma, gammainc.