hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_specfun_1f1_real (s22ba)

Purpose

nag_specfun_1f1_real (s22ba) returns a value for the confluent hypergeometric function 1F1 (a ; b ; x) F 1 1 (a;b;x)  with real parameters aa, bb and xx. This function is sometimes also known as Kummer's function M(a,b,x)M(a,b,x).

Syntax

[m, ifail] = s22ba(a, b, x)
[m, ifail] = nag_specfun_1f1_real(a, b, x)

Description

nag_specfun_1f1_real (s22ba) returns a value for the confluent hypergeometric function 1F1 (a ; b ; x) F1 1 (a;b;x)  with real parameters aa, bb and xx. This function is unbounded or not uniquely defined for bb equal to zero or a negative integer.
The associated function nag_specfun_1f1_real_scaled (s22bb) performs the same operations, but returns MM in the scaled form M = mf × 2msM=mf×2ms to allow calculations to be performed when MM is not representable as a single working precision number. It also accepts the parameters aa and bb as summations of an integer and a decimal fraction, giving higher accuracy when aa or bb are close to an integer. In such cases, nag_specfun_1f1_real_scaled (s22bb) should be used when high accuracy is required.
The confluent hypergeometric function is defined by the confluent series
1F1(a ; b ; x) = M(a,b,x) = ( (a)s xs )/( (b)s s! ) = 1 + (a)/b x + ( a(a + 1) )/( b(b + 1) 2! )x2 +
s = 0
F1 1 (a;b;x) = M(a,b,x) = s=0 (a)s xs (b)s s! = 1 + a b x + a(a+1) b(b+1) 2! x2 +
where (a)s = 1 (a) (a + 1) (a + 2) (a + s1) (a)s = 1 (a) (a+1) (a+2) (a+s-1)  is the rising factorial of aa. M(a,b,x) M(a,b,x)  is a solution to the second order ODE (Kummer's Equation):
x (d2M)/(dx2) + (bx) (dM)/(dx) a M = 0 .
x d2M dx2 + (b-x) dM dx - a M = 0 .
(1)
Given the parameters (a,b,x) (a,b,x) , this function determines a set of safe parameters {(αi,βi,ζi)i2} { (αi,βi,ζi) i2 }  and selects an appropriate algorithm to accurately evaluate the functions Mi (αi,βi,ζi) Mi (αi,βi,ζi) . The result is then used to construct the solution to the original problem M(a,b,x) M(a,b,x)  using, where necessary, recurrence relations and/or continuation.
Additionally, an artificial bound, arbndarbnd is placed on the magnitudes of aa, bb and xx to minimize the occurrence of overflow in internal calculations. arbnd = 0.0001 × Imax arbnd = 0.0001 × Imax , where Imax = x02bbImax=x02bb. It should, however, not be assumed that this function will produce an accurate result for all values of aa, bb and xx satisfying this criterion.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the confluent hypergeoemtric function including special cases, transformations, relations and asymptotic approximations.

References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

Parameters

Compulsory Input Parameters

1:     a – double scalar
The parameter aa of the function.
Constraint: |a|arbnd|a|arbnd.
2:     b – double scalar
The parameter bb of the function.
Constraint: |b|arbnd|b|arbnd.
3:     x – double scalar
The argument xx of the function.
Constraint: |x|arbnd|x|arbnd.

Optional Input Parameters

None.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     m – double scalar
The solution M(a,b,x)M(a,b,x).
Note: if overflow occurs upon completion, as indicated by ifail = 2ifail=2, |M(a,b,x)||M(a,b,x)| may be assumed to be too large to be representable. m will be returned as ± Rmax±Rmax, where RmaxRmax is the largest representable real number (see nag_machine_real_largest (x02al)). The sign of m should match the sign of M(a,b,x)M(a,b,x). If overflow occurs during a subcalculation, as indicated by ifail = 5ifail=5, the sign may be incorrect, and the true value of M(a,b,x)M(a,b,x) may or may not be greater than RmaxRmax. In either case it is advisable to subsequently use nag_specfun_1f1_real_scaled (s22bb).
2:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W ifail = 1ifail=1
Underflow occurred during the evaluation of M(a,b,x)M(a,b,x).
The returned value may be inaccurate.
  ifail = 2ifail=2
On completion, overflow occurred in the evaluation of M(a,b,x)M(a,b,x).
  ifail = 3ifail=3
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
  ifail = 4ifail=4
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
  ifail = 5ifail=5
Overflow occurred in a subcalculation of M(a,b,x)M(a,b,x).
The answer may be completely incorrect.
  ifail = 11ifail=11
Constraint: .
  ifail = 31ifail=31
Constraint: .
  ifail = 32ifail=32
On entry.
M(a,b,x)M(a,b,x) is undefined when bb is zero or a negative integer.
  ifail = 51ifail=51
Constraint: .

Accuracy

In general, if ifail = 0ifail=0, the value of MM may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not under or overflow, an error estimate resres is made internally using equation (1). If the magnitude of resres is sufficiently large, a nonzero ifail will be returned. Specifically,
ifail = 0ifail=0 res1000εres1000ε
ifail = 3ifail=3 1000 ε < res0.11000ε<res0.1
ifail = 4ifail=4 res > 0.1res>0.1
A further estimate of the residual can be constructed using equation (1), and the differential identity,
( d M(a,b,x) )/(dx) = a/b M (a + 1,b + 1,x) ,
( d2 M(a,b,x) )/(dx2) = (a(a + 1))/(b(b + 1)) M (a + 2,b + 2,x) .
d M(a,b,x) dx = ab M (a+1,b+1,x) , d2 M(a,b,x) dx2 = a(a+1) b(b+1) M (a+2,b+2,x) .
This estimate is however dependent upon the error involved in approximating M (a + 1,b + 1,x) M (a+1,b+1,x)  and M (a + 2,b + 2,x) M (a+2,b+2,x) .
Furthermore, the accuracy of the solution, and the error estimate, can be dependent upon the accuracy of the decimal fraction of the input parameters aa and bb. For example, if b = bi + br = 100 + 1.0e−6b=bi+br=100+1.0e−6, then on a machine with 1616 decimal digits of precision, the internal calculation of brbr will only be accurate to 88 decimal places. This can subsequently pollute the final solution by several decimal places without affecting the residual estimate as greatly. Should you require higher accuracy in such regions, then you should use nag_specfun_1f1_real_scaled (s22bb), which requires you to supply the correct decimal fraction.

Further Comments

None.

Example

function nag_specfun_1f1_real_example
a = 13.6;
b = 14.2;
x = [-2.5; -0.9; -0.25; -0.01; 0.1; 0.5; 0.75];

m     = zeros(numel(x), 1);
ifail = zeros(numel(x), 1, 'int64');
for i = 1:numel(x)
  [m(i), ifail(i)] = nag_specfun_1f1_real(a, b, x(i));
end
fprintf('\n       x       M(a,b,x)       ifail\n');
fprintf('%10.2f  %13.5e  %6d\n', vertcat(x', m', double(ifail')));
 

       x       M(a,b,x)       ifail
     -2.50    9.20723e-02       0
     -0.90    4.22800e-01       0
     -0.25    7.87137e-01       0
     -0.01    9.90468e-01       0
      0.10    1.10053e+00       0
      0.50    1.61478e+00       0
      0.75    2.05246e+00       0

function s22ba_example
a = 13.6;
b = 14.2;
x = [-2.5; -0.9; -0.25; -0.01; 0.1; 0.5; 0.75];

m     = zeros(numel(x), 1);
ifail = zeros(numel(x), 1, 'int64');
for i = 1:numel(x)
  [m(i), ifail(i)] = s22ba(a, b, x(i));
end
fprintf('\n       x       M(a,b,x)       ifail\n');
fprintf('%10.2f  %13.5e  %6d\n', vertcat(x', m', double(ifail')));
 

       x       M(a,b,x)       ifail
     -2.50    9.20723e-02       0
     -0.90    4.22800e-01       0
     -0.25    7.87137e-01       0
     -0.01    9.90468e-01       0
      0.10    1.10053e+00       0
      0.50    1.61478e+00       0
      0.75    2.05246e+00       0


PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013