J3/05-132r1
To: J3
From: Dan Nagle
Subject: libm math functions
Date: 2005 Jan 24
Most Fortran vendors also support C/C++ compilers,
or utilize C/C++ RTLs to supply low-level services.
The C/C++ libm contains a few mathematical routines
which would be of use to Fortran programs. Standardizing
names for these routines aids portability
of Fortran programs.
This is J3/04-246 at M167, where the Hate .. Love vote was 0 - 3 - 6 - 0
Number:
Title: C libm functions as Fortran intrinsics
Submitted By: J3
Status: For Consideration
References: C99 7.12 Mathematics page 211 et seq.
Unix Programmer's Manual, Volume 2, System calls
and Library Routines (3m)
Basic Functionality: Add the Bessel functions, hypot, and error functions
to the Fortran intrinsic function set
for real arguments.
Rationale: Fortran is mainly used for numerical problems, supplying
mathematical functions of proven utility will assist
Fortran is continuing as the premier mathematical programming
language in the world today.
Estimated Impact: The estimated impact at 167 was 4 on the John Reid scale.
These are proposed intrinsic functions, no other feature
is affected. Impact on vendors is minimal,
as most vendors support these functions anyway
for their C/C++ compilers.
Detailed Specification: Add subsections to Section 13 detailing
the Fortran names for these procedures. (The C names
should not be used due to the common usage, 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.
Since Fortran does not support the concept
of external variables, the signgam variable of lgamma
is represented here as an optional intent(out)
argument.
Possible Fortran names are in the proposed edits below.
Note that the edits are proposed to illustrate
the degree of difficulty of modifying the standard,
and to provide an example of the edits the above
specifications might require.
Possible edits are proposed:
[Add to the list 13.5.2]
BESSEL_J0
BESSEL_J1
BESSEL_JN
BESSEL_Y0
BESSEL_Y1
BESSEL_YN
COMP_ERROR_FUNC
ERROR_FUNC
GAMMA_FUNC
HYPOT
LOG_GAMMA_FUNC
[306:13+] Add
"13.7.15+ BESSEL_J0 (X)
*Description.* Bessel function of the first kind
of order zero.
*Class.* Elemental function.
*Argument.* X shall be of type real. Its value
shall satisfy the inequality X >= 0.
*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 the zeroth order of X.
13.7.15+ BESSEL_J1 (X)
*Description.* Bessel function of the first kind
of order one.
*Class.* Elemental function.
*Argument.* X shall be of type real. Its value
shall satisfy the inequality X >= 0.
*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 the first order of X.
13.7.15+ BESSEL_JN (N,X)
*Description.* Bessel function of the first kind
of order N.
*Class.* Elemental function.
*Arguments.*
X shall be of type real. Its value
shall satisfy the inequality X >= 0.
N shall be of type integer. Its value
shall satisfy the inequality N >= 0.
It shall be a scalar.
*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 the Nth order of X.
13.7.15+ 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 satisfy the inequality X > 0.
*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 the zeroth order of X.
13.7.15+ 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 satisfy the inequality X > 0.
*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 the first order of X.
13.7.15+ 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 satisfy the inequality X > 0.
N shall be of type integer. Its value
shall satisfy the inequality N >= 0.
It shall be a scalar.
*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 the Nth order of X."
[308:20+] Add
"COMP_ERROR_FUNC (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
complement (that is, 1.0 - ERROR_FUNC(X)) of the
error function, ERROR_FUNC(X)."
[315:24+] Add
"ERROR_FUNC (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,
({2} over {pi} times int {0} {x} exp( -t*t) dt)."
[317:10+] Add
"GAMMA_FUNC (X)
*Description.* Gamma function.
*Class.* Elemental function.
*Argument.* X shall be of type real. Its value
shall satisfy the inequality X >= 0.
*Result Characteristics.* Same as X.
*Result Value.* The result has a value equal
to a processor-dependent approximation
of the gamma function,
(int {0} {inf} exp( -t) t**( x - 1) dt)."
[319:20+] Add
"HYPOT (X,Y)
*Description.* Euclidean distance function
*Class.* Elemental function.
*Argument.*
X shall be of type real.
Y shall be of type real. It shall
have the same kind 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*x + y*y ), taking
precautions against unwarranted overflows."
[329:21+] Add
"LOG_GAMMA_FUNC (X [, SIGNGAM])
*Description.* log gamma function.
*Class.* Elemental function.
*Argument.*
X shall be of type real. Its value
shall not be a negative integer.
SIGNGAM (optional) shall be of type real and
of the same type kind parameter
as X. It is an INTENT(OUT)
argument.
*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,
(int {0} {inf} exp( -t) t**( x - 1) dt).
If present, SIGNGAM is +1.0 if the GAMMA function
is positive, and -1.0 if the GAMMA function
is negative."
History: J3/04-246 at M167, J3/05-132 at M171