1: /*$Id: matio.c,v 1.79 2001/08/06 21:16:10 bsmith Exp $*/

  3: /* 
  4:    This file contains simple binary read/write routines for matrices.
  5:  */

 7:  #include src/mat/matimpl.h
 8:  #include petscsys.h
  9: PetscTruth MatLoadRegisterAllCalled = PETSC_FALSE;
 10: PetscFList      MatLoadList              = 0;

 12: #undef __FUNCT__  
 14: /*@C
 15:     MatLoadRegister - Allows one to register a routine that reads matrices
 16:         from a binary file for a particular matrix type.

 18:   Not Collective

 20:   Input Parameters:
 21: +   type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ.
 22: -   loader - the function that reads the matrix from the binary file.

 24:   Level: developer

 26: .seealso: MatLoadRegisterAll(), MatLoad()

 28: @*/
 29: int MatLoadRegister(char *sname,char *path,char *name,int (*function)(PetscViewer,MatType,Mat*))
 30: {
 31:   int  ierr;
 32:   char fullname[256];

 35:   PetscFListConcat(path,name,fullname);
 36:   PetscFListAdd(&MatLoadList,sname,fullname,(void (*)(void))function);
 37:   return(0);
 38: }

 40: #undef __FUNCT__  
 42: static int MatLoadPrintHelp_Private(Mat A)
 43: {
 44:   static PetscTruth called = PETSC_FALSE;
 45:   MPI_Comm          comm = A->comm;
 46:   int               ierr;
 47: 
 49:   if (called) {return(0);} else called = PETSC_TRUE;
 50:   (*PetscHelpPrintf)(comm," Options for MatLoad:n");
 51:   (*PetscHelpPrintf)(comm,"  -mat_type <type>n");
 52:   (*PetscHelpPrintf)(comm,"  -matload_type <type>n");
 53:   (*PetscHelpPrintf)(comm,"  -matload_block_size <block_size> :Used for MATBAIJ, MATBDIAGn");
 54:   (*PetscHelpPrintf)(comm,"  -matload_bdiag_diags <s1,s2,s3,...> : Used for MATBDIAGn");
 55:   return(0);
 56: }

 58: #undef __FUNCT__  
 60: /*@C
 61:    MatLoad - Loads a matrix that has been stored in binary format
 62:    with MatView().  The matrix format is determined from the options database.
 63:    Generates a parallel MPI matrix if the communicator has more than one
 64:    processor.  The default matrix type is AIJ.

 66:    Collective on PetscViewer

 68:    Input Parameters:
 69: +  viewer - binary file viewer, created with PetscViewerBinaryOpen()
 70: -  outtype - type of matrix desired, for example MATSEQAIJ,
 71:              MATMPIROWBS, etc.  See types in petsc/include/petscmat.h.

 73:    Output Parameters:
 74: .  newmat - new matrix

 76:    Basic Options Database Keys:
 77: +    -matload_type seqaij   - AIJ type
 78: .    -matload_type mpiaij   - parallel AIJ type
 79: .    -matload_type seqbaij  - block AIJ type
 80: .    -matload_type mpibaij  - parallel block AIJ type
 81: .    -matload_type seqsbaij - block symmetric AIJ type
 82: .    -matload_type mpisbaij - parallel block symmetric AIJ type
 83: .    -matload_type seqbdiag - block diagonal type
 84: .    -matload_type mpibdiag - parallel block diagonal type
 85: .    -matload_type mpirowbs - parallel rowbs type
 86: .    -matload_type seqdense - dense type
 87: .    -matload_type mpidense - parallel dense type
 88: -    -matload_symmetric - matrix in file is symmetric

 90:    More Options Database Keys:
 91:    Used with block matrix formats (MATSEQBAIJ, MATMPIBDIAG, ...) to specify
 92:    block size
 93: .    -matload_block_size <bs>

 95:    Used to specify block diagonal numbers for MATSEQBDIAG and MATMPIBDIAG formats
 96: .    -matload_bdiag_diags <s1,s2,s3,...>

 98:    Level: beginner

100:    Notes:
101:    MatLoad() automatically loads into the options database any options
102:    given in the file filename.info where filename is the name of the file
103:    that was passed to the PetscViewerBinaryOpen(). The options in the info
104:    file will be ignored if you use the -matload_ignore_info option.

106:    In parallel, each processor can load a subset of rows (or the
107:    entire matrix).  This routine is especially useful when a large
108:    matrix is stored on disk and only part of it existsis desired on each
109:    processor.  For example, a parallel solver may access only some of
110:    the rows from each processor.  The algorithm used here reads
111:    relatively small blocks of data rather than reading the entire
112:    matrix and then subsetting it.

114:    Notes for advanced users:
115:    Most users should not need to know the details of the binary storage
116:    format, since MatLoad() and MatView() completely hide these details.
117:    But for anyone who's interested, the standard binary matrix storage
118:    format is

120: $    int    MAT_FILE_COOKIE
121: $    int    number of rows
122: $    int    number of columns
123: $    int    total number of nonzeros
124: $    int    *number nonzeros in each row
125: $    int    *column indices of all nonzeros (starting index is zero)
126: $    PetscScalar *values of all nonzeros

128:    Note for Cray users, the int's stored in the binary file are 32 bit
129: integers; not 64 as they are represented in the memory, so if you
130: write your own routines to read/write these binary files from the Cray
131: you need to adjust the integer sizes that you read in, see
132: PetscReadBinary() and PetscWriteBinary() to see how this may be
133: done.

135:    In addition, PETSc automatically does the byte swapping for
136: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
137: linux, nt and the paragon; thus if you write your own binary
138: read/write routines you have to swap the bytes; see PetscReadBinary()
139: and PetscWriteBinary() to see how this may be done.

141: .keywords: matrix, load, binary, input

143: .seealso: PetscViewerBinaryOpen(), MatView(), VecLoad(), MatLoadRegister(),
144:           MatLoadRegisterAll()

146:  @*/
147: int MatLoad(PetscViewer viewer,MatType outtype,Mat *newmat)
148: {
149:   int         ierr;
150:   PetscTruth  isbinary,flg;
151:   MPI_Comm    comm;
152:   int         (*r)(PetscViewer,MatType,Mat*);
153:   char        mtype[256],*prefix;


158:   *newmat  = 0;

160:   if (!MatLoadRegisterAllCalled) {
161:     MatLoadRegisterAll(PETSC_NULL);
162:   }

164:   PetscObjectGetOptionsPrefix((PetscObject)viewer,&prefix);
165:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_BINARY,&isbinary);
166:   if (!isbinary) {
167:     SETERRQ(PETSC_ERR_ARG_WRONG,"Invalid viewer; open viewer with PetscViewerBinaryOpen()");
168:   }

170:   PetscOptionsGetString(prefix,"-mat_type",mtype,256,&flg);
171:   if (flg) {
172:     outtype = mtype;
173:   }
174:   PetscOptionsGetString(prefix,"-matload_type",mtype,256,&flg);
175:   if (flg) {
176:     outtype = mtype;
177:   }
178:   PetscObjectGetComm((PetscObject)viewer,&comm);
179:   if (!outtype) outtype = MATMPIAIJ;
180:    PetscFListFind(comm,MatLoadList,outtype,(void(**)(void))&r);
181:   if (!r) SETERRQ1(1,"Unknown Mat type given: %s",outtype);

183:   PetscLogEventBegin(MAT_Load,viewer,0,0,0);
184:   (*r)(viewer,outtype,newmat);
185:   PetscLogEventEnd(MAT_Load,viewer,0,0,0);

187:   PetscOptionsHasName(prefix,"-matload_symmetric",&flg);
188:   if (flg) {
189:     MatSetOption(*newmat,MAT_SYMMETRIC);
190:   }
191:   PetscOptionsHasName(PETSC_NULL,"-help",&flg);
192:   if (flg) {MatLoadPrintHelp_Private(*newmat); }
193:   return(0);
194: }