INTRO_LIBM(3M) Last changed: 1698
INTRO_LIBM  Introduction to math library routines
See individual man pages for implementation details
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:
32bit or half precision real and 64bit or single precision real.
The specific names for single precision real data provide a link to
the 64bit intrinsic functions. To ensure a link to the 32bit
intrinsic functions, use the generic function names with 32bit 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 64bit 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 doubleprecision 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.
* Extendedprecision routines  The extendedprecision routines
perform double and tripleprecision 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 [Toc] [Back]
Some function names are in uppercase, and some are in lowercase. The
Fortran language is caseinsensitive; 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 [Toc] [Back]
The C language is casesensitive. 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 passbyaddress.
Calling from Cray Assembly Language (CAL)
External references from Cray Assembly Language (CAL) are casesensitive,
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: callbyregister and callbyaddress. For more
information on the details of calling sequences, see the documentation
for the CALL macro in UNICOS Macros and Opdefs Reference Manual,
publication SR2403.
It is strongly recommended that function linkage be done using the
CALL macros. Direct user calls to functions by using the returnjump
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 vectorlength register (VL) upon entry.
For example, to call the SQRT routine using the callbyaddress
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 callbyregister 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 callbyregister
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 vectorlength register VL
is unchanged.
Naming conventions [Toc] [Back]
Most of the UNICOS math library functions adhere to the following
naming convention:
NAME Entry for callbyaddress
NAME% Entry for scalar callbyregister
%NAME% Entry for vector callbyregister
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, doubleprecision, or complex logarithm
respectively, and the argument must be of the correct type (real,
doubleprecision, or complex).
Register conventions [Toc] [Back]
The documentation for some of the widely used usercallable functions
contains the register usage convention for the function. By default
all the Cray Fortran compilers use the callbyregister 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 callbyaddress method.
INTRO_INTRIN(3I)
Cray Standard C Reference Manual, publication SR2074
CF90 Commands and Directives Reference Manual, publication SR3901
Fortran Language Reference Manual, Volume 1, publication SR3902
Fortran Language Reference Manual, Volume 2, publication SR3903
Fortran Language Reference Manual, Volume 3, publication SR3905
Intrinsic Procedures Reference Manual, publication SR2138, for the
INTRO_LIBM(3M) Last changed: 1698
INTRO_LIBM  Introduction to math library routines
See individual man pages for implementation details
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:
32bit or half precision real and 64bit or single precision real.
The specific names for single precision real data provide a link to
the 64bit intrinsic functions. To ensure a link to the 32bit
intrinsic functions, use the generic function names with 32bit 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 64bit 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 doubleprecision 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.
* Extendedprecision routines  The extendedprecision routines
perform double and tripleprecision 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 [Toc] [Back]
Some function names are in uppercase, and some are in lowercase. The
Fortran language is caseinsensitive; 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 [Toc] [Back]
The C language is casesensitive. 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 passbyaddress.
Calling from Cray Assembly Language (CAL)
External references from Cray Assembly Language (CAL) are casesensitive,
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: callbyregister and callbyaddress. For more
information on the details of calling sequences, see the documentation
for the CALL macro in UNICOS Macros and Opdefs Reference Manual,
publication SR2403.
It is strongly recommended that function linkage be done using the
CALL macros. Direct user calls to functions by using the returnjump
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 vectorlength register (VL) upon entry.
For example, to call the SQRT routine using the callbyaddress
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 callbyregister 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 callbyregister
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 vectorlength register VL
is unchanged.
Naming conventions [Toc] [Back]
Most of the UNICOS math library functions adhere to the following
naming convention:
NAME Entry for callbyaddress
NAME% Entry for scalar callbyregister
%NAME% Entry for vector callbyregister
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, doubleprecision, or complex logarithm
respectively, and the argument must be of the correct type (real,
doubleprecision, or complex).
Register conventions [Toc] [Back]
The documentation for some of the widely used usercallable functions
contains the register usage convention for the function. By default
all the Cray Fortran compilers use the callbyregister 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 callbyaddress method.
INTRO_INTRIN(3I)
Cray Standard C Reference Manual, publication SR2074
CF90 Commands and Directives Reference Manual, publication SR3901
Fortran Language Reference Manual, Volume 1, publication SR3902
Fortran Language Reference Manual, Volume 2, publication SR3903
Fortran Language Reference Manual, Volume 3, publication SR3905
Intrinsic Procedures Reference Manual, publication SR2138, for the
[ Back ]
