J3/05-248r1 To: J3 From: Dan Nagle Subject: libm math functions Date: 2005 August 10 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. There is one straw vote which should be taken before details may be finalized, viz, how to handle the signgam external variable used by the libm C binding to return the sign of gamma when the log of abs( gamma) is computed. JoR chose to use a subroutine, say log_gamma_func(), which may be elemental and allow optional, intent( out) arguments. The design specified by earlier papers used an optional, intent(out) argument to the log_gamma function, which is not allowed if log_gamma() is to be a pure function. As a reminder, the specifications are: 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. (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. Edits would include adding to the list in 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 Syntax: No new syntax. The procedure names are as above. The calling sequences are the same one- or two- argument sequences as the C versions (modulo the outcome of the straw vote above). Edits: [7:35+] Add: "ISO 31-11:1992(E) Quantities and Units- Part 11: Mathematical signs and symbols for use in the physical sciences and technology." [Add to the list 13.5.2] [294:28+] Add "BESSEL_J0 BESSEL_J1 BESSEL_JN BESSEL_Y0 BESSEL_Y1 BESSEL_YN COMP_ERROR_FUNC" [294:30+] Add "ERROR_FUNC" [294:31+] Add "GAMMA_FUNC HYPOT" [294:33+] Add "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 divided by sqrt(pi) times the integral from 0 to x of 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, the integral from 0 to infinity of 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 , LOGGAMMA, [, SIGNGAM]) *Description.* log gamma function. *Class.* Elemental subroutine. *Argument.* X shall be of type real. Its value shall not be a negative integer. LOGGAMMA shall be of type real and of the same type kind parameter as X. It is an INTENT(OUT) argument. 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 LOGGAMMA has a value equal to a processor-dependent approximation of the natural logarithm of the absolute value of the gamma function, 2 divided by sqrt(pi) times the integral from 0 to x of exp( -t*t) dt." If present, SIGNGAM is +1.0 if the GAMMA function is positive, and -1.0 if the GAMMA function is negative."