Navigation

The functions listed in Exponential integrals and error functions, Bessel functions and related functions and
Orthogonal polynomials, and many other functions as well, are merely
particular instances of the generalized hypergeometric function \(\,_pF_q\).
The functions listed in the following section enable efficient
direct evaluation of the underlying hypergeometric series, as
well as linear combinations, limits with respect to parameters,
and analytic continuations thereof. Extensions to twodimensional
series are also provided. See also the basic or q-analog of
the hypergeometric series in q-functions.

For convenience, most of the hypergeometric series of low order are
provided as standalone functions. They can equivalently be evaluated using
hyper(). As will be demonstrated in the respective docstrings,
all the hyp#f# functions implement analytic continuations and/or asymptotic
expansions with respect to the argument \(z\), thereby permitting evaluation
for \(z\) anywhere in the complex plane. Functions of higher degree can be
computed via hyper(), but generally only in rapidly convergent
instances.

Most hypergeometric and hypergeometric-derived functions accept optional
keyword arguments to specify options for hypercomb() or
hyper(). Some useful options are maxprec, maxterms,
zeroprec, accurate_small, hmag, force_series,
asymp_tol and eliminate. These options give control over what to
do in case of slow convergence, extreme loss of accuracy or
evaluation at zeros (these two cases cannot generally be
distinguished from each other automatically),
and singular parameter combinations.

Gives the hypergeometric function \(\,_2F_0\), defined formally by the
series

\[\,_2F_0(a,b;;z) = \sum_{n=0}^{\infty} (a)_n (b)_n \frac{z^n}{n!}.\]

This series usually does not converge. For small enough \(z\), it can be viewed
as an asymptotic series that may be summed directly with an appropriate
truncation. When this is not the case, hyp2f0() gives a regularized sum,
or equivalently, it uses a representation in terms of the
hypergeometric U function [1]. The series also converges when either \(a\) or \(b\)
is a nonpositive integer, as it then terminates into a polynomial
after \(-a\) or \(-b\) terms.

Even with real arguments, the regularized value of 2F0 is often complex-valued,
but the imaginary part decreases exponentially as \(z \to 0\). In the following
example, the first call uses complex evaluation while the second has a small
enough \(z\) to evaluate using the direct series and thus the returned value
is strictly real (this should be taken to indicate that the imaginary
part is less than eps):

and for \(|z| \ge 1\) by analytic continuation, with a branch cut on \((1, \infty)\)
when necessary.

Special cases of this function include many of the orthogonal polynomials as
well as the incomplete beta function and other functions. Properties of the
Gauss hypergeometric function are documented comprehensively in many references,
for example Abramowitz & Stegun, section 15.

The implementation supports the analytic continuation as well as evaluation
close to the unit circle where \(|z| \approx 1\). The syntax hyp2f1(a,b,c,z)
is equivalent to hyper([a,b],[c],z).

Examples

Evaluation with \(z\) inside, outside and on the unit circle, for
fixed parameters:

and for \(|z| \ge 1\) by analytic continuation. The analytic structure of this
function is similar to that of \(\,_2F_1\), generally with a singularity at
\(z = 1\) and a branch cut on \((1, \infty)\).

The parameters lists a_s and b_s may contain integers,
real numbers, complex numbers, as well as exact fractions given in
the form of tuples \((p, q)\). hyper() is optimized to handle
integers and fractions more efficiently than arbitrary
floating-point parameters (since rational parameters are by
far the most common).

Examples

Verifying that hyper() gives the sum in the definition, by
comparison with nsum():

The analytic continuations of the functions with \(p = q+1\), i.e. \(\,_2F_1\),
\(\,_3F_2\), \(\,_4F_3\), etc, are all implemented and therefore these functions
can be evaluated for \(|z| \ge 1\). The shortcuts hyp2f1(), hyp3f2()
are available to handle the most common cases (see their documentation),
but functions of higher degree are also supported via hyper():

Please note that, as currently implemented, evaluation of \(\,_pF_{p-1}\)
with \(p \ge 3\) may be slow or inaccurate when \(|z-1|\) is small,
for some parameter values.

When \(p > q+1\), hyper computes the (iterated) Borel sum of the divergent
series. For \(\,_2F_0\) the Borel sum has an analytic solution and can be
computed efficiently (see hyp2f0()). For higher degrees, the functions
is evaluated first by attempting to sum it directly as an asymptotic
series (this only works for tiny \(|z|\)), and then by evaluating the Borel
regularized sum using numerical integration. Except for
special parameter combinations, this can be extremely slow.

Typically the parameters are linear combinations of a small set of base
parameters; hypercomb() permits computing a correct value in
the case that some of the \(\alpha\), \(\beta\), \(b\) turn out to be
nonpositive integers, or if division by zero occurs for some \(w^c\),
assuming that there are opposing singularities that cancel out.
The limit is computed by evaluating the function with the base
parameters perturbed, at a higher working precision.

The first argument should be a function that takes the perturbable
base parameters params as input and returns \(N\) tuples
(w,c,alpha,beta,a,b,z), where the coefficients w, c,
gamma factors alpha, beta, and hypergeometric coefficients
a, b each should be lists of numbers, and z should be a single
number.

There are \(p\) elements \(a_j\).
The argument a_s should be a pair of lists, the first containing the
\(n\) elements \(a_1, \ldots, a_n\) and the second containing
the \(p-n\) elements \(a_{n+1}, \ldots a_p\).

There are \(q\) elements \(b_j\).
The argument b_s should be a pair of lists, the first containing the
\(m\) elements \(b_1, \ldots, b_m\) and the second containing
the \(q-m\) elements \(b_{m+1}, \ldots b_q\).

The implicit tuple \((m, n, p, q)\) constitutes the order or degree of the
Meijer G-function, and is determined by the lengths of the coefficient
vectors. Confusingly, the indices in this tuple appear in a different order
from the coefficients, but this notation is standard. The many examples
given below should hopefully clear up any potential confusion.

Algorithm

The Meijer G-function is evaluated as a combination of hypergeometric series.
There are two versions of the function, which can be selected with
the optional series argument.

series=1 uses a sum of \(m\)\(\,_pF_{q-1}\) functions of \(z\)

series=2 uses a sum of \(n\)\(\,_qF_{p-1}\) functions of \(1/z\)

The default series is chosen based on the degree and \(|z|\) in order
to be consistent with Mathematica’s. This definition of the Meijer G-function
has a discontinuity at \(|z| = 1\) for some orders, which can
be avoided by explicitly specifying a series.

where, for direct convergence, \(A = B\) and \(|z| = 1\), although a
regularized sum exists more generally by considering the
bilateral series as a sum of two ordinary hypergeometric
functions. In order for the series to make sense, none of the
parameters may be integers.

where \((a) = (a_1,\ldots,a_r)\), \((b) = (b_1,\ldots,b_s)\) and where
\(P\) and \(Q\) are products of rising factorials such as \((a_j)_n\) or
\((a_j)_{m+n}\). \(P\) and \(Q\) are specified in the form of dicts, with
the \(m\) and \(n\) dependence as keys and parameter lists as values.
The supported rising factorials are given in the following table
(note that only a few are supported in \(Q\)):

More generally, hyper2d() can evaluate any of the 34 distinct
convergent second-order (generalized Gaussian) hypergeometric
series enumerated by Horn, as well as the Kampe de Feriet
function.

The series is computed by rewriting it so that the inner
series (i.e. the series containing \(n\) and \(y\)) has the form of an
ordinary generalized hypergeometric series and thereby can be
evaluated efficiently using hyper(). If possible,
manually swapping \(x\) and \(y\) and the corresponding parameters
can sometimes give better results.

Examples

Two separable cases: a product of two geometric series, and a
product of two Gaussian hypergeometric functions: