MARCA_Models:
Generating the Matrices

William J. Stewart

Billy's Home Page,   MARCA-Models Home Page


Overview

The matrix corresponding to a specific instance of a model is generated by a single call to the Fortran subroutine that bears the name of the model. For example, a call to mutex:

	call mutex(index,dwork,mdw,iwork,miw,n,nz,j1,k1,k2)
generates the transition rate matrix corresponding to the instance index of the mutex model. (The meaning of the other parameters is provided below.) This permits a user to either generate a matrix and then write it to a specified file for later use, or to call the subroutine from within a separate program and subsequently manipulate the matrix as desired without the need to write/read it onto auxiliary storage.

The remainder of this page explains which source code files and datasets are needed, the parameter list of the routine that when called actually generates a transition rate matrix, the storage format used to hold the matrix, and how to get the subroutines and datasets.


Subroutines and Datasets

The Fortran file, generate.f contains code that is required in the generation of all models.
The names of the subroutines that are in this file are: genmatrix, wpack, statematx, stappend, searchlist, getkey, writeToFile.

Furthermore, corresponding to each model is


Model Parameter List

The parameter list is the same for all model subroutines.

      subroutine model(index,dwork,mdw,iwork,miw,n,nz,j1,k1,k2)
   
   Input ===>
      index:    a particular dataset of the input file
      dwork:    a real*8 work array
      iwork:    an integer work array
      mdw,miw:  the sizes of dwork and iwork respectively
   Output ==>
      n:        The order of the transition rate matrix
      nz:       The number of nonzero elements in the matrix
      j1:       The starting location in dwork of the nonzero elements
      k1:       The starting location in iwork of the column indices
      k2:       The starting location in iwork of the row boundaries

A call to one of the subroutines ncd, mutex, ... will generate a transition rate matrix of order n that is stored in the compact Harwell-Boeing format for sparse matrices. The (nz) nonzero elements of the transition matrix are stored contiguously in a real*8 work array (dwork) beginning at position j1. The (nz) column indices are stored in an integer work array (iwork) beginning at position k1, while the (n+1) row boundary markers are stored in the same integer work array beginning at position k2 .


Sample Driver Program

The first subroutine in each source code file, model.f , is a sample driver program. This program calls the subroutine for different values of index and hence generates matrices corresponding to different sets of the model's parameter values.

To execute the sample driver program for one of the models, it suffices to overwrite Makefile with model_makefile, execute the make operation and run the executable model file. E.g.,

   cp mutex_makefile Makefile      % overwrite Makefile
   make                            % make executable module
   mutex                           % run the mutex example


Sample driver program for the NCD model.

   *****************************************************************
   ***              A DRIVER FOR THE NCD EXAMPLE                 ***
   *****************************************************************
    
   c    ***  This driver generates matrices for the first four   ***
   c    ***  data sets (index = 1,4) in the file "ncd_in"        ***
    
   c    ***  Replace parameter statement (line 3 of driver) with ***
   c             parameter (miw=1985395,mdw=1207052)
   c    ***  to allocate sufficient memory for any/all datasets  ***
   *****************************************************************
 
      program driver
 
      implicit double precision (a-h,o-z)
      parameter (miw=175785,mdw=81222)
      real*4 etime,time
      dimension iwork(miw),dwork(mdw)
      open(unit=12, file='ncd_in')
      open(unit=14, file='ncd_matx',status='unknown')
      io_unit = 14
 
      time = etime(t)
      do index = 1,4
         print *, ' '
         print *, '**********************************************'
         print *, '***             Dataset',index,'           ***'
 
         call ncd(index,dwork,mdw,iwork,miw,n,nz,j1,k1,k2)
 
         print *, '       Now writing to: ncd_matx.'
c        call writeToFile(n,nz,dwork(j1),iwork(k1),iwork(k2),io_unit)
         print *, ' '
         print *, 'Matrix has been written to: ncd_matx.'
         print *, ' '
      end do
      time = etime(t)-time
      print *, 'Time taken:',time
 
      close(12)
      close(14)
      stop
      end

As stated in the comments, this driver generates four transition rate matrices corresponding to the first four data sets, index = 1,2,3,4, in the input data file ncd_in. It opens a file called ncd_matx into which the four matrices should be entered. However, the statement to actually do this has been commented out. The subroutine writeToFile takes a matrix in Harwell-Boeing format and writes it in a simpler format to the file specified by the unit number io_unit. In the new format, the number of rows, number of columns and number of nonzeros is printed on the first line. Each succeeding line contains a nonzero element along with its column and row positions. These are in order: row number; column number; nonzero element. All the elements of row i precede those of row i+1 and follow those of row i-1 . A final terminator line containing -1 -1 -1 is tagged on to the end.


Billy's Home Page,   MARCA-Models Home Page