matmul(3I)

NAME
     MATMUL - Performs matrix multiplication of numeric or logical matrices

SYNOPSIS
     MATMUL ([MATRIX_A=]matrix_a, [MATRIX_B=]matrix_b)

STANDARDS
     Fortran

DESCRIPTION
     The MATMUL intrinsic function performs matrix multiplication
     operations on numeric or logical matrices.  It accepts the following
     arguments:

     matrix_a  Must be of numeric type (integer, real, or complex) or of
               logical type.  It must be array valued and of rank one or
               two.

     matrix_b  Must be of numeric type if matrix_a is of numeric type and
               of logical type if matrix_a is of logical type.  It must be
               array valued and of rank one or two.  If matrix_a has rank
               one, matrix_b must have rank two.  If matrix_b has rank one,
               matrix_a must have rank two.  The size of the first (or
               only) dimension of matrix_b must equal the size of the last
               (or only) dimension of matrix_a.

     MATMUL is a transformational function.  The name of this intrinsic
     cannot be passed as an argument.

ENVIRONMENT VARIABLES
     The F90_MATMUL_BLAS environment variable directs the compiler to use
     the single-processor matrix multiplication routines from libblas.  The
     libblas GEMM routines will be invoked only when the MATMUL arguments
     are numeric matrices of floating-point values.

     If the F90_MATMUL_PARALLEL_BLAS environment variable is set in
     addition to the F90_MATMUL_BLAS variable, the multiprocessor matrix
     multiplication routines from libblas_mp are used.

     Note that libblas is an older library version and has been superceded
     by SCSL (the SGI Scientific Computing Software Library).  In order to
     use the SCSL matrix multiplication routines, link the executable with
     the -lscs or -lscs_mp compiler options, depending on whether single or
     multiprocessor functionality is needed. If that is done, then setting
     F90_MATMUL_BLAS alone will be sufficient to invoke the SCSL routines,
     whether single or multiprocessor.

     Note that it is not necessary for the executable to explicitly call
     any SCSL routines. The library merely has to be linked in to be used.

     Using the SCSL version of this routine can provide substantial
     performance improvement without requiring any code change.

RETURN VALUES
     The result type, type parameter, and shape are as follows.  If the
     arguments are of numeric type, the type and kind type parameter of the
     result are determined by the types of the arguments.  If the arguments
     are of type logical, the result is of type logical with the kind type
     parameter of the arguments.  The shape of the result depends on the
     shapes of the arguments, as follows:

     * If matrix_a has shape (n, m) and matrix_b has shape (m, k), the
       result has shape (n, k).

     * If matrix_a has shape (m) and matrix_b has shape (m, k), the result
       has shape (k).

     * If matrix_a has shape (n, m) and matrix_b has shape (m), the result
       has shape (n).

     Element (i, j) of the result has the value
     SUM(MATRIX_A(i,:)*MATRIX_B(:,j)) if the arguments are of numeric type
     and has the value ANY(MATRIX_A(i,:).AND.MATRIX_B(:,j)) if the
     arguments are of logical type.

     Element (j) of the result has the value SUM(MATRIX_A(:)*MATRIX_B(:,j))
     if the arguments are of numeric type and has the value
     ANY(MATRIX_A(:).AND.MATRIX_B(:,j)) if the arguments are of logical
     type.

     Element (i) of the result has the value SUM(MATRIX_A(i,:)*MATRIX_B(:))
     if the arguments are of numeric type and has the value
     ANY(MATRIX_A(i,:).AND.MATRIX_B(:)) if the arguments are of logical
     type.

EXAMPLES
     Let A and B be the following matrices:

     | 1 2 3 |
     | 2 3 4 |

     and

     | 1 2 |
     | 2 3 |
     | 2 4 |

     Let X and Y be vectors [1,2] and [1,2,3].

     MATMUL(A,B) yields the matrix-matrix product AB, as follows:

     | 11 20 |
     | 16 29 |

     MATMUL(X,A) yields the vector-matrix product XA with the value
     [5,8,11].

     MATMUL(A,Y) yields the matrix-vector product AY with the value
     [14,20].