PDF version (NAG web site
, 64-bit version, 64-bit version)
NAG Toolbox: nag_specfun_1f1_real_scaled (s22bb)
Purpose
nag_specfun_1f1_real_scaled (s22bb) returns a value for the confluent hypergeometric function , with real parameters and and real argument . The solution is returned in the scaled form . This function is sometimes also known as Kummer's function .
Syntax
Description
nag_specfun_1f1_real_scaled (s22bb) returns a value for the confluent hypergeometric function , with real parameters and and real argument , in the scaled form , where is the real scaled component and is the integer power of two scaling. This function is unbounded or not uniquely defined for equal to zero or a negative integer.
The confluent hypergeometric function is defined by the confluent series,
where
is the rising factorial of
.
is a solution to the second order ODE (Kummer's Equation):
Given the parameters and argument , this function determines a set of safe values and selects an appropriate algorithm to accurately evaluate the functions . The result is then used to construct the solution to the original problem using, where necessary, recurrence relations and/or continuation.
For improved precision in the final result, this function accepts and split into an integral and a decimal fractional component. Specifically , where and is integral. is similarly deconstructed.
Additionally, an artificial bound, is placed on the magnitudes of , and to minimize the occurrence of overflow in internal calculations. , where . It should, however, not be assumed that this function will produce an accurate result for all values of , and satisfying this criterion.
Please consult the
NIST Digital Library of Mathematical Functions or the companion
(2010) for a detailed discussion of the confluent hypergeometric 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:
– double scalar
-
, the nearest integer to , satisfying .
- 2:
– double scalar
-
, the signed decimal remainder satisfying and .
Constraint:
.
Note: if
,
will be used, where
is the
machine precision as returned by
nag_machine_precision (x02aj).
- 3:
– double scalar
-
, the nearest integer to , satisfying .
Constraints:
- ;
- ;
- if , .
- 4:
– double scalar
-
, the signed decimal remainder satisfying and .
Constraint:
.
Note: if
,
will be used, where
is the
machine precision as returned by
nag_machine_precision (x02aj).
- 5:
– double scalar
-
The argument of the function.
Constraint:
.
Optional Input Parameters
None.
Output Parameters
- 1:
– double scalar
-
, the scaled real component of the solution satisfying
.
Note: if overflow occurs upon completion, as indicated by , the value of returned may still be correct. If overflow occurs in a subcalculation, as indicated by , this should not be assumed.
- 2:
– int64int32nag_int scalar
-
, the scaling power of two, satisfying
.
Note: if overflow occurs upon completion, as indicated by
, then
, where
is the largest representable integer (see
nag_machine_integer_max (x02bb)). If overflow occurs during a subcalculation, as indicated by
,
may or may not be greater than
. In either case,
will have been returned.
- 3:
– int64int32nag_int scalar
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
-
Underflow occurred during the evaluation of .
The returned value may be inaccurate.
- W
-
On completion, overflow occurred in the evaluation of .
- W
-
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
-
-
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
-
-
Overflow occurred in a subcalculation of .
The answer may be completely incorrect.
-
-
Constraint: .
-
-
Constraint: .
-
-
Constraint: .
-
-
Constraint: .
-
-
On entry.
is undefined when is zero or a negative integer.
-
-
Constraint: .
-
-
Constraint: .
-
-
Constraint: .
-
An unexpected error has been triggered by this routine. Please
contact
NAG.
-
Your licence key may have expired or may not have been installed correctly.
-
Dynamic memory allocation failed.
Accuracy
In general, if
, the value of
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
is made internally using equation
(1). If the magnitude of
is sufficiently large a
nonzero
ifail
will be returned. Specifically,
|
|
|
|
|
|
A further estimate of the residual can be constructed using equation
(1), and the differential identity,
This estimate is however dependent upon the error involved in approximating and .
Further Comments
The values of and are implementation dependent. In most cases, if , and will be returned, and if is finite, the fractional component will be bound by , with chosen accordingly.
The values returned in
frm (
) and
scm (
) may be used to explicitly evaluate
, and may also be used to evaluate products and ratios of multiple values of
as follows,
Example
This example evaluates the confluent hypergeometric function at two points in scaled form using nag_specfun_1f1_real_scaled (s22bb), and subsequently calculates their product and ratio without having to explicitly construct .
Open in the MATLAB editor:
s22bb_example
function s22bb_example
fprintf('s22bb example results\n\n');
n = 2;
delta = 1e-4;
amod = [-10 -10]; arem = [ delta -delta];
bmod = [ 30 30]; brem = [-delta delta];
x = 25;
fprintf(' a b x frm scm M(a,b,x)\n');
for j = 1:n
[frmv(j), scmv(j), ifail] = s22bb( ...
amod(j), arem(j), bmod(j), brem(j), x);
a = amod(j) + arem(j);
b = bmod(j) + brem(j);
fprintf('%9.3f %9.3f %9.3f %11.3e %5d ', a, b, x, frmv(j), scmv(j));
print_scale(frmv(j), scmv(j));
end
frm = prod(frmv);
scm = sum(scmv);
fprintf('\nSolution product %24.3e %5d ', frm, scm);
print_scale(frm, scm);
if frmv(2) ~= 0
frm = frmv(1)/frmv(2);
scm = scmv(1) - scmv(2);
fprintf('\nSolution ratio %24.3e %5d ', frm, scm);
print_scale(frm, scm);
end
function print_scale(frm, scm)
if scm < x02bl
scale = frm*2^double(scm);
fprintf('%11.3e\n', scale);
else
fprintf(' Not representable\n');
end
s22bb example results
a b x frm scm M(a,b,x)
-10.000 30.000 25.000 -7.733e-01 -15 -2.360e-05
-10.000 30.000 25.000 -7.732e-01 -15 -2.360e-05
Solution product 5.979e-01 -30 5.568e-10
Solution ratio 1.000e+00 0 1.000e+00
PDF version (NAG web site
, 64-bit version, 64-bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015