1 /* $Id: mat.h,v 1.137 1997/07/01 22:18:03 bsmith Exp bsmith $ */ 2 /* 3 Include file for the matrix component of PETSc 4 */ 5 #ifndef __MAT_PACKAGE 6 #define __MAT_PACKAGE 7 #include "vec.h" 8 9 #define MAT_COOKIE PETSC_COOKIE+5 10 11 typedef struct _p_Mat* Mat; 12 13 #define MAX_MATRIX_TYPES 12 14 /* 15 The default matrix data storage formats and routines to create them. 16 */ 17 typedef enum { MATSAME=-1, MATSEQDENSE, MATSEQAIJ, MATMPIAIJ, MATSHELL, 18 MATMPIROWBS, MATSEQBDIAG, MATMPIBDIAG, MATMPIDENSE, MATSEQBAIJ, 19 MATMPIBAIJ, MATMPICSN, MATSEQCSN, MATSEQADJ, MATMPIADJ} MatType; 20 21 extern int MatCreate(MPI_Comm,int,int,Mat*); 22 extern int MatCreateSeqDense(MPI_Comm,int,int,Scalar*,Mat*); 23 extern int MatCreateMPIDense(MPI_Comm,int,int,int,int,Scalar*,Mat*); 24 extern int MatCreateSeqAIJ(MPI_Comm,int,int,int,int*,Mat*); 25 extern int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,int*,int,int*,Mat*); 26 extern int MatCreateMPIRowbs(MPI_Comm,int,int,int,int*,void*,Mat*); 27 extern int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,int*,Scalar**,Mat*); 28 extern int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,int*,Scalar**,Mat*); 29 extern int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,int*,Mat*); 30 extern int MatCreateMPIBAIJ(MPI_Comm,int,int,int,int,int,int,int*,int,int*,Mat*); 31 extern int MatCreateSeqAdj(MPI_Comm,int,int,int*,int*,Mat *); 32 extern int MatCreateMPIAdj(MPI_Comm,int,int,int,int*,int*,Mat*); 33 34 extern int MatDestroy(Mat); 35 36 extern int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*); 37 extern int MatShellGetContext(Mat,void **); 38 39 extern int MatPrintHelp(Mat); 40 41 /* ------------------------------------------------------------*/ 42 extern int MatSetValues(Mat,int,int*,int,int*,Scalar*,InsertMode); 43 extern int MatSetValuesBlocked(Mat,int,int*,int,int*,Scalar*,InsertMode); 44 45 typedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType; 46 extern int MatAssemblyBegin(Mat,MatAssemblyType); 47 extern int MatAssemblyEnd(Mat,MatAssemblyType); 48 #define MatSetValue(v,i,j,va,mode) \ 49 {int _ierr,_row = i,_col = j; Scalar _va = va; \ 50 _ierr = MatSetValues(v,1,&_row,1,&_col,&_va,mode);CHKERRQ(_ierr); \ 51 } 52 53 typedef enum {MAT_ROW_ORIENTED=1,MAT_COLUMN_ORIENTED=2,MAT_ROWS_SORTED=4, 54 MAT_COLUMNS_SORTED=8,MAT_NO_NEW_NONZERO_LOCATIONS=16, 55 MAT_YES_NEW_NONZERO_LOCATIONS=32,MAT_SYMMETRIC=64, 56 MAT_STRUCTURALLY_SYMMETRIC,MAT_NO_NEW_DIAGONALS, 57 MAT_YES_NEW_DIAGONALS,MAT_INODE_LIMIT_1,MAT_INODE_LIMIT_2, 58 MAT_INODE_LIMIT_3,MAT_INODE_LIMIT_4,MAT_INODE_LIMIT_5, 59 MAT_IGNORE_OFF_PROC_ENTRIES,MAT_ROWS_UNSORTED, 60 MAT_COLUMNS_UNSORTED,MAT_NEW_NONZERO_LOCATION_ERROR, 61 MAT_NEW_NONZERO_ALLOCATION_ERROR} MatOption; 62 extern int MatSetOption(Mat,MatOption); 63 extern int MatGetType(Mat,MatType*,char**); 64 extern int MatGetTypeFromOptions(MPI_Comm,char*,MatType*,PetscTruth*); 65 66 extern int MatGetValues(Mat,int,int*,int,int*,Scalar*); 67 extern int MatGetRow(Mat,int,int *,int **,Scalar**); 68 extern int MatRestoreRow(Mat,int,int *,int **,Scalar**); 69 extern int MatGetColumn(Mat,int,int *,int **,Scalar**); 70 extern int MatRestoreColumn(Mat,int,int *,int **,Scalar**); 71 extern int MatGetArray(Mat,Scalar **); 72 extern int MatRestoreArray(Mat,Scalar **); 73 extern int MatGetBlockSize(Mat,int *); 74 75 extern int MatMult(Mat,Vec,Vec); 76 extern int MatMultAdd(Mat,Vec,Vec,Vec); 77 extern int MatMultTrans(Mat,Vec,Vec); 78 extern int MatMultTransAdd(Mat,Vec,Vec,Vec); 79 80 extern int MatConvert(Mat,MatType,Mat*); 81 extern int MatConvertRegister(MatType,MatType,int (*)(Mat,MatType,Mat*)); 82 extern int MatConvertRegisterAll(); 83 84 extern int MatCopy(Mat,Mat); 85 extern int MatView(Mat,Viewer); 86 extern int MatLoad(Viewer,MatType,Mat*); 87 extern int MatLoadRegister(MatType,int (*)(Viewer,MatType,Mat*)); 88 extern int MatLoadRegisterAll(); 89 90 extern int MatGetRowIJ(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *); 91 extern int MatRestoreRowIJ(Mat,int,PetscTruth,int *,int **,int **,PetscTruth *); 92 extern int MatGetColumnIJ(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *); 93 extern int MatRestoreColumnIJ(Mat,int,PetscTruth,int *,int **,int **,PetscTruth *); 94 95 /* 96 Context of matrix information, used with MatGetInfo() 97 Note: If any entries are added to this context, be sure 98 to adjust MAT_INFO_SIZE in FINCLUDE/mat.h 99 */ 100 typedef struct { 101 PLogDouble rows_global, columns_global; /* number of global rows and columns */ 102 PLogDouble rows_local, columns_local; /* number of local rows and columns */ 103 PLogDouble block_size; /* block size */ 104 PLogDouble nz_allocated, nz_used, nz_unneeded; /* number of nonzeros */ 105 PLogDouble memory; /* memory allocated */ 106 PLogDouble assemblies; /* number of matrix assemblies */ 107 PLogDouble mallocs; /* number of mallocs during MatSetValues() */ 108 PLogDouble fill_ratio_given, fill_ratio_needed; /* fill ratio for LU/ILU */ 109 PLogDouble factor_mallocs; /* number of mallocs during factorization */ 110 } MatInfo; 111 112 typedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType; 113 extern int MatGetInfo(Mat,MatInfoType,MatInfo*); 114 extern int MatValid(Mat,PetscTruth*); 115 extern int MatGetDiagonal(Mat,Vec); 116 extern int MatTranspose(Mat,Mat*); 117 extern int MatPermute(Mat,IS,IS,Mat *); 118 extern int MatDiagonalScale(Mat,Vec,Vec); 119 extern int MatDiagonalShift(Mat,Vec); 120 extern int MatEqual(Mat,Mat, PetscTruth*); 121 122 extern int MatNorm(Mat,NormType,double *); 123 extern int MatZeroEntries(Mat); 124 extern int MatZeroRows(Mat,IS,Scalar*); 125 extern int MatZeroColumns(Mat,IS,Scalar*); 126 127 extern int MatGetSize(Mat,int*,int*); 128 extern int MatGetLocalSize(Mat,int*,int*); 129 extern int MatGetOwnershipRange(Mat,int*,int*); 130 131 typedef enum {MAT_INITIAL_MATRIX, MAT_REUSE_MATRIX} MatGetSubMatrixCall; 132 extern int MatGetSubMatrices(Mat,int,IS *,IS *,MatGetSubMatrixCall,Mat **); 133 extern int MatDestroyMatrices(int, Mat **); 134 extern int MatIncreaseOverlap(Mat,int,IS *,int); 135 136 extern int MatAXPY(Scalar *,Mat,Mat); 137 extern int MatCompress(Mat); 138 139 extern int MatScale(Scalar *,Mat); 140 extern int MatShift(Scalar *,Mat); 141 142 extern int MatSetLocalToGlobalMapping(Mat, int,int *); 143 extern int MatSetLocalToGlobalMappingBlocked(Mat, int,int *); 144 extern int MatZeroRowsLocal(Mat,IS,Scalar*); 145 extern int MatSetValuesLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 146 extern int MatSetValuesBlockedLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 147 148 /* Routines unique to particular data structures */ 149 extern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***); 150 151 /* 152 These routines are not usually accessed directly, rather solving is 153 done through the SLES, KSP and PC interfaces. 154 */ 155 156 typedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,ORDER_RCM=3, 157 ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_FLOW,ORDER_NEW} MatReordering; 158 extern int MatGetReordering(Mat,MatReordering,IS*,IS*); 159 extern int MatGetReorderingTypeFromOptions(char *,MatReordering*); 160 extern int MatReorderingRegister(MatReordering,MatReordering*,char*,int(*)(Mat,MatReordering,IS*,IS*)); 161 extern int MatReorderingGetName(MatReordering,char **); 162 extern int MatReorderingRegisterDestroy(); 163 extern int MatReorderingRegisterAll(); 164 extern int MatReorderingRegisterAllCalled; 165 166 extern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS); 167 168 extern int MatCholeskyFactor(Mat,IS,double); 169 extern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*); 170 extern int MatCholeskyFactorNumeric(Mat,Mat*); 171 172 extern int MatLUFactor(Mat,IS,IS,double); 173 extern int MatILUFactor(Mat,IS,IS,double,int); 174 extern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*); 175 extern int MatILUFactorSymbolic(Mat,IS,IS,double,int,Mat*); 176 extern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*); 177 extern int MatLUFactorNumeric(Mat,Mat*); 178 extern int MatILUDTFactor(Mat,double,int,IS,IS,Mat *); 179 180 extern int MatSolve(Mat,Vec,Vec); 181 extern int MatForwardSolve(Mat,Vec,Vec); 182 extern int MatBackwardSolve(Mat,Vec,Vec); 183 extern int MatSolveAdd(Mat,Vec,Vec,Vec); 184 extern int MatSolveTrans(Mat,Vec,Vec); 185 extern int MatSolveTransAdd(Mat,Vec,Vec,Vec); 186 187 extern int MatSetUnfactored(Mat); 188 189 typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3, 190 SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8, 191 SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16, 192 SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType; 193 extern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec); 194 195 /* 196 These routines are for efficiently computing Jacobians via finite differences. 197 */ 198 typedef enum {COLORING_NATURAL, COLORING_SL, COLORING_LF, COLORING_ID, 199 COLORING_NEW} MatColoring; 200 extern int MatGetColoring(Mat,MatColoring,ISColoring*); 201 extern int MatGetColoringTypeFromOptions(char *,MatColoring*); 202 extern int MatColoringRegister(MatColoring,MatColoring*,char*,int(*)(Mat,MatColoring,ISColoring *)); 203 extern int MatColoringRegisterAll(); 204 extern int MatColoringRegisterAllCalled; 205 extern int MatColoringRegisterDestroy(); 206 extern int MatColoringPatch(Mat,int,int *,ISColoring*); 207 208 /* 209 Data structures used to compute Jacobian vector products 210 efficiently using finite differences. 211 */ 212 #define MAT_FDCOLORING_COOKIE PETSC_COOKIE + 22 213 214 typedef struct _p_MatFDColoring *MatFDColoring; 215 216 extern int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *); 217 extern int MatFDColoringDestroy(MatFDColoring); 218 extern int MatFDColoringView(MatFDColoring,Viewer); 219 extern int MatFDColoringSetParameters(MatFDColoring,double,double); 220 extern int MatFDColoringSetFromOptions(MatFDColoring); 221 extern int MatFDColoringPrintHelp(MatFDColoring); 222 extern int MatFDColoringApply(Mat,MatFDColoring,Vec,Vec,Vec,Vec,int (*)(void *,Vec,Vec,void*), 223 void *,void *); 224 225 /* 226 If you add entries here you must also add them to FINCLUDE/mat.h 227 */ 228 typedef enum { MATOP_SET_VALUES=0, 229 MATOP_GET_ROW=1, 230 MATOP_RESTORE_ROW=2, 231 MATOP_MULT=3, 232 MATOP_MULT_ADD=4, 233 MATOP_MULT_TRANS=5, 234 MATOP_MULT_TRANS_ADD=6, 235 MATOP_SOLVE=7, 236 MATOP_SOLVE_ADD=8, 237 MATOP_SOLVE_TRANS=9, 238 MATOP_SOLVE_TRANS_ADD=10, 239 MATOP_LUFACTOR=11, 240 MATOP_CHOLESKYFACTOR=12, 241 MATOP_RELAX=13, 242 MATOP_TRANSPOSE=14, 243 MATOP_GETINFO=15, 244 MATOP_EQUAL=16, 245 MATOP_GET_DIAGONAL=17, 246 MATOP_DIAGONAL_SCALE=18, 247 MATOP_NORM=19, 248 MATOP_ASSEMBLY_BEGIN=20, 249 MATOP_ASSEMBLY_END=21, 250 MATOP_COMPRESS=22, 251 MATOP_SET_OPTION=23, 252 MATOP_ZERO_ENTRIES=24, 253 MATOP_ZERO_ROWS=25, 254 MATOP_LUFACTOR_SYMBOLIC=26, 255 MATOP_LUFACTOR_NUMERIC=27, 256 MATOP_CHOLESKY_FACTOR_SYMBOLIC=28, 257 MATOP_CHOLESKY_FACTOR_NUMERIC=29, 258 MATOP_GET_SIZE=30, 259 MATOP_GET_LOCAL_SIZE=31, 260 MATOP_GET_OWNERSHIP_RANGE=32, 261 MATOP_ILUFACTOR_SYMBOLIC=33, 262 MATOP_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=34, 263 MATOP_GET_ARRAY=35, 264 MATOP_RESTORE_ARRAY=36, 265 266 MATOP_CONVERT_SAME_TYPE=39, 267 MATOP_FORWARD_SOLVE=40, 268 MATOP_BACKWARD_SOLVE=41, 269 MATOP_ILUFACTOR=42, 270 MATOP_INCOMPLETECHOLESKYFACTOR=43, 271 MATOP_AXPY=44, 272 MATOP_GET_SUBMATRICES=45, 273 MATOP_INCREASE_OVERLAP=46, 274 MATOP_GET_VALUES=47, 275 MATOP_COPY=48, 276 MATOP_PRINT_HELP=49, 277 MATOP_SCALE=50, 278 MATOP_SHIFT=51, 279 MATOP_DIAGONAL_SHIFT=52, 280 MATOP_ILUDT_FACTOR=53, 281 MATOP_GET_BLOCK_SIZE=54, 282 MATOP_GET_ROW_IJ=55, 283 MATOP_RESTORE_ROW_IJ=56, 284 MATOP_GET_COLUMN_IJ=57, 285 MATOP_RESTORE_COLUMN_IJ=58, 286 MATOP_FDCOLORING_CREATE=59, 287 MATOP_DESTROY=250, 288 MATOP_VIEW=251 289 } MatOperation; 290 extern int MatHasOperation(Mat,MatOperation,PetscTruth*); 291 extern int MatShellSetOperation(Mat,MatOperation,void *); 292 293 /* 294 Codes for matrices stored on disk. By default they are 295 stored in a universal format. By changing the format with 296 ViewerSetFormat(viewer,VIEWER_FORMAT_BINARY_NATIVE); the matrices will 297 be stored in a way natural for the matrix, for example dense matrices 298 would be stored as dense. Matrices stored this way may only be 299 read into matrices of the same time. 300 */ 301 #define MATRIX_BINARY_FORMAT_DENSE -1 302 303 /* 304 New matrix classes not yet distributed 305 */ 306 /* 307 MatAIJIndices is a data structure for storing the nonzero location information 308 for sparse matrices. Several matrices with identical nonzero structure can share 309 the same MatAIJIndices. 310 */ 311 typedef struct _p_MatAIJIndices* MatAIJIndices; 312 313 extern int MatCreateAIJIndices(int,int,int*,int*,PetscTruth,MatAIJIndices*); 314 extern int MatCreateAIJIndicesEmpty(int,int,int*,PetscTruth,MatAIJIndices*); 315 extern int MatAttachAIJIndices(MatAIJIndices,MatAIJIndices*); 316 extern int MatDestroyAIJIndices(MatAIJIndices); 317 extern int MatCopyAIJIndices(MatAIJIndices,MatAIJIndices*); 318 extern int MatValidateAIJIndices(int,MatAIJIndices); 319 extern int MatShiftAIJIndices(MatAIJIndices); 320 extern int MatShrinkAIJIndices(MatAIJIndices); 321 extern int MatTransposeAIJIndices(MatAIJIndices, MatAIJIndices*); 322 323 extern int MatCreateSeqCSN(MPI_Comm,int,int,int*,int,Mat*); 324 extern int MatCreateSeqCSN_Single(MPI_Comm,int,int,int*,int,Mat*); 325 extern int MatCreateSeqCSNWithPrecision(MPI_Comm,int,int,int*,int,ScalarPrecision,Mat*); 326 327 extern int MatCreateSeqCSNIndices(MPI_Comm,MatAIJIndices,int,Mat *); 328 extern int MatCreateSeqCSNIndices_Single(MPI_Comm,MatAIJIndices,int,Mat *); 329 extern int MatCreateSeqCSNIndicesWithPrecision(MPI_Comm,MatAIJIndices,int,ScalarPrecision,Mat *); 330 331 332 #endif 333 334 335 336