CM FORTRAN LANGUAGE REFERENCE MANUAL Version 2.1, January 1994 Copyright (c) 1989-1994 Thinking Machines Corporation. CHAPTER 17: INTRINSIC FUNCTIONS ******************************** An intrinsic function (or intrinsic subroutine) is a function (or subroutine) that is predefined within the language. CM Fortran supports all the intrinsic functions specified in the FORTRAN 77 standard, most of the additional functions (and an intrinsic subroutine) specified by the Fortran 90 standard, and a number of functions that were included in early drafts of the Fortran 90 standard, but were later removed. Intrinsic functions are categorized into the following groups: o inquiry functions o elemental functions o transformational functions An inquiry function returns information about certain characteristics of its argument. Such functions do not depend on the value of their argument, so the argument may be undefined. An elemental function is a function with only scalar arguments that can be called with array- valued arguments, provided all array arguments are the same shape; the function is applied to corresponding elements of the array arguments as if it had been called repeatedly with a series of scalar arguments. (An elemental subroutine is defined similarly. See Section 12.5.2.2 for information on elemental function references.) A transformational function accepts array arguments and usually returns an array result, in many cases of a different shape from the input arguments. The following sections list the intrinsic functions, grouped into general categories. The name of each function and its arguments is listed, with optional arguments indicated in italic brackets. In these sections, the elemental functions are indicated by a comment !E, the transformational functions by !T, and the inquiry functions by !I. Section 17.12 lists the functions alphabetically and describes each function in detail. NOTE: CM Fortran defines more intrinsic functions than does FORTRAN 77. This means that a FORTRAN 77 program may have a different interpretation from a CM Fortran program if it invokes a procedure having the same name as one of the new intrinsic functions (or the intrinsic subroutine), unless that procedure is specified in an EXTERNAL statement. Much of the text for this chapter is derived from the ANSI Fortran 8x Standard (X3.9-198X, X3J3 / S8.108). 17.1 NUMERIC FUNCTIONS ----------------------- The functions in this group are all elemental functions that either perform type conversions or simple numeric operations. The following numeric functions convert arguments from one type to another. ABS( A ) !E AIMAG( Z ) !E CMPLX( X [, Y ] [, MOLD ] ) !E DBLE( A ) !E DCMPLX( X [, Y ] ) !E DPROD( X, Y ) !E INT( A [, KIND ] ) !E NINT( A [, KIND ] ) !E REAL( A [, MOLD ] ) !E The following inquiry function determines the kind of a type. KIND( X ) !I The following numeric functions perform simple numeric operations and do not convert arguments from one type to another. AINT( A ) !E ANINT( A ) !E CONJG( Z ) !E DIM( X, Y ) !E MAX( A1, A2 [, A3]... ) !E MIN( A1, A2 [, A3]... ) !E MOD( A, P ) !E SIGN( A, B ) !E 17.2 MATHEMATICAL FUNCTIONS ---------------------------- The following elemental functions evaluate elementary mathematical functions. ACOS( X ) !E ASIN( X ) !E ATAN( X ) !E ATAN2( Y, X ) !E COS( X ) !E COSH( X ) !E EXP( X ) !E LOG( X ) !E LOG10( X ) !E SIN( X ) !E SINH( X ) !E SQRT( X ) !E TAN( X ) !E TANH( X ) !E 17.3 CHARACTER FUNCTIONS ------------------------- The functions in this group perform character operations. All functions except LEN are elemental functions, but none may be used with array arguments. The following functions convert from a single character to an integer, or the reverse. CHAR( I ) !E* ICHAR( C ) !E* The following functions perform lexicographic comparison between character strings. Similar functions are provided by the relational operators. LGE( STRING_A, STRING_B ) !E* LGT( STRING_A, STRING_B ) !E* LLE( STRING_A, STRING_B ) !E* LLT( STRING_A, STRING_B ) !E* The following function finds the location of a substring in a string. INDEX( STRING, SUBSTRING ) !E* The inquiry function LEN returns the length of a character entity. The value of a character variable passed as an argument to this function need not be defined. The value of LEN is computed at compile time when possible. LEN( STRING ) !I 17.4 BIT-LEVEL PROCEDURES -------------------------- The following elemental procedures perform bit manipulation operations on integer values. MVBITS is an elemental subroutine. BTEST( I, POS ) !E IAND( I, J ) !E IBCLR( I, POS ) !E IBITS( I, POS, LEN ) !E IBSET( I, POS ) !E IEOR( I, J ) !E IOR( I, J ) !E ISHFT(I, SHIFT ) !E ISHFTC( I, SHIFT, SIZE ) !E NOT( I ) !E MVBITS( FROM, FROMPOS, LEN, TO, TOPOS ) !E The following procedures return information about integer or logical values. LEADZ( X ) !E POPCNT( X ) !E POPPAR( X ) !E 17.5 VECTOR AND MATRIX MULTIPLICATION FUNCTIONS ------------------------------------------------ The matrix multiplication function MATMUL operates on two matrix arguments (either of which can be a vector), returning the product under matrix multiplication. The DOTPRODUCT function returns the scalar product of two vectors. On logical matrices and vectors, MATMUL performs Boolean matrix multiplication. For logical vectors, DOTPRODUCT returns the Boolean scalar product. DOTPRODUCT( VECTOR_A, VECTOR_B ) !T MATMUL( MATRIX_A, MATRIX_B ) !T 17.6 ARRAY REDUCTION FUNCTIONS ------------------------------- These functions perform numerical, logical, and counting operations on arrays. They may be applied to a whole array to give a scalar result, or they may be applied over a given dimension to yield an array of results (the rank of the result is the rank of the original array reduced by one). By using a logical mask that is conformable with the given array, the computation may be confined to any subset of the array (e.g., the positive elements). ALL( MASK [, DIM ] ) !T ANY( MASK [, DIM ] ) !T COUNT( MASK [, DIM ] ) !T MAXVAL( ARRAY [, DIM ] [, MASK ] ) !T MINVAL( ARRAY [, DIM ] [, MASK ] ) !T PRODUCT( ARRAY [, DIM ][, MASK ] ) !T SUM( ARRAY [, DIM ] [, MASK ] ) !T 17.7 ARRAY INQUIRY FUNCTIONS ----------------------------- These functions return information about particular characteristics of an array or vector. These functions can be applied to array arguments whose values have not yet been defined (assigned to), since they do not depend on the value of their arguments. The value of an array inquiry function is computed at compile time for some cases. ALLOCATED( ARRAY ) !I ASSOCIATED( POINTER ) !I DLBOUND( ARRAY [, DIM ] ) !I DSHAPE( SOURCE ) !I DSIZE( ARRAY [, DIM ] ) !I DUBOUND( ARRAY [, DIM ] ) !I RANK( SOURCE ) !I 17.8 ARRAY CONSTRUCTION FUNCTIONS ---------------------------------- The functions MERGE, SPREAD, RESHAPE, PACK, and UNPACK construct new arrays from the elements of existing arrays. MERGE combines two conformable arrays into one array by an element-wise choice based on a logical mask. SPREAD constructs an array from several copies of an actual argument (by adding an extra dimension, as in forming a book from copies of one page). RESHAPE produces an array with the same elements and a different shape. PACK and UNPACK respectively gather and scatter the elements of a one-dimensional array from and to positions in another array where the positions are specified by a logical mask. REPLICATE constructs an array from several copies of an actual argument by increasing the size of one of the dimensions. DIAGONAL constructs a diagonal matrix. DIAGONAL( ARRAY [, FILL ] ) !T MERGE( TSOURCE, FSOURCE, MASK ) !E PACK( ARRAY, MASK [, VECTOR ] ) !T REPLICATE( ARRAY, DIM, NCOPIES ) !T RESHAPE( MOLD, SOURCE [, PAD ] [, ORDER ] ) !T SPREAD( SOURCE, DIM, NCOPIES ) !T UNPACK( VECTOR, MASK, FIELD ) !T 17.9 ARRAY MANIPULATION FUNCTIONS ---------------------------------- The shift functions leave the shape of an array unaltered but shift the positions of the elements parallel to a specified dimension of the array. The TRANSPOSE function performs the matrix transpose operation on a two-dimensional array. CSHIFT( ARRAY, DIM, SHIFT ) !T EOSHIFT( ARRAY, DIM, SHIFT [, BOUNDARY ] ) !T TRANSPOSE( MATRIX ) !T 17.10 ARRAY LOCATION FUNCTIONS ------------------------------- The functions MAXLOC and MINLOC return the location (subscripts) of an element of an array with the maximum or minimum value, respectively, under the control of a logical mask. The functions FIRSTLOC and LASTLOC locate the leading and trailing edges, respectively, of the set of true elements of a logical mask. PROJECT extracts the elements that lie along an edge of an array. (PROJECT also may be classified as a reduction functionsee Section 17.6.) FIRSTLOC( MASK [, DIM ] ) !T LASTLOC( MASK [, DIM ] ) !T MAXLOC( ARRAY [, MASK ] ) !T MINLOC( ARRAY [, MASK ] ) !T PROJECT( ARRAY, MASK, FIELD [, DIM ] ) !T 17.11 SPECIFIC NAMES FOR GENERIC INTRINSIC FUNCTIONS ----------------------------------------------------- Some intrinsic functions may be referenced with either a generic name or a specific name. Generic function names can be used with more than one type of argument. The compiler scans the arguments and generates a call to a specific function name. Only specific names can appear as actual arguments to an external procedure, and the arguments must be scalar. If an intrinsic function does not have a specific name, it cannot be used as an actual argument. Also, those specific intrinsic function names listed below that are marked with an asterisk must not be used as an actual argument. (Note that the list below only includes those intrinsic functions that have specific names.) ------------------------------------------------------------------------------- Generic Name Specific Name Argument Type Function Type ------------------------------------------------------------------------------- ABS( A ) IABS( A ) integer integer ABS( A ) ABS( A ) real real ABS( A ) DABS( A ) double complex double precision ABS( Z ) CABS( Z ) complex real ABS( Z ) CDABS( Z ) double complex double precision ACOS( X ) ACOS( X ) real real ACOS( X ) DACOS( X ) double precision double precision AIMAG( Z ) AIMAG( Z ) complex real AIMAG( Z ) DIMAG( Z ) double complex double precision AINT( A ) AINT( A ) real real AINT( A ) DINT( A ) double precision double precision ANINT( A ) ANINT( A ) real real ANINT( A ) DNINT( A ) double precision double precision ASIN( X ) ASIN( X ) real real ASIN( X ) DASIN( X ) double precision double precision ATAN( X ) ATAN( X ) real real ATAN( X ) DATAN( X ) double precision double precision ATAN2( Y, X ) ATAN2( Y, X ) real real ATAN2( Y, X ) DATAN2( Y, X ) double precision double precision CHAR( I ) *CHAR( I ) integer character CONJG( Z ) CONJG( Z ) complex complex CONJG( Z ) DCONJG( Z ) double complex double complex COS( X ) COS( X ) real real COS( X ) DCOS( X ) double precision double precision COS( Z ) CCOS( Z ) complex complex COS( Z ) CDCOS( Z ) double complex double complex COSH( X ) COSH( X ) real real COSH( X ) DCOSH( X ) double precision double precision DIM( X, Y ) IDIM( X, Y ) integer integer DIM( X, Y ) DIM( X, Y ) real real DIM( X, Y ) DDIM( X, Y ) double precision double precision DPROD( X, Y ) DPROD( X, Y ) real double precision EXP( X ) EXP( X ) real real EXP( X ) DEXP( X ) double precision double precision EXP( Z ) CEXP( Z ) complex complex EXP( Z ) CDEXP( Z ) double complex double complex ICHAR( C ) ICHAR( C ) character integer INDEX( S, T ) INDEX( S, T ) character integer INT( A ) *IFIX( A ) real integer INT( A ) *INT( A ) real integer INT( A ) *IDINT( A ) double precision integer LEN( S ) LEN( S ) character integer LGE( S, T ) LGE( S, T ) character logical LGT( S, T ) LGT( S, T ) character logical LLE( S, T ) LLE( S, T ) character logical LLT( S, T ) LLT( S, T ) character logical LOG( X ) ALOG( X ) real real LOG( X ) DLOG( X ) double precision double prec. LOG( Z ) CLOG( Z ) complex complex LOG( Z ) CDLOG( Z ) double complex double complex LOG10( X ) ALOG10( X ) real real LOG10( X ) DLOG10( X ) double prec. double prec. MAX( A1, A2, A3,.. ) *MAX0( A1, A2, A3,... ) integer integer MAX( A1, A2, A3,.. ) *AMAX1( A1, A2, A3,... ) real real MAX( A1, A2, A3,... ) *DMAX1( A1, A2, A3,... ) double prec. double prec. MAX( A1, A2, A3,... ) *AMAX0( A1, A2, A3,... ) integer real MAX( A1, A2, A3,... ) *MAX1( A1, A2, A3,... ) real integer MIN( A1, A2, A3 ) *MIN0( A1, A2, A3,... ) integer integer MIN( A1, A2, A3,... ) *AMIN1( A1, A2, A3,... ) real real MIN( A1, A2, A3,... ) *DMIN1( A1, A2, A3,... ) double prec. double prec. MIN( A1, A2, A3,... ) *AMIN0( A1, A2, A3,... ) integer real MIN( A1, A2, A3,... ) *MIN1( A1, A2, A3,... ) real integer MOD( A, P ) MOD( A, P ) integer integer MOD( A, P ) AMOD( A, P ) real real MOD( A, P ) DMOD( A, P ) double precision double prec. NINT( A ) NINT( A ) real integer NINT( A ) IDNINT( A ) double precision integer REAL( A ) *REAL( A ) integer real REAL( A ) *FLOAT( A ) integer real REAL( A ) *SNGL( A ) double precision real SIGN( A, B ) ISIGN( A, B ) integer integer SIGN( A, B ) SIGN( A, B ) real real SIGN( A, B ) DSIGN( A, B ) double precision double prec. SIN( X ) SIN( X ) real real SIN( X ) DSIN( X ) double precision double prec. SIN( Z ) CSIN( Z ) complex complex SIN( Z ) CDSIN( Z ) double complex double complex SINH( X ) SINH( X ) real real SINH( X ) DSINH( X ) double precision double prec. SQRT( X ) SQRT( X ) real real SQRT( X ) DSQRT( X ) double precision double prec. SQRT( Z ) CSQRT( Z ) complex complex SQRT( Z ) CDSQRT( Z ) double complex double complex TAN( X ) TAN( X ) real real TAN( X ) DTAN( X ) double precision double prec. TANH( X ) TANH( X ) real real TANH( X ) DTANH( X ) double precision double prec. ------------------------------------------------------------------------------- 17.12 SPECIFICATIONS OF THE INTRINSIC FUNCTIONS ------------------------------------------------ To view detailed specifications of the intrinsic functions, on a CM-5 type man and on a CM-200 type cmman where is one of ABS EOSHIFT MINLOC ACOS EXP MINVAL AIMAG FIRSTLOC MOD AINT IAND MVBITS ALL IBCLR NINT ALLOCATED IBITS NOT ANINT IBSET PACK ANY ICHAR POPCNT ASIN IEOR POPPAR ASSOCIATED INDEX PRODUCT ATAN INT PROJECT ATAN2 IOR RANK BTEST ISHFT REAL CHAR ISHFTC REPLICATE CMPLX KIND RESHAPE CONJG LASTLOC SIGN COS LEADZ SIN COSH LEN SINH COUNT LGE SPREAD CSHIFT LGT SQRT DBLE LLE SUM DCMPLX LLT TAN DIAGONAL LOG TANH DIM LOG10 TRANSPOSE DLBOUND MATMUL UNPACK DOTPRODUCT MAX DPROD MAXLOC DSHAPE MAXVAL DSIZE MERGE DUBOUND MIN In the function headings, optional dummy arguments are italicized. Throughout the examples in the man pages, arrays of rank 2 or 3 are written using the matrix notation commonly used in mathematics, as in: || 111 121 131 141 || | 11 12 13 | || 211 221 231 241 || A = | 21 22 23 | B = || 311 321 331 341 || | 31 32 33 | | | || 112 122 132 142 || || 212 222 232 242 || || 312 322 332 342 || The elements of array A in array element order are: 11, 21, 31, 12, ..., 33. The elements of array B in array element order are: 111, 211, 311, 121, ..., 341, 112, 212, 312, 122, ..., 342. For compactness (and consistency with the rest of this manual), arrays of rank one are usually written as array constructors, as in C = [10,20,30] as an alternative to matrix notation | 10 | C = | 20 | | 30 | Also for compactness, the abbreviations T and F are used in place of the logical constants .TRUE. and.FALSE., respectively. Within matrix brackets and array constructors representing logical arrays, the character period (.) is used for .FALSE.. In giving examples, the symbols --> and ==> mean "evaluates exactly to" and "evaluates approximately to." For example: SUM(A) ==> 1.5732 ! SUM(A) has the approximate value 1.5732 SUM(B) --> pi ! SUM(B) has the exact value pi As in syntax rules, italic brackets [ ] designate optional arguments in a function specification. ***************************************************************** The information in this document is subject to change without notice and should not be construed as a commitment by Think- ing Machines Corporation. Thinking Machines reserves the right to make changes to any product described herein. Although the information in this document has been reviewed and is believed to be reliable, Thinking Machines Corporation assumes no liability for errors in this document. Thinking Machines does not assume any liability arising from the application or use of any information or product described herein. ***************************************************************** Connection Machine (r) is a registered trademark of Thinking Machines Corporation. CM, CM-2, CM-200, CM-5, CM-5 Scale 3, and DataVault are trademarks of Thinking Machines Corporation. CMOST, CMAX, and Prism are trademarks of Thinking Machines Corporation. C* (r) is a registered trademark of Thinking Machines Corporation. Paris, *Lisp, and CM Fortran are trademarks of Thinking Machines Corporation. CMMD, CMSSL, and CMX11 are trademarks of Thinking Machines Corporation. CMview is a trademark of Thinking Machines Corporation. Scalable Computing (SC) is a trademark of Thinking Machines Corporation. Scalable Disk Array (SDA) is a trademark of Thinking Machines Corporation. Thinking Machines (r) is a registered trademark of Thinking Machines Corporation. CONVEX is a trademark of CONVEX Computer Corporation. Cray is a registered trademark of Cray Research, Inc. SPARC and SPARCstation are trademarks of SPARC International, Inc. Sun, Sun-4, and Sun Workstation are trademarks of Sun Microsystems, Inc. UNIX is a trademark of UNIX System Laboratories, Inc. The X Window System is a trademark of the Massachusetts Institute of Technology. Copyright (c) 1989-1994 by Thinking Machines Corporation. All rights reserved. This file contains documentation produced by Thinking Machines Corporation. Unauthorized duplication of this documentation is prohibited. Thinking Machines Corporation 245 First Street Cambridge, Massachusetts 02142-1264 (617) 234-1000