octave: Special Functions
17.6 Special Functions
======================
-- : [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.
0. Normal return.
1. Input error, return ‘NaN’.
2. Overflow, return ‘Inf’.
3. Loss of significance by argument reduction results in less
than half of machine accuracy.
4. Complete loss of significance by argument reduction, return
‘NaN’.
5. Error—no computation, algorithm termination condition not met,
return ‘NaN’.
-- : [J, IERR] = besselj (ALPHA, X, OPT)
-- : [Y, IERR] = bessely (ALPHA, X, OPT)
-- : [I, IERR] = besseli (ALPHA, X, OPT)
-- : [K, IERR] = besselk (ALPHA, X, OPT)
-- : [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 1
or true, the result is multiplied by ‘exp (-abs (imag (X)))’.
‘bessely’
Bessel functions of the second kind. If the argument OPT is 1
or true, the result is multiplied by ‘exp (-abs (imag (X)))’.
‘besseli’
Modified Bessel functions of the first kind. If the argument
OPT is 1 or true, the result is multiplied by ‘exp (-abs (real
(X)))’.
‘besselk’
Modified Bessel functions of the second kind. If the argument
OPT is 1 or true, 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 1 or true, 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.
0. Normal return.
1. Input error, return ‘NaN’.
2. Overflow, return ‘Inf’.
3. Loss of significance by argument reduction results in less
than half of machine accuracy.
4. Complete loss of significance by argument reduction, return
‘NaN’.
5. Error—no computation, algorithm termination condition not met,
return ‘NaN’.
-- : 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. betaln XREFbetaln, for computing the logarithm of
the Beta function in an efficient manner.
See also: betaln XREFbetaln, betainc XREFbetainc,
betaincinv XREFbetaincinv.
-- : betainc (X, A, B)
Compute the regularized incomplete Beta function.
The regularized incomplete Beta function is defined by
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 XREFbetaincinv, beta XREFbeta,
betaln XREFbetaln.
-- : betaincinv (Y, A, B)
Compute the inverse of the incomplete Beta function.
The inverse is the value X such that
Y == betainc (X, A, B)
DONTPRINTYET See also: betainc XREFbetainc, beta XREFbeta, *noteDONTPRINTYET See also: betainc XREFbetainc, beta XREFbeta,
betaln XREFbetaln.
-- : 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.
DONTPRINTYET See also: beta XREFbeta, betainc XREFbetainc, *noteDONTPRINTYET See also: beta XREFbeta, betainc XREFbetainc,
betaincinv XREFbetaincinv, gammaln XREFgammaln.
-- : 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 XREFnchoosek.
-- : 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.’
-- : 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.’
-- : dawson (Z)
Compute the Dawson (scaled imaginary error) function.
The Dawson function is defined as
(sqrt (pi) / 2) * exp (-z^2) * erfi (z)
DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, *noteerfcx:
DONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfcx
XREFerfcx, erfi XREFerfi, erfinv XREFerfinv, *noteDONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfcx
XREFerfcx, erfi XREFerfi, erfinv XREFerfinv,
erfcinv XREFerfcinv.
-- : [SN, CN, DN, ERR] = ellipj (U, M)
-- : [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.
0. Normal return.
1. 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 XREFellipke.
-- : K = ellipke (M)
-- : K = ellipke (M, TOL)
-- : [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*t^2))
0
Elliptic integrals of the second kind are defined as
1
/ sqrt (1 - m*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 XREFellipj.
-- : erf (Z)
Compute the error function.
The error function is defined as
z
2 /
erf (z) = --------- * | e^(-t^2) dt
sqrt (pi) /
t=0
DONTPRINTYET See also: erfc XREFerfc, erfcx XREFerfcx, *noteerfi:
DONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erfcx XREFerfcx, erfi
XREFerfi, dawson XREFdawson, erfinv XREFerfinv, *noteDONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erfcx XREFerfcx, erfi
XREFerfi, dawson XREFdawson, erfinv XREFerfinv,
erfcinv XREFerfcinv.
-- : erfc (Z)
Compute the complementary error function.
The complementary error function is defined as ‘1 - erf (Z)’.
DONTPRINTYET See also: erfcinv XREFerfcinv, erfcx XREFerfcx, *noteDONTPRINTYET DONTPRINTYET See also: erfcinv XREFerfcinv, erfcx XREFerfcx,
erfi XREFerfi, dawson XREFdawson, erf XREFerf, *noteDONTPRINTYET DONTPRINTYET See also: erfcinv XREFerfcinv, erfcx XREFerfcx,
erfi XREFerfi, dawson XREFdawson, erf XREFerf,
erfinv XREFerfinv.
-- : erfcx (Z)
Compute the scaled complementary error function.
The scaled complementary error function is defined as
exp (z^2) * erfc (z)
DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, *noteerfi:
DONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfi
XREFerfi, dawson XREFdawson, erfinv XREFerfinv, *noteDONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfi
XREFerfi, dawson XREFdawson, erfinv XREFerfinv,
erfcinv XREFerfcinv.
-- : erfi (Z)
Compute the imaginary error function.
The imaginary error function is defined as
-i * erf (i*z)
DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, *noteerfcx:
DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfcx
XREFerfcx, dawson XREFdawson, erfinv XREFerfinv,
erfcinv XREFerfcinv.
-- : erfinv (X)
Compute the inverse error function.
The inverse error function is defined such that
erf (Y) == X
DONTPRINTYET See also: erf XREFerf, erfc XREFerfc, *noteerfcx:
DONTPRINTYET DONTPRINTYET See also: erf XREFerf, erfc XREFerfc, erfcx
XREFerfcx, erfi XREFerfi, dawson XREFdawson, *noteDONTPRINTYET DONTPRINTYET See also: erf XREFerf, erfc XREFerfc, erfcx
XREFerfcx, erfi XREFerfi, dawson XREFdawson,
erfcinv XREFerfcinv.
-- : erfcinv (X)
Compute the inverse complementary error function.
The inverse complementary error function is defined such that
erfc (Y) == X
DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, *noteerfcx:
DONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfcx
XREFerfcx, erfi XREFerfi, dawson XREFdawson, *noteDONTPRINTYET DONTPRINTYET See also: erfc XREFerfc, erf XREFerf, erfcx
XREFerfcx, erfi XREFerfi, dawson XREFdawson,
erfinv XREFerfinv.
-- : 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 as
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’.
-- : gamma (Z)
Compute the Gamma function.
The Gamma function is defined as
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 XREFgammainc, gammaln XREFgammaln,
factorial XREFfactorial.
-- : gammainc (X, A)
-- : gammainc (X, A, "lower")
-- : gammainc (X, A, "upper")
Compute the normalized incomplete gamma function.
This is defined as
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 XREFgamma, gammaln XREFgammaln.
-- : L = legendre (N, X)
-- : L = legendre (N, X, NORMALIZATION)
Compute the associated 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
associated 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 associated 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 associated 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)!
-- : gammaln (X)
-- : lgamma (X)
Return the natural logarithm of the gamma function of X.
See also: gamma XREFgamma, gammainc XREFgammainc.
-- : psi (Z)
-- : psi (K, Z)
Compute the psi (polygamma) function.
The polygamma functions are the Kth derivative of the logarithm of
the gamma function. If unspecified, K defaults to zero. A value
of zero computes the digamma function, a value of 1, the trigamma
function, and so on.
The digamma function is defined:
psi (z) = d (log (gamma (z))) / dx
When computing the digamma function (when K equals zero), Z can
have any value real or complex value. However, for polygamma
functions (K higher than 0), Z must be real and non-negative.
See also: gamma XREFgamma, gammainc XREFgammainc,
gammaln XREFgammaln.