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