\documentclass[nocolor,memo]{j3}
\renewcommand{\hdate}{21 September 2005}
\renewcommand{\vers}{J3/05-264}
\usepackage{alltt}
\usepackage[fleqn]{amsmath}
\usepackage{lineno}
\usepackage{longtable}
\usepackage{xr}
\externaldocument{007}
\input pdftest
\begin{document}
\vspace{-10pt}
\begin{tabbing}
Subject: \hspace*{0.25in}\=Intrinsic math functions\\
From: \>Van Snyder\\
Reference: \>05-248r3\\
\end{tabbing}
\pagewiselinenumbers
\leftlinenumbers
\linenumbers*
\section{Introduction}
As specified in 05-248r3, the HYPOT function a is nearly useless, and
ERFC and LOG\_GAMMA are suboptimal.
\subsection{HYPOT}
The HYPOT function specified in 05-248r3 is nearly useless, since (1)
it's identical to CABS, and (2) the interesting function in any case is
the one that computes the $L_2$ norm of a vector of any length, not just
length 2. Instead of HYPOT we ought to add the NRM2 functions from the
BLAS, with the generic name TBD. Once one has CABS (or indeed NRM2) one
needs only a statement function to have a HYPOT spelling. Presumably, if
the length is given by an initialization expression, and happens to be
two, a decent processor will optimize NRM2 just as well as it would HYPOT
--- or maybe it won't if HYPOT isn't in the SPEC benchmark. Either HYPOT
or NRM2 can be done with SQRT(DOT\_PRODUCT(A,A)), but a carefully-done
$L_2$ norm function (e.g., the one in the BLAS) will not experience an
overflow in the calculation of an intermediate result unless the final
result overflows.
\subsection{ERFC}
The ERFC function specified in 05-248r3 is not the most useful
specification for that functionality. ERFC is asymptotic to
$\exp(-x^2)/(x \sqrt\pi)$, and as such underflows for $x > \approx 9$ in
IEEE single precision. The expression $\exp(x^2) \text{erfc}(x)$, which
doesn't underflow until $x > \text{HUGE}(x)/\sqrt\pi$, appears more
frequently in statistical calculations. Real math function libraries (as
opposed to libm) frequently include a ``scaled erfc'' function,
frequently called ERFCE, that computes $\exp(x^2) \text{erfc}(x)$. Where
carefully done, implementations of this function do not experience
overflow of intermediate or final results for any positive X, and
intermediate or final results underflow only for $x >
\text{HUGE}(x)/\sqrt\pi$. It \emph{is not} computed by computing
erfc$(x)$ and multiplying by $\exp(x^2)$, as a naive user might be
tempted to do --- especially if all we provide is the functionality
presently specified in 05-248r3. $\exp(x^2)$ would overflow for $x >
\approx 9$ in IEEE single precision, and erfc$(x)$ would underflow around
the same value, so multiplying the results of those functions would
produce nonsense for $x > \approx 9$.
\subsection{LOG\_GAMMA}
The LOG\_GAMMA subroutine defined in 05-248r3 will be cumbersome to use
in nearly all cases, i.e., when one knows $x > 0$. It would be better if
it were a function that computed $\log(|\Gamma(x)|)$. In the rare case
when one cares, one can get the sign of $\Gamma(x)$ as {\tt MERGE(1,
2*IAND(INT(-X),1)-1, X$>$0)} or .... There are two additional
alternatives: (1) An additional function that returns a complex result or
(2) a COMPLEX optional argument, whose value is required to be a logical
initialization expression, that causes LOG\_GAMMA to return a complex
result if it is present and true. If the result is complex the imaginary
part is zero if $\Gamma(x) > 0$, or $\pi$ if $\Gamma(x) < 0$ ---
remember $\text{Log}(-|x|)$ is just $\log(|x|) + i \pi$.
\section{Syntax}
No new syntax and no changes to existing syntax.
\edits{04-007}
\sep\mgpar{296:30+}[Insert into list of Mathematical functions in
13.5.2:]
\begin{insum}
\item[{ERFC~(X [, SCALED]) }] Complementary error function
\end{insum}
\sep\mgpar{296:33+}[Insert into list of Mathematical functions in
13.5.2:]
\begin{insum}
\item[{LOG\_GAMMA(X [, COMPLEX])}] Logarithm of Gamma function
\end{insum}
[or (if alternative definition below is selected):]
\begin{insum}
\item[{LOG\_GAMMA (X) }] Logarithm of Gamma function
\end{insum}
\sep\mgpar{299:7+}[Insert into list of Array reduction functions in
13.5.12:]
\begin{insum}
\item[{NORM2 (X) }] $L_2$ norm of an array
\end{insum}
%=========================================================================
\sep\mgpar{317:17+}[Insert after 13.7.5 EPSILON~(X):]
{\secfont\large 13.7.5$\frac12$ ERFC~(X [, SCALED])}
\desc{Complementary error function.}
\class{Elemental function.}
\arguments{}
\intrinarg{X}{shall be of type real.}
\intrinarg{SCALED}{(optional) shall be of type logical.}
\reschar{Same as X.}
\resvalue{}
\begin{incase}
\item If SCALED is absent or present with the value false, the value of
the result is a processor-dependent approximation to the complementary
error function, $\frac2{\sqrt\pi} \int_x^\infty \exp(-t^2) \text{d}t$.
\item if SCALED is present with the value true, the value of the result
is a processor-dependent approximation to the exponentially-scaled
complementary error function, $\exp(x^2) \frac2{\sqrt\pi} \int_x^\infty
\exp(-t^2) \text{d}t$.
\end{incase}
\examples{}
\begin{incase}
\item The value of ERFC(1.0) is 0.1572992070 (approximately).
\item The value of ERFC(20.0) is $0.5395865612\times 10^{-175}$
(approximately).
\item The value of ERFC(20.0,SCALED=.TRUE.) is 0.02817434874
(approximately).
\end{incase}
\begin{xnote}{13.8$\frac12$}
The complementary error function is asymptotic to $\exp(-x^2)/(x
\sqrt\pi)$. As such it underflows for $x > \approx 9$ when using
single-precision IEEE arithmetic. The exponentially-scaled complementary
error function is asymptotic to $1/(x \sqrt\pi)$. As such it does not
underflow until $x > \text{HUGE}(x)/\sqrt\pi$.
\end{xnote}
%=========================================================================
\sep\mgpar{331:31+}[Insert after 13.7.69 LOGICAL~(L [, KIND]):]
{\secfont\large 13.7.69$\frac12$ LOG\_GAMMA~(X, [COMPLEX])}
\desc{Principal value of natural logarithm of the Gamma function.}
\class{Elemental function.}
\arguments{}
\intrinarg{X}{shall be of type real. Its value shall not be zero or a
negative integer. If COMPLEX is absent or present with the value false,
X shall be positive.}
\intrinarg{COMPLEX}{(optional) shall be a scalar logical initialization
expression.}
\reschar{}
\begin{incase}
\item If COMPLEX is absent or present with the value false, the result
characteristics are the same as X.
\item If COMPLEX is present with the value true, the result type is
complex with the same kind type parameter value as X.
\end{incase}
\resvalue{The result has a value equal to a processor-dependent
approximation to $\log_e \Gamma (X)$.}
\examples{}
\begin{incase}
\item The value of LOG\_GAMMA(0.5) is 0.5723649430 (approximately).
\item The value of LOG\_GAMMA($-$0.5,.TRUE.) is
(1.265512124, 3.141592654) (approximately).
\end{incase}
\begin{xnote}{13.14$\frac12$}
$\Gamma(x) < 0$ if $x < 0$ and $\lceil x \rceil$ is even. In this case,
$\text{Log}_e \Gamma(x) = \log_e | \Gamma(x) | + i \pi$.
\end{xnote}
%=========================================================================
\sep\mgpar{331:31+}[Alternative definition, to insert after 13.7.69
LOGICAL~(L [, KIND]):]
{\secfont\large 13.7.69$\frac12$ LOG\_GAMMA~(X)}
\desc{Natural logarithm of the absolute value of the Gamma function.}
\class{Elemental function.}
\argument{X shall be of type real. Its value shall not be zero or a
negative integer.}
\reschar{Same as X.}
\resvalue{The result has a value equal to a processor-dependent
approximation to $\log_e |\Gamma (X)|$.}
\examples{}
\begin{incase}
\item The value of LOG\_GAMMA(0.5) is 0.5723649430 (approximately).
\item The value of LOG\_GAMMA($-$0.5) is 1.265512124 (approximately).
\end{incase}
\begin{xnote}{13.14$\frac12$}
$\Gamma(x) < 0$ if $x < 0$ and $\lceil x \rceil$ is even. In this case,
$\text{Log}_e \Gamma(x) = \log_e | \Gamma(x) | + i \pi$.
\end{xnote}
%=========================================================================
\sep\mgpar{342:6+}[Insert after 13.7.87 NOT~(I):]
{\secfont\large 13.7.87$\frac12$ NORM2~(X)}
\desc{$L_2$ norm of an array.}
\class{Transformational function.}
\argument{X shall be of type real. It shall not be a scalar.}
\reschar{Scalar of the same type and kind type parameter value as X.}
\resvalue{The result has a value equal to a processor-dependent
approximation to the $L_2$ norm of X if X is a rank-one array, the
Frobenius norm of X if X is a rank-two array, and the generalized $L_2$
norm of X for higher-rank arrays. In all cases, this is the square root
of the sum of the squares of all elements.}
\begin{incase}
\item X is a rank-one array.
\begin{equation*}
\text{NORM2}(X) = \sqrt{\sum_{i=1}^{\text{SIZE}(X)} X(i)^2}
\end{equation*}
\item X is a rank-two array.
\begin{equation*}
\text{NORM2}(X) = \sqrt{\sum_{i=1}^{\text{SIZE}(X,1)}
\sum_{j=1}^{\text{SIZE}(X,2)} X(i,j)^2}
\end{equation*}
\item[n] X is a rank-$n$ array.
\begin{equation*}
\text{NORM2}(X) = \sqrt{\sum_{i_1=1}^{\text{SIZE}(X,1)} \dots
\sum_{i_n=1}^{\text{SIZE}(X,n)} X(i_1, \dots,
i_n)^2}
\end{equation*}
\end{incase}
\examples{}
\begin{incase}
\item The value of NORM2( (/ 3.0, 4.0 /) ) is 5.0 (approximately).
\item The value of NORM2( (/ 1.0, 2.0, 2.0 /) ) is 3.0 (approximately).
\item The value of NORM2( (/ (REAL(I), I = 1, N) /) ) is
SQRT(N**3/3.0 + N**2/2.0 + N/6.0) (approximately).
\end{incase}
\begin{xnote}{13.16$\frac12$}
It is recommended that the processor compute NORM2 in such a way that
intermediate results do not overflow unless the final result would
overflow.
\end{xnote}
\label{lastpage}
\end{document}