Evaluates the generalized hypergeometric function

where \((x)_n\) denotes the rising factorial (see rf()).

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 parameters can be any combination of integers, fractions, floats and complex numbers:

The \(\,_0F_0\) and \(\,_1F_0\) series are just elementary functions:

If any \(a_k\) coefficient is a nonpositive integer, the series terminates into a finite polynomial:

If any \(b_k\) is a nonpositive integer, the function is undefined (unless the series terminates before the division by zero occurs):

Except for polynomial cases, the radius of convergence \(R\) of the hypergeometric series is either \(R = \infty\) (if \(p \le q\)), \(R = 1\) (if \(p = q+1\)), or \(R = 0\) (if \(p > q+1\)).

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

Near \(z = 1\) with noninteger parameters:

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.

Evaluation may be aborted if convergence appears to be too slow. The optional maxterms (limiting the number of series terms) and maxprec (limiting the internal precision) keyword arguments can be used to control evaluation:

Additional options include force_series (which forces direct use of a hypergeometric series even if another evaluation method might work better) and asymp_tol which controls the target tolerance for using asymptotic series.

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.

With the following magnitude of argument, the asymptotic series for \(\,_3F_1\) gives only a few digits. Using Borel summation, hyper can produce a value with full accuracy:

Note that with the positive \(z\) value, there is a complex part in the correct result, which falls below the tolerance of the asymptotic series.

By default, a parameter that appears in both a_s and b_s will be removed unless it is a nonpositive integer. This generally speeds up evaluation by producing a hypergeometric function of lower order. This optimization can be disabled by passing eliminate=False.

If a nonpositive integer \(-n\) appears in both a_s and b_s, this parameter cannot be unambiguously removed since it creates a term 0 / 0. In this case the hypergeometric series is understood to terminate before the division by zero occurs. This convention is consistent with Mathematica. An alternative convention of eliminating the parameters can be toggled with eliminate_all=True: