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