NAME
clibmvec - vector versions of some complex mathematical
functions
SYNOPSIS
f95 [ flag ... ] file ... -lmvec [ library ... ]
or
f95 [ flag ... ] file ... -lmvec_mt [ library ... ]
subroutine vc_abs(n, a, stridea, r, strider)
subroutine vc_exp(n, a, stridea, b, strideb, rtmp)
subroutine vc_log(n, a, stridea, b, strideb)
subroutine vc_pow(n, a, stridea, b, strideb, c, stridec,
rtmp3)
subroutine vz_abs(n, x, stridex, d, strided)
subroutine vz_exp(n, x, stridex, y, stridey, dtmp)
subroutine vz_log(n, x, stridex, y, stridey)
subroutine vz_pow(n, x, stridex, y, stridey, z, stridez,
dtmp3)
integer n, stridea, strideb, stridec, strider
integer stridex, stridey, stridez, strided
complex a(1+(n-1)*stridea), b(1+(n-1)*strideb), c(1+(n-
1)*stridec)
real r(1+(n-1)*strider), rtmp(n), rtmp3(3*n)
complex*16 x(1+(n-1)*stridex), y(1+(n-1)*stridey), z(1+(n-
1)*stridez)
real*16 d(1+(n-1)*strided), dtmp(n), dtmp3(3*n)
DESCRIPTION
These routines evaluate common complex elementary functions
for an entire vector of values at once. The first parameter
indicates the number of values to compute. Subsequent
parameters specify the argument and result vectors. Each
vector is described by the first array element to be used
and a stride, which is the increment between successive ele-
ments.
vc_abs(n, a, stridea, r, strider) computes
r(1+(i-1)*strider) = abs(a(1+(i-1)*stridea)) for each i = 1,
2, ..., n. Note that the output vector is of real type.
vc_exp(n, a, stridea, b, strideb, rtmp) computes
b(1+(i-1)*strideb) = exp(a(1+(i-1)*stridea)). The rtmp
parameter provides scratch space and must be large enough to
hold n elements of real type.
vc_log(n, a, stridea, b, strideb) computes
b(1+(i-1)*strideb) = log(a(1+(i-1)*stridea)).
vc_pow(n, a, stridea, b, strideb, c, stridec, rtmp3) com-
putes c(1+(i-1)*stridec) =
a(1+(i-1)*stridea)**b(1+(i-1)*strideb). The rtmp3 parameter
provides scratch space and must be large enough to hold 3*n
elements of real type.
The subroutines vz_abs, vz_exp, vz_log, and vz_pow are dou-
ble precision complex versions of the single precision com-
plex functions listed above.
For each function, the element count n must be greater than
zero. The strides for the argument and result arrays may be
arbitrary integers, but the arrays themselves must not be
the same or overlap. For example, the result of calling
vc_log(n, a, 1, a, 1) is undefined. Note that a zero stride
may be specified, which effectively collapses the entire
vector into a single element. Thus, for example, one can
use vc_pow to compute values of a(i)**b for a fixed value of
b by setting strideb to 0. Finally, note that a stride may
be negative, but the corresponding array parameter must
still refer to the first element accessed in the vector; if
the stride is negative, this will be the highest-addressed
element in memory. (This convention differs from the Level
1 BLAS, in which array parameters always refer to the
lowest-addressed element in memory even when negative incre-
ments are used.) For example, to set b(i) = exp(a(n-i+1)),
call vc_exp(n, a(n), -1, b, 1, rtmp).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
_______________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE|
|____________________|_________________|
| Availability | SPROlang |
| Interface Stability| Evolving |
| MT-Level | MT-Safe |
|____________________|_________________|
SEE ALSO
libmvec(3M), attributes(5)
DIAGNOSTICS
The vector functions treat exceptional cases in the spirit
of IEEE 754, producing essentially the same results as the
corresponding Fortran scalar functions. Some vector func-
tions may raise the inexact exception even if all elements
of the argument array are such that the numerical results
are exact.
NOTES
The vector functions listed above are provided in each of
two libraries, libmvec.a and libmvec_mt.a. The latter con-
tains parallelized versions of the functions that work in
conjunction with the automatic parallelization provided by
the compiler. To use libmvec_mt.a, you must link with one
of the parallelization options -xparallel, -xexplicitpar, or
-xautopar.
It is the user's responsibility to ensure that the default
round-to-nearest mode is in effect when functions in this
library are called. The vector functions assume that the
default round-to-nearest mode is in effect. If the calling
program changes the rounding mode to a non-default mode, it
must re-establish round-to-nearest mode before calling one
of the vector functions. The result of calling a vector
function with a non-default rounding mode is undefined.
The vector functions may be called indirectly through the
use of -xvector=yes, -xlibmopt, or -fast. The -fast compile
option asserts that the program only uses default rounding,
and so the rounding should never be changed. With -xlibmopt
and -xvector=yes, rounding must be set to the default
round-to-nearest mode whenever the program calls a math
function. Non-default rounding can be used for arithmetic
functions outside of the math library.
In vector and parallel execution, elements need not be pro-
cessed in the natural order x(1), x(1+stridex),
x(1+2*stridex), etc. Therefore, exceptions that occur may
not be raised in order. For example, if exp(x(1)) would
raise the overflow exception, and exp(x(9)) would raise the
invalid operation exception, there is no guarantee that a
call to vc_exp will indicate the overflow first.