naginterfaces.library.specfun.hyperg_gauss_real_scaled¶

naginterfaces.library.specfun.hyperg_gauss_real_scaled(ani, adr, bni, bdr, cni, cdr, x)[source]¶

hyperg_gauss_real_scaled returns a value for the Gauss hypergeometric function $_{2} F_{1} (a, b; c; x)$ for real parameters $a, b$ and $c$ , and real argument $x$ . The result is returned in the scaled form $_{2} F_{1} (a, b; c; x) = f_{f r} \times 2^{f_{s c}}$ .

For full information please refer to the NAG Library document for s22bf

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/s/s22bff.html

Parameters

anifloat: $a_{i}$ , the nearest integer to $a$ , satisfying $a_{i} = a - a_{r}$ .
adrfloat: $a_{r}$ , the signed decimal remainder satisfying $a_{r} = a - a_{i}$ and $| a_{r} | \leq 0.5$ .
bnifloat: $b_{i}$ , the nearest integer to $b$ , satisfying $b_{i} = b - b_{r}$ .
bdrfloat: $b_{r}$ , the signed decimal remainder satisfying $b_{r} = b - b_{i}$ and $| b_{r} | \leq 0.5$ .
cnifloat: $c_{i}$ , the nearest integer to $c$ , satisfying $c_{i} = c - c_{r}$ .
cdrfloat: $c_{r}$ , the signed decimal remainder satisfying $c_{r} = c - c_{i}$ and $| c_{r} | \leq 0.5$ .
xfloat: The argument $x$ .

Returns

frffloat: $f_{f r}$ , the scaled real component of the solution satisfying $f_{f r} =_{2} F_{1} (a, b; c; x) \times 2^{- f_{s c}}$ , i.e., $_{2} F_{1} (a, b; c; x) = f_{f r} \times 2^{f_{s c}}$ . See Further Comments for the behaviour of $f_{f r}$ when a finite or non-finite answer is returned.
scfint: $f_{s c}$ , the scaling power of two, satisfying $f_{s c} = l o g 2 (\frac{_{2} F_{1} (a, b; c; x)}{f_{f r}})$ , i.e., $_{2} F_{1} (a, b; c; x) = f_{f r} \times 2^{f_{s c}}$ . See Further Comments for the behaviour of $f_{s c}$ when a non-finite answer is returned.

Raises

NagValueError

(errno $3$ )

All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.

$Relative residual = ⟨ v a l u e ⟩$ .

(errno $4$ )

On entry, $x = ⟨ v a l u e ⟩$ , $c = ⟨ v a l u e ⟩$ , $a + b = ⟨ v a l u e ⟩$ .

$_{2} F_{1} (a, b; c; 1)$ is infinite in the case $c \leq a + b$ .

(errno $6$ )

Overflow occurred in a subcalculation of $_{2} F_{1} (a, b; c; x)$ . The answer may be completely incorrect.

(errno $9$ )

An internal calculation has resulted in an undefined result.

(errno $11$ )

On entry, $a n i$ does not satisfy $| a n i | \leq arbnd = ⟨ v a l u e ⟩$ .

(errno $13$ )

$a n i$ is non-integral.

On entry, $a n i = ⟨ v a l u e ⟩$ .

Constraint: $a n i = ⌊ a n i ⌋$ .

(errno $21$ )

On entry, $a d r$ does not satisfy $| a d r | \leq 0.5$ .

(errno $31$ )

On entry, $b n i$ does not satisfy $| b n i | \leq arbnd = ⟨ v a l u e ⟩$ .

(errno $33$ )

$b n i$ is non-integral.

On entry, $b n i = ⟨ v a l u e ⟩$ .

Constraint: $b n i = ⌊ b n i ⌋$ .

(errno $41$ )

On entry, $b d r$ does not satisfy $| b d r | \leq 0.5$ .

(errno $51$ )

On entry, $c n i$ does not satisfy $| c n i | \leq arbnd = ⟨ v a l u e ⟩$ .

(errno $52$ )

On entry, $c = c n i + c d r = ⟨ v a l u e ⟩$ .

$_{2} F_{1} (a, b; c; x)$ is undefined when $c$ is zero or a negative integer.

(errno $53$ )

$c n i$ is non-integral.

On entry, $c n i = ⟨ v a l u e ⟩$ .

Constraint: $c n i = ⌊ c n i ⌋$ .

(errno $61$ )

On entry, $c d r$ does not satisfy $| c d r | \leq 0.5$ .

(errno $71$ )

On entry, $x$ does not satisfy $| x | \leq arbnd = ⟨ v a l u e ⟩$ .

(errno $72$ )

On entry, $x = ⟨ v a l u e ⟩$ .

In general, $_{2} F_{1} (a, b; c; x)$ is not real valued when $x > 1$ .

Warns

NagAlgorithmicWarning

(errno $1$ )

Underflow occurred during the evaluation of $_{2} F_{1} (a, b; c; x)$ . The returned value may be inaccurate.

(errno $2$ )

All approximations have completed, and the final residual estimate indicates some precision may have been lost.

$Relative residual = ⟨ v a l u e ⟩$ .

(errno $5$ )

On completion, overflow occurred in the evaluation of $_{2} F_{1} (a, b; c; x)$ .

Notes

hyperg_gauss_real_scaled returns a value for the Gauss hypergeometric function $_{2} F_{1} (a, b; c; x)$ for real parameters $a$ , $b$ and $c$ , and for real argument $x$ .

The Gauss hypergeometric function is a solution to the hypergeometric differential equation,

x (1 - x) \frac{d^{2} f}{d x^{2}} + (c - (a + b + 1) x) \frac{d f}{d x} - a b f = 0 .

For $| x | < 1$ , it may be defined by the Gauss series,

_{2} F_{1} (a, b; c; x) = \infty \sum 0 \frac{{(a)}_{s} {(b)}_{s}}{{(c)}_{s} s!} x^{s} = 1 + \frac{a b}{c} x + \frac{a (a + 1) b (b + 1)}{c (c + 1) 2!} x^{2} + \dots,

where ${(a)}_{s} = 1 (a) (a + 1) (a + 2) \dots (a + s - 1)$ is the rising factorial of $a$ . $_{2} F_{1} (a, b; c; x)$ is undefined for $c = 0$ or $c$ a negative integer.

For $| x | < 1$ , the series is absolutely convergent and $_{2} F_{1} (a, b; c; x)$ is finite.

For $x < 1$ , linear transformations of the form,

_{2} F_{1} (a, b; c; x) = C_{1} (a_{1}, b_{1}, c_{1}, x_{1})_{2} F_{1} (a_{1}, b_{1}; c_{1}; x_{1}) + C_{2} (a_{2}, b_{2}, c_{2}, x_{2})_{2} F_{1} (a_{2}, b_{2}; c_{2}; x_{2})

exist, where $x_{1}$ , $x_{2} \in (0, 1]$ . $C_{1}$ and $C_{2}$ are real valued functions of the parameters and argument, typically involving products of gamma functions. When these are degenerate, finite limiting cases exist. Hence for $x < 0$ , $_{2} F_{1} (a, b; c; x)$ is defined by analytic continuation, and for $x < 1$ , $_{2} F_{1} (a, b; c; x)$ is real and finite.

For $x = 1$ , the following apply:

If $c > a + b$ , $_{2} F_{1} (a, b; c; 1) = \frac{Γ (c) Γ (c - a - b)}{Γ (c - a) Γ (c - b)}$ , and hence is finite. Solutions also exist for the degenerate cases where $c - a$ or $c - b$ are negative integers or zero.

If $c \leq a + b$ , $_{2} F_{1} (a, b; c; 1)$ is infinite, and the sign of $_{2} F_{1} (a, b; c; 1)$ is determinable as $x$ approaches $1$ from below.

In the complex plane, the principal branch of $_{2} F_{1} (a, b; c; z)$ is taken along the real axis from $x = 1.0$ increasing. $_{2} F_{1} (a, b; c; z)$ is multivalued along this branch, and for real parameters $a, b$ and $c$ is typically not real valued. As such, this function will not compute a solution when $x > 1$ .

The solution strategy used by this function is primarily dependent upon the value of the argument $x$ . Once trivial cases and the case $x = 1.0$ are eliminated, this proceeds as follows.

For $0 < x \leq 0.5$ , sets of safe parameters ${α_{i, j}, β_{i, j}, ζ_{i, j}, χ_{j} | 1 \leq j \leq 2 |, 1 \leq i \leq 4}$ are determined, such that the values of $_{2} F_{1} (a_{j}, b_{j}; c_{j}; x_{j})$ required for an appropriate transformation of the type (3) may be calculated either directly or using recurrence relations from the solutions of $_{2} F_{1} (α_{i, j}, β_{i, j}; ζ_{i, j}; χ_{j})$ . If $c$ is positive, then only transformations with $C_{2} = 0.0$ will be used, implying only $_{2} F_{1} (a_{1}, b_{1}; c_{1}; x_{1})$ will be required, with the transformed argument $x_{1} = x$ . If $c$ is negative, in some cases a transformation with $C_{2} \neq 0.0$ will be used, with the argument $x_{2} = 1.0 - x$ . The function then cycles through these sets until acceptable solutions are generated. If no computation produces an accurate answer, the least inaccurate answer is selected to complete the computation. See Accuracy.

For $0.5 < x < 1.0$ , an identical approach is first used with the argument $x$ . Should this fail, a linear transformation resulting in both transformed arguments satisfying $x_{j} = 1.0 - x$ is employed, and the above strategy for $0 < x \leq 0.5$ is utilized on both components. Further transformations in these sub-computations are however, limited to single terms with no argument transformation.

For $x < 0$ , a linear transformation mapping the argument $x$ to the interval $(0, 0.5]$ is first employed. The strategy for $0 < x \leq 0.5$ is then used on each component, including possible further two term transforms. To avoid some degenerate cases, a transform mapping the argument $x$ to $[0.5, 1)$ may also be used.

For improved precision in the final result, this function accepts $a, b$ and $c$ split into an integral and a decimal fractional component. Specifically, $a = a_{i} + a_{r}$ , where $| a_{r} | \leq 0.5$ and $a_{i} = a - a_{r}$ is integral. The other parameters $b$ and $c$ are similarly deconstructed.

In addition to the above restrictions on $c$ and $x$ , an artificial bound, arbnd, is placed on the magnitudes of $a, b, c$ and $x$ to minimize the occurrence of overflow in internal calculations, particularly those involving real to integer conversions. $arbnd = 0.0001 \times I_{m a x}$ , where $I_{m a x}$ is the largest machine integer (see machine.integer_max). It should however, not be assumed that this function will produce accurate answers for all values of $a, b, c$ and $x$ satisfying this criterion.

This function also tests for non-finite values of the parameters and argument on entry, and assigns non-finite values upon completion if appropriate. See Further Comments and submodule ieee.

Please consult the NIST Digital Library of Mathematical Functions for a detailed discussion of the Gauss hypergeometric function including special cases, transformations, relations and asymptotic approximations.

References

NIST Digital Library of Mathematical Functions

Pearson, J, 2009, Computation of hypergeometric functions, MSc Dissertation, Mathematical Institute, University of Oxford

NAG and Python

Return to Front

naginterfaces.library.specfun.hyperg_gauss_real_scaled¶

naginterfaces.library.specfun.hyperg_​gauss_​real_​scaled¶

naginterfaces.library.specfun.hyperg_gauss_real_scaled¶