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