MATRAN
A MATRIX WRAPPER FOR FORTRAN 95

G. W. Stewart

Department of Computer Science
Institute for Advanced Computer Studies
University of Maryland

Mathematical and Computations Sciences Division
NIST

stewart@cs.umd.edu
http://www.cs.umd.edu/~stewart/

Introduction
Current Status
Obtaining and using Matran
Copyright and License
Change Log
Acknowledgements

Introduction
(top)

Matran (pronounced MAY-tran) is a Fortran 95 wrapper that implements matrix operations and computes matrix decompositions using Lapack and the Blas. Although Matran is not based on a formally defined matrix language, it provides the flavor and convenience of coding in matrix oriented systems like Matlab, Octave, etc. By using routines from Lapack and the Blas, Matran allows the user to obtain the computational benefits of these packages with minimal fuss and bother.

Detailed information about Matran may be found in the Matran Writeup (ps, pdf). Here we give a general overview of Matran, its organization, and its capabilities.

Organization

Matran consists of a number of Fortran 95 modules, which fall into five categories.

The Matran utility module

This module contains global parameters, error handlers, and utility routines.

Matrix types

A Matran matrix type is essentially a storage class for matrices. Currently implemented are the Rmat and the Rdiag. The Rmat represents matrices that can be conveniently stored in a rectangular array (whose dimensions may be larger than that of the matrix). The Rdiag represents diagonal matrices whose diagonal elements are stored in a linear array. Matran can be compiled to give a single or double precision package (but not both at the same time).

The Rmat has a special tag field that specifies if the matrix is general, triangular, Hermitian, or positive (semi) definite. Matran uses this field to the most efficient way to perform operations with the matrices. There are no packed representations. For example, the zero elements of a triangular matrix are explicitly stored in the Rmat array.

The Rdiag implements a diagonal matrix with its diagonal elements stored in a linear array.

Although they are not currently implemented, Matran will eventually have complex types, Cmat and Cdiag, corresponding to the real types.

Matrix operations

Matran overloads old operators and defines new operators to compute transposes (.trp.A, .ctp.A), sums (A+B, -A), and products (A*B)of matrices. In addition it defines operators to compute quantities like A^-1B (A.xiy.B). There are also operators for concatenating matrices and extracting submatrices.

These operations are organized into collections of modules called suites. For example, there are two modules in the product suite that compute matrix products. The module RmatProduct_m implements products between Rmats, taking due account of the tag components mentioned above. The module RdiagProduct implements products between Rdiags and between Rdiags and Rmats. When the type Cmat is introduced, the module CmatProduct_m will be responsible for implementing products between any combination of Rmats, Rdiags, and Cmats.

Matrix miscelanea

Matran provides a number of useful matrix functions (e.g., norms) and constructors (e.g., identity matrices). It also provides a module to pretty print a matrix.

Decompositions

Matwrap provides types and constructors for the following decompositions: LU with partial pivoting, QR, QR with column pivoting, Cholesky, spectral, SVD, real Schur, and the eigendecompositon of a general matrix.

A recurring problem in matrix oriented languages is how to prevent the recomputation of matrix decompositions in loops. Matran provides features that help the programmer circumvent this problem.

Openness

Modules in Fortran 95 cannot see private parts of other modules. For this reason Matran's modules have no private parts at all. Although this goes against the grain of object oriented programming, it actually makes a good deal of sense when it comes to matrix computations. The number of uses of matrices (which have been around for 150 years) is far greater than the number of methods that can be folded into an object oriented package. The present arrangements allow the user to extend the package efficiently by operating directly on the arrays containing the matrices. For example, all the powerful array operations of Fortran 95 are directly available to the Matran programmer. The dark side of this flexibility is that the programmer must exercise discipline in enforcing a number of Matran conventions.

Memory management

Matran handles all memory allocation automatically. It is conservative and attempts to use available storage wherever possible. Unfortunately, the storage of matrix types and decompositions declared in subprograms as well as temporaries passed to subprograms are not automatically deallocated when the program returns from the subprogram, and the coder must explicitly deallocate the storage. However, Matran provides special generic subroutines to make this task easy.

Matran allows considerable control over the creation of temporary matrix objects by shadowing matrix operators with subroutine forms. For example, the statement

   C = A + B

requires a temporary Rmat to hold the intermediate result A + B. On the other hand the statement

   call Plus(C, A, B)

accomplishes the same thing with no temporaries.

Matran performs most of its computations by calling appropriate Lapack and Blas routines, some of which require the user to furnish working storage. Ordinarily, this storage is silently allocated and deallocated by Matran. But through optional arguments, the coder can furnish the storage explicitly, thus reducing calls to the allocator.

Current Status
(top)

Matran is at a point where it can perform useful computations (see the last section of the Matran Writeup (ps, pdf for an example), which is why it is being distributed. However, it can certainly be improved, and a second purpose of the distribution is to get feedback before Matran gets so large it is hard to change. Please send comments and suggestions to me at stewart@cs.umd.edu There are three areas in which Matran will likely change.

The addition of types and operations for complex matrices.
The expansion of the matrix miscelanea class of modules.
The replacement of pointer arrays with allocatable arrays. This will happen when the allocatable array extensions to Fortran 95 are widely and correctly implemented.

Obtaining and Using Matran
(top)

Downloading

Matran is available over the web.
The following files can be downloaded via http or via ftp Simply click on the method you wish to use.
If you are not sure, use http.

File	Description	Method
README	Please do!	http	ftp
Matran.html	This document	http	ftp
MatranWriteup.ps	The postscript documentation	http	ftp
MatranWriteup.pdf	The pdf documentation	http	ftp
Matran.tar	The whole shebang	http	ftp

Download Matran.tar to a suitable directory and execute

   tar -xf Matran.tar

This will create a directory Matran with the following contents.

   README
   Doc
   Matran

Doc is a directory containing the Matran writup. The directory Matran contains the goodies.

Installation

Installation consists of creating an archive of Matran object code. In principle this is easy to do. Go to the Matran directory and in the Makefile edit the lines

   FC = f95

   .f95.o :
           $(FC) -c -fpp $<

to invoke your Fortran 95 compiler with the Fortran preprocessor. (Note the initial spaces in the second line represent a tab character.) Then enter

   make all

followed by

   make arch

This will produce a file Matran.a, which you can move to wherever you store your library files. To get a single precision version of Matran, change the make all command to

   make all PREC=sngl

To use Matran, you must not only link your program to Matran.a but to Lapack and the Blas. If these routines are already installed on your system, use the standard linking syntax for your compiler-loader. If not, you may obtain them from

   www.netlib.org

You will need the real codes of the appropriate precision. The code is not difficult to compile and collect into a library. However, the compiler specified in the Lapack make file is Fortran 77, and it may be necessary to change it to Fortran 95 for compatibility with Matran. Note that the Blas you obtain from netlib are reference code and are not optimized for any particular machine.

Some compilers are fussy about the suffixes they will accept. For example some Fortran 95 compilers accept only the suffix F90. The Makefile contains a target chsuf that automates the tedious procedure of changing suffixes on unix machines with sed. Edit the command

   ls -d *.s1 | sed 's/\(.*\)\.s1$$/mv & \1.s2/' | sh

to replace s1 with the old suffix and s2 with the new one, and then enter

   make chsuf

Although Matran has been tested on a number of compilers, it has been impossible to cover the field. For this reason, the rough code used to debug the modules of Matran are included. Each debugging program is named after the module it tests; e.g., RmatDebug for the module Rmat_m. The line

 LIB = lapack.a blas.a

in Makefile must be edited to link to Lapack and the Blas on your system. The corresponding Makefile target is rmatdebug. Please understand that these uncommented programs do not represent exhaustive tests of the modules; they were written to bootstrap Matran, not establish its correctnesss. To aid you in deciphering these programs, representative output is contained in the .out files (e.g., Rmat.out for Rmat_m). If you enounter errors or problems please report them to stewart@cs.umd.edu.

Copyright, License, and Aailability
(top)

Copyright

License

Your use or distribution of Matran or any derivative code implies that you agree to this License.

Permission is hereby granted to use or copy this program, provided that the Copyright, this License, and the Availability note of the original version is retained on all copies. Only the current, umodified version of Matran may be distributed, whether by itself or as part of another program; however, additional modules extending Matran may be appended. Any such distributation stand must cite the Copyright, this License, the Availability note, and "Used by permission."

THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK.

Explanatory note: The reason for the restriction on the distribution is that Matran is still growing. It is desirable during this period to have only one version of core Matran in circulation. Suggestions for improvements may be sent to stewart@cs.umd.edu.

Availability

Matran is available over the web at

   ftp://thales.cs.umd.edu/pub/Matran

Change Log
(top)

Oct 1 2003: The tag SP (symmetric positive definite) has been changed to HP (Hermitian positivie definite.)

Acknowledgments
(top)

Matran has been supported by the National Science Foundation and by the Mathematical and Computer Sciences Division of the National Institute for Standards and Technology.

I am indebted to John Reid and Bill Mitchell for sharing their expertise in Fortran~95. I also wish to thank my student Che-Rung Lee for his help in assembling the package.

MATRAN A MATRIX WRAPPER FOR FORTRAN 95

Contents

Introduction (top)