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