naginterfaces.library.specfun.hyperg_​confl_​real_​scaled

naginterfaces.library.specfun.hyperg_confl_real_scaled(ani, adr, bni, bdr, x)

hyperg_confl_real_scaled returns a value for the confluent hypergeometric function ${}_1{F}_1(a;b;x)$, with real parameters $a$ and $b$ and real argument $x$. The solution is returned in the scaled form ${}_1{F}_1(a;b;x)=m_f\times 2^{m_s}$. This function is sometimes also known as Kummer’s function $M(a,b,x)$.

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/s/s22bbf.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 $\left|a_r\right|\le 0.5$.

Note: if $\left|adr\right|<100.0ϵ$, $a_r=0.0$ will be used, where $ϵ$ is the machine precision as returned by machine.precision.

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 $\left|b_r\right|\le 0.5$.

Note: if $|bdr-adr|<100.0ϵ$, $a_r=b_r$ will be used, where $ϵ$ is the machine precision as returned by machine.precision.

xfloat

The argument $x$ of the function.

Returns

frmfloat

$m_f$, the scaled real component of the solution satisfying $m_f=M(a,b,x)\times 2^{-m_s}$.

Note: if overflow occurs upon completion, as indicated by $errno$ = 2, the value of $m_f$ returned may still be correct. If overflow occurs in a subcalculation, as indicated by $errno$ = 5, this should not be assumed.

scmint

$m_s$, the scaling power of two, satisfying $m_s=log2\left(\frac{M(a,b,x)}{m_f}\right)$.

Note: if overflow occurs upon completion, as indicated by $errno$ = 2, then $m_s\ge I_{max}$, where $I_{max}$ is the largest representable integer (see machine.integer_max). If overflow occurs during a subcalculation, as indicated by $errno$ = 5, $m_s$ may or may not be greater than $I_{max}$. In either case, $scm=\text{machine.integer\_max}$ will have been returned.

Raises

NagValueError

(errno $4$)

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

Relative residual $=⟨value⟩$.

(errno $5$)

Overflow occurred in a subcalculation of $M(a,b,x)$.

The answer may be completely incorrect.

(errno $11$)

On entry, $ani=⟨value⟩$.

Constraint: $\left|ani\right|\le \text{arbnd}=⟨value⟩$.

(errno $13$)

$ani$ is non-integral.

On entry, $ani=⟨value⟩$.

Constraint: $ani=\lfloor ani\rfloor$.

(errno $21$)

On entry, $adr=⟨value⟩$.

Constraint: $\left|adr\right|\le 0.5$.

(errno $31$)

On entry, $bni=⟨value⟩$.

Constraint: $\left|bni\right|\le \text{arbnd}=⟨value⟩$.

(errno $32$)

On entry, $b=bni+bdr=⟨value⟩$.

$M(a,b,x)$ is undefined when $b$ is zero or a negative integer.

(errno $33$)

$bni$ is non-integral.

On entry, $bni=⟨value⟩$.

Constraint: $bni=\lfloor bni\rfloor$.

(errno $41$)

On entry, $bdr=⟨value⟩$.

Constraint: $\left|bdr\right|\le 0.5$.

(errno $51$)

On entry, $x=⟨value⟩$.

Constraint: $\left|x\right|\le \text{arbnd}=⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $1$)

Underflow occurred during the evaluation of $M(a,b,x)$.

The returned value may be inaccurate.

(errno $2$)

On completion, overflow occurred in the evaluation of $M(a,b,x)$.

(errno $3$)

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

Relative residual $=⟨value⟩$.

Notes

hyperg_confl_real_scaled returns a value for the confluent hypergeometric function ${}_1{F}_1(a;b;x)$, with real parameters $a$ and $b$ and real argument $x$, in the scaled form ${}_1{F}_1(a;b;x)=m_f\times 2^{m_s}$, where $m_f$ is the real scaled component and $m_s$ is the integer power of two scaling. This function is unbounded or not uniquely defined for $b$ equal to zero or a negative integer.

The confluent hypergeometric function is defined by the confluent series,

$${}_1{F}_1(a;b;x)=M(a,b,x)=\sum _0^{\infty }\frac{{\left(a\right)}_s{x}^s}{{\left(b\right)}_{s}s!}=1+\frac{a}{b}x+\frac{a(a+1)}{b(b+1)2!}{x}^2+\cdots$$

where ${\left(a\right)}_s=1\left(a\right)(a+1)(a+2)\dots (a+s-1)$ is the rising factorial of $a$. $M(a,b,x)$ is a solution to the second order ODE (Kummer’s Equation):

$$x\frac{d^{2}M}{d{x}^2}+(b-x)\frac{dM}{dx}-aM=0\text{.}$$

Given the parameters and argument $(a,b,x)$, this function determines a set of safe values $\{({\alpha }_i,{\beta }_i,{\zeta }_i)|i\le 2\}$ and selects an appropriate algorithm to accurately evaluate the functions $M_i({\alpha }_i,{\beta }_i,{\zeta }_i)$. The result is then used to construct the solution to the original problem $M(a,b,x)$ using, where necessary, recurrence relations and/or continuation.

For improved precision in the final result, this function accepts $a$ and $b$ split into an integral and a decimal fractional component. Specifically $a=a_i+a_r$, where $\left|a_r\right|\le 0.5$ and $a_i=a-a_r$ is integral. $b$ is similarly deconstructed.

Additionally, an artificial bound, $\text{arbnd}$ is placed on the magnitudes of $a_i$, $b_i$ and $x$ to minimize the occurrence of overflow in internal calculations. $\text{arbnd}=0.0001\times I_{max}$, where $I_{max}=\text{machine.integer\_max}$. It should, however, not be assumed that this function will produce an accurate result for all values of $a_i$, $b_i$ and $x$ satisfying this criterion.

Please consult the NIST Digital Library of Mathematical Functions for a detailed discussion of the confluent 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