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