J3/05-268r2
To: J3
From: Dan Nagle
Subject: libm math functions
Date: 2005 November 9
At Delft, it was decided to pursue the libm procedures.
This paper attempts to provide edits to do so.
The specifications are in 05-132r2, pursuant to J3-038.
In short, this paper provides Fortran standard names
for some procedures already existing in the C language math library
as specified by C99, POSIX, OSF and the SV and BSD implementations;
it does not specify wholly new procedures. These procedures
are being considered for inclusion in C++08, where they are not
already a part of C++.
As Van has remarked, and apparently resulting from the name-changing
at 173, some of the edits reference the wrong lines. This version
attempts to repair that error.
Specification: Add subsections to Section 13 detailing
the Fortran names for these procedures from the C libm:
j0, j1, jn, y0, y1, yn, erf, erfc, hypot, tgamma, lgamma.
(Some of the C names should not be used due
to the common use, in Fortran, of names such as j0 etc.)
The functions are (the C names):
Bessel functions (j0, j1, jn, y0, y1, yn)
Error functions (erf, erfc)
Hypotenuse (hypot)
Gamma and log gamma (tgamma, lgamma)
The detailed mathematical specification of these
procedures is given in the references above.
The intention is to allow the vendor to use
the procedure supplied by libm, so the exact
specification is left to libm, which is most likely
what the applications programmer wants.
The generic names proposed are:
BESSEL_J0
BESSEL_J1
BESSEL_JN
BESSEL_Y0
BESSEL_Y1
BESSEL_YN
ERF
ERFC
GAMMA
HYPOT
LOG_GAMMA
Syntax:
There is no new syntax. The procedure names are as above.
The calling sequences are the same one- or two- argument sequences
as the C versions. Again, this is most likely the most useful
to applications programmers.
Edits:
[Add to the list 13.5.2]
[294:28+] Add
"BESSEL_J0
BESSEL_J1
BESSEL_JN
BESSEL_Y0
BESSEL_Y1
BESSEL_YN"
[294:30+] Add
"ERF
ERFC"
[294:31+] Add
"GAMMA
HYPOT"
[294:33+] Add
"LOG_GAMMA"
[In the following, section numbers of the form 13.7.x are used.
The intention is for the editor to insert the appropriate x.]
[306:13+] Add
"13.7.x BESSEL_J0 (X)
*Description.* Bessel function of the first kind
of order zero.
*Class.* Elemental function.
*Argument.* X shall be of type real.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the first kind of order zero.
*Example.* BESSEL_J0(1.0) has the value 0.765 (approximately).
13.7.x BESSEL_J1 (X)
*Description.* Bessel function of the first kind
of order one.
*Class.* Elemental function.
*Argument.* X shall be of type real.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the first kind of order one.
*Example.* BESSEL_J1(1.0) has the value 0.440 (approximately).
13.7.x BESSEL_JN (N,X)
*Description.* Bessel function of the first kind
of order N.
*Class.* Elemental function.
*Arguments.*
X shall be of type real.
N shall be of type integer and nonnegative.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the first kind of order N.
*Example.* BESSEL_JN(2, 1.0) has the value 0.115 (approximately).
13.7.x BESSEL_Y0 (X)
*Description.* Bessel function of the second kind
of order zero.
*Class.* Elemental function.
*Argument.* X shall be of type real.
Its value shall be greater than zero.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the second kind of order zero.
*Example.* BESSEL_Y0(1.0) has the value 0.088 (approximately).
13.7.x BESSEL_Y1 (X)
*Description.* Bessel function of the second kind
of order one.
*Class.* Elemental function.
*Argument.* X shall be of type real.
Its value shall be greater than zero.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the second kind of order one.
*Example.* BESSEL_Y1(1.0) has the value -0.781 (approximately).
13.7.x BESSEL_YN (N,X)
*Description.* Bessel function of the second kind
of order N.
*Class.* Elemental function.
*Arguments.*
X shall be of type real. Its value shall be
greater than zero.
N shall be of type integer and nonnegative.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the Bessel
function of the second kind of order N.
*Example.* BESSEL_YN(2, 1.0) has the value -1.651 (approximately)."
[315:24+] Add
"13.7.x ERF (X)
*Description.* error function.
*Class.* Elemental function.
*Argument.* X shall be of type real.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the
error function of X,
2 divided by sqrt(pi) times the integral
from 0 to x of exp( -t*t) dt.
*Example.* ERF(1.0) has the value 0.843 (approximately).
13.7.x ERFC (X)
*Description.* Complementary error function.
*Class.* Elemental function.
*Argument.* X shall be of type real.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the
complementary error function (that is, 1.0 - ERF(X))
of X.
*Example.* ERFC(1.0) has the value 0.157 (approximately)."
[317:10+] Add
"13.7.x GAMMA (X)
*Description.* Gamma function.
*Class.* Elemental function.
*Argument.* X shall be of type real. Its value
shall not be a negative integer or zero.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation
of the gamma function,
the integral from 0 to infinity
of exp( -t) t**( x - 1) dt.
*Example.* GAMMA(1.0) has the value 1.000 (approximately)."
[319:20+] Add
"13.7.x HYPOT (X,Y)
*Description.* Euclidean distance function
*Class.* Elemental function.
*Argument.*
X shall be of type real.
Y shall be of type real
with the same kind type parameter as X.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the
Euclidean distance sqrt( x**2 + y**2 ),
without undue overflow or underflow.
*Example.* HYPOT(2.0, 1.0) has the value 2.236 (approximately)."
[329:21+] Add
"13.7.x LOG_GAMMA (X)
*Description.* log gamma function.
*Class.* Elemental function.
*Argument.*
X shall be of type real. Its value
shall not be a negative integer or zero.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation of the
natural logarithm of the absolute value of the
gamma function.
*Example.* LOG_GAMMA(3.0) has the value 0.693 (approximately)."
History:
04-246r1
05-132r2
J3-038
05-248r3
05-268