1 /*$Id: matio.c,v 1.60 1999/10/01 21:21:43 bsmith Exp bsmith $*/ 2 3 /* 4 This file contains simple binary read/write routines for matrices. 5 */ 6 7 #include "petsc.h" 8 #include "src/mat/matimpl.h" /*I "mat.h" I*/ 9 #include "sys.h" 10 11 static int MatLoadersSet = 0,(*MatLoaders[MAX_MATRIX_TYPES])(Viewer,MatType,Mat*) = 12 {0,0,0,0,0,0,0,0,0,0,0,0}; 13 14 #undef __FUNC__ 15 #define __FUNC__ "MatLoadRegister" 16 /*@C 17 MatLoadRegister - Allows one to register a routine that reads matrices 18 from a binary file for a particular matrix type. 19 20 Not Collective 21 22 Input Parameters: 23 + type - the type of matrix (defined in include/mat.h), for example, MATSEQAIJ. 24 - loader - the function that reads the matrix from the binary file. 25 26 Level: developer 27 28 .seealso: MatLoadRegisterAll(), MatLoad() 29 30 @*/ 31 int MatLoadRegister(MatType type,int (*loader)(Viewer,MatType,Mat*)) 32 { 33 PetscFunctionBegin; 34 MatLoaders[type] = loader; 35 MatLoadersSet = 1; 36 PetscFunctionReturn(0); 37 } 38 39 #undef __FUNC__ 40 #define __FUNC__ "MatLoadPrintHelp_Private" 41 static int MatLoadPrintHelp_Private(Mat A) 42 { 43 static int called = 0; 44 MPI_Comm comm = A->comm; 45 int ierr; 46 47 PetscFunctionBegin; 48 if (called) {PetscFunctionReturn(0);} else called = 1; 49 ierr = (*PetscHelpPrintf)(comm," Options for MatLoad:\n");CHKERRQ(ierr); 50 ierr = (*PetscHelpPrintf)(comm," -matload_block_size <block_size> :Used for MATBAIJ, MATBDIAG\n");CHKERRQ(ierr); 51 ierr = (*PetscHelpPrintf)(comm," -matload_bdiag_diags <s1,s2,s3,...> : Used for MATBDIAG\n");CHKERRQ(ierr); 52 PetscFunctionReturn(0); 53 } 54 55 #undef __FUNC__ 56 #define __FUNC__ "MatLoad" 57 /*@C 58 MatLoad - Loads a matrix that has been stored in binary format 59 with MatView(). The matrix format is determined from the options database. 60 Generates a parallel MPI matrix if the communicator has more than one 61 processor. The default matrix type is AIJ. 62 63 Collective on Viewer 64 65 Input Parameters: 66 + viewer - binary file viewer, created with ViewerBinaryOpen() 67 - outtype - type of matrix desired, for example MATSEQAIJ, 68 MATMPIROWBS, etc. See types in petsc/include/mat.h. 69 70 Output Parameters: 71 . newmat - new matrix 72 73 Basic Options Database Keys: 74 The following options will work if you first call MatGetTypeFromOptions() 75 and pass the resulting type to MatLoad(). 76 These options use MatCreateSeqXXX or MatCreateMPIXXX, 77 depending on the communicator, comm. 78 + -mat_aij - AIJ type 79 . -mat_baij - block AIJ type 80 . -mat_dense - dense type 81 . -mat_bdiag - block diagonal type 82 . -mat_complex - indicates the matrix has complex entries 83 - -mat_double - indicates the matrix has double entries 84 85 More Options Database Keys: 86 + -mat_seqaij - AIJ type 87 . -mat_mpiaij - parallel AIJ type 88 . -mat_seqbaij - block AIJ type 89 . -mat_mpibaij - parallel block AIJ type 90 . -mat_seqbdiag - block diagonal type 91 . -mat_mpibdiag - parallel block diagonal type 92 . -mat_mpirowbs - parallel rowbs type 93 . -mat_seqdense - dense type 94 - -mat_mpidense - parallel dense type 95 96 More Options Database Keys: 97 Used with block matrix formats (MATSEQBAIJ, MATMPIBDIAG, ...) to specify 98 block size 99 . -matload_block_size <bs> 100 101 Used to specify block diagonal numbers for MATSEQBDIAG and MATMPIBDIAG formats 102 . -matload_bdiag_diags <s1,s2,s3,...> 103 104 Level: beginner 105 106 Notes: 107 MatLoad() automatically loads into the options database any options 108 given in the file filename.info where filename is the name of the file 109 that was passed to the ViewerBinaryOpen(). The options in the info 110 file will be ignored if you use the -matload_ignore_info option. 111 112 In parallel, each processor can load a subset of rows (or the 113 entire matrix). This routine is especially useful when a large 114 matrix is stored on disk and only part of it existsis desired on each 115 processor. For example, a parallel solver may access only some of 116 the rows from each processor. The algorithm used here reads 117 relatively small blocks of data rather than reading the entire 118 matrix and then subsetting it. 119 120 Notes for advanced users: 121 Most users should not need to know the details of the binary storage 122 format, since MatLoad() and MatView() completely hide these details. 123 But for anyone who's interested, the standard binary matrix storage 124 format is 125 126 $ int MAT_COOKIE 127 $ int number of rows 128 $ int number of columns 129 $ int total number of nonzeros 130 $ int *number nonzeros in each row 131 $ int *column indices of all nonzeros (starting index is zero) 132 $ Scalar *values of all nonzeros 133 134 Note for Cray users, the int's stored in the binary file are 32 bit 135 integers; not 64 as they are represented in the memory, so if you 136 write your own routines to read/write these binary files from the Cray 137 you need to adjust the integer sizes that you read in, see 138 PetscReadBinary() and PetscWriteBinary() to see how this may be 139 done. 140 141 In addition, PETSc automatically does the byte swapping for 142 machines that store the bytes reversed, e.g. DEC alpha, freebsd, 143 linux, nt and the paragon; thus if you write your own binary 144 read/write routines you have to swap the bytes; see PetscReadBinary() 145 and PetscWriteBinary() to see how this may be done. 146 147 .keywords: matrix, load, binary, input 148 149 .seealso: ViewerBinaryOpen(), MatView(), VecLoad(), MatLoadRegister(), 150 MatLoadRegisterAll(), MatGetTypeFromOptions() 151 152 @*/ 153 int MatLoad(Viewer viewer,MatType outtype,Mat *newmat) 154 { 155 int ierr,flg; 156 PetscTruth set,isbinary; 157 MatType type; 158 MPI_Comm comm; 159 160 PetscFunctionBegin; 161 if (outtype > MAX_MATRIX_TYPES || outtype < 0) { 162 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,1,"Not a valid matrix type"); 163 } 164 PetscValidHeaderSpecific(viewer,VIEWER_COOKIE); 165 *newmat = 0; 166 167 if (!MatLoadersSet) { 168 ierr = MatLoadRegisterAll();CHKERRQ(ierr); 169 } 170 171 ierr = PetscTypeCompare((PetscObject)viewer,BINARY_VIEWER,&isbinary);CHKERRQ(ierr); 172 if (!isbinary) { 173 SETERRQ(PETSC_ERR_ARG_WRONG,0,"Invalid viewer; open viewer with ViewerBinaryOpen()"); 174 } 175 176 ierr = PetscObjectGetComm((PetscObject)viewer,&comm);CHKERRQ(ierr); 177 ierr = MatGetTypeFromOptions(comm,0,&type,&set);CHKERRQ(ierr); 178 if (!set) type = outtype; 179 180 PLogEventBegin(MAT_Load,viewer,0,0,0); 181 182 if (!MatLoaders[outtype]) { 183 SETERRQ(PETSC_ERR_ARG_WRONG,1,"Invalid matrix type, or matrix load not registered"); 184 } 185 186 ierr = (*MatLoaders[outtype])(viewer,type,newmat);CHKERRQ(ierr); 187 188 ierr = OptionsHasName(PETSC_NULL,"-help", &flg);CHKERRQ(ierr); 189 if (flg) {ierr = MatLoadPrintHelp_Private(*newmat);CHKERRQ(ierr); } 190 PLogEventEnd(MAT_Load,viewer,0,0,0); 191 PetscFunctionReturn(0); 192 } 193 194