INTRO_LIBM(3M) Last changed: 1-6-98
NAME
INTRO_LIBM - Introduction to math library routines
IMPLEMENTATION
See individual man pages for implementation details
DESCRIPTION
The math routines are listed with the other intrinsic procedures in
alphabetical order, usually by generic function name. Generic
function names are function calls that cause the compiler to compile
automatically the appropriate data type version of a routine, based on
the type of the input data. For example, a call to the generic
function LOG with a type of input data of complex compiles as CLOG.
In general, on UNICOS systems, real functions have no prefix; integer
functions are prefixed with I, double precision functions are prefixed
with D, complex functions are prefixed with C, and double precision
complex functions are prefixed with CD (for example, ABS, IABS, DABS,
CABS, and CDABS). Functions with a type different from their
arguments are noted. Real functions are usually the same as the
generic function name.
On UNICOS/mk systems, two precisions are provided for real data:
32-bit or half precision real and 64-bit or single precision real.
The specific names for single precision real data provide a link to
the 64-bit intrinsic functions. To ensure a link to the 32-bit
intrinsic functions, use the generic function names with 32-bit real
arguments. For example, use LOG for any of the types of real data.
Use ALOG for single precision real arguments. Extended precision
routines of math library routines are not provided on UNICOS/mk
systems and only some routines have vector versions.
UNICOS/mk systems have an additional library named libmfastv. It
contains versions of selected math intrinsics which can be faster than
those in the default Math library. These alternate versions are not
as accurate as the default library, and in some cases there are
argument restrictions, such as not allowing the use of the -O option
on the compiler command line, or not allowing the use of infinities.
These alternate versions are generally faster for loops with 50 or
more iterations. To use libmfastv, use the -l mfastv option on the
compiler's command line to load the library file. You must compile
your code with the -O3 or -Ovector3 option for the Fortran compiler or
use -h vector3 with the C compiler.
For information on inlining and vectorization of the Fortran 90
intrinsic procedures, see INTRO_INTRIN(3I).
The documentation for some of the most often used math library
routines also contains information on Cray Assembly Language (CAL)
register usage.
For more information on calling library routines from various
programming languages, see the subsection on this man page titled
"Calling Functions from Fortran, C, or CAL."
The math routines can be divided into the following general
categories:
* General arithmetic functions - In the routine descriptions, complex
arguments are represented as
x = x + ix .
r i
The real part of the complex number is x ; x is the imaginary part.
r i
Arguments and results are of the same type unless otherwise
indicated.
Base values raised to a power and 64-bit integer division are called
implicitly from Fortran.
* Exponential and logarithmic functions - The Cray Resesarch
exponential and logarithmic functions are similar to the ANSI
standard functions. Each function has variations for real, double
precision, and complex values except the common logarithm function,
which addresses only real and double-precision values. Complex
arguments are represented as
x = x + ix .
r i
x is the real part of the complex number; x is the imaginary part.
r i
* Trigonometric functions - The trigonometric functions are based on
the ANSI standard for Fortran, except for the cotangent function and
the COSS (cosine and sine) function, which are Cray Research
extensions.
* Type conversion functions - Type conversion functions change the
type of an argument. In the routine description, complex arguments
are represented as
x = x + ix .
r i
x is the real part of the complex number; x is the imaginary part.
r i
Arguments and results are of the same type, unless indicated
otherwise.
* Special functions - The special functions provide Fortran access to
a number of Standard C functions on UNICOS/mk and UNICOS systems.
* Extended-precision routines - The extended-precision routines
perform double- and triple-precision arithmetic on UNICOS systems.
* Boolean functions - The Boolean functions perform logical operations
and bit manipulations. On UNICOS systems, the scalar subprograms
are external versions of Fortran inline functions. They are all
called by address; results are returned in register S1. All Boolean
functions are extensions. These functions cannot be passed as
arguments with CF90 on any system.
Calling Functions from Fortran, C, or CAL
Because of differences in the calling sequences for these languages,
and other language differences, important variations must be noted in
what functions can be called and how they are called.
Calling from Fortran programs
Some function names are in uppercase, and some are in lowercase. The
Fortran language is case-insensitive; the Cray Research Fortran
compilers map all code in uppercase. This means that functions with
lowercase names cannot be called from Fortran programs.
Calling from C programs
The C language is case-sensitive. You must use the exact case
specified in the documentation when coding references to a function.
All functions documented in this manual are callable from C programs.
The following rules can be used:
* Because the function is not declared in a Standard C header,
explicitly declare the function as external, and specify the type of
the return value.
* When calling the function, pass the address of the arguments by
using the address operator (&) for each argument or by using a
pointer to the argument. Array names are considered to be
addresses; the address operator is not needed when using them.
* The value returned by the function is the value, rather than the
address of the value.
* Specify the fortran keyword. The fortran keyword is an extension to
the C language and is useful when a C program calls a function
following the Cray Fortran calling sequence. Specifying the fortran
keyword causes the C compiler to verify that the arguments used in
each call to the function are pass-by-address.
Calling from Cray Assembly Language (CAL)
External references from Cray Assembly Language (CAL) are case-
sensitive, so you must use the exact name for functions as specified
on the man pages. Two standard calling methods are supported by Cray
for math functions: call-by-register and call-by-address. For more
information on the details of calling sequences, see the documentation
for the CALL macro in UNICOS Macros and Opdefs Reference Manual,
publication SR-2403.
It is strongly recommended that function linkage be done using the
CALL macros. Direct user calls to functions by using the return-jump
instruction should be avoided.
Scalar functions return the result in registers S1 (and S2 if needed);
results for complex double precision are returned in S1 through S4.
Vector functions return their result in registers V1 (and V2 if
needed); complex double precision are returned in V1 through V4. The
number of elements computed for vector functions is determined by the
contents of the vector-length register (VL) upon entry.
For example, to call the SQRT routine using the call-by-address
sequence, let arg1 be the address of the argument.
CAL usage:
EXT SQRT Declare the name to be an external
CALL SQRT,(arg1) Call the function
(result)S1 The result is returned in register S1 and
stored at the address result
Note that the name SQRT must be uppercase.
To call the SQRT routine by using the call-by-register convention:
(S1) Value of the argument
CAL usage:
EXT SQRT% Declare the name to be an external
CALLV SQRT% Call the function
(result)S1 The result is returned in register S1 and
stored at the address result
To call the routine for vector SQRT using the call-by-register
convention, let V1 be the value of the vector argument and VL be the
vector length (between 1 and 64 values will be returned).
CAL usage:
EXT %SQRT% Declare the name to be an
external
CALLV %SQRT% Call the function
The result is returned in register V1. The vector-length register VL
is unchanged.
Naming conventions
Most of the UNICOS math library functions adhere to the following
naming convention:
NAME Entry for call-by-address
NAME% Entry for scalar call-by-register
%NAME% Entry for vector call-by-register
Note that assembly language does not support generic function names or
automatic data type conversion. For example, there is no math library
LOG function for the logarithm routine. You must specify either ALOG,
DLOG, or CLOG for real, double-precision, or complex logarithm
respectively, and the argument must be of the correct type (real,
double-precision, or complex).
Register conventions
The documentation for some of the widely used user-callable functions
contains the register usage convention for the function. By default
all the Cray Fortran compilers use the call-by-register convention for
math library functions (it is the fastest calling sequence), and will
put the % prefix or suffix on the function name where needed. If a
math library function is declared EXTERNAL or INTRINSIC, the compilers
will generate code for the call-by-address method.
SEE ALSOINTRO_INTRIN(3I)
Cray Standard C Reference Manual, publication SR-2074
CF90 Commands and Directives Reference Manual, publication SR-3901
Fortran Language Reference Manual, Volume 1, publication SR-3902
Fortran Language Reference Manual, Volume 2, publication SR-3903
Fortran Language Reference Manual, Volume 3, publication SR-3905
Intrinsic Procedures Reference Manual, publication SR-2138, for the
