1 /* $Id: mat.h,v 1.170 1999/03/18 15:37:17 bsmith Exp bsmith $ */ 2 /* 3 Include file for the matrix component of PETSc 4 */ 5 #ifndef __MAT_H 6 #define __MAT_H 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 14 14 /* 15 The default matrix data storage formats and routines to create them. 16 17 MATLASTTYPE is "end-of-list" marker that can be used to check that 18 MAX_MATRIX_TYPES is large enough. The rule is 19 MAX_MATRIX_TYPES >= MATLASTTYPE . 20 21 To do: add a test program that checks the consistency of these values. 22 */ 23 typedef enum { MATSAME=-1, MATSEQDENSE, MATSEQAIJ, MATMPIAIJ, MATSHELL, 24 MATMPIROWBS, MATSEQBDIAG, MATMPIBDIAG, MATMPIDENSE, MATSEQBAIJ, 25 MATMPIBAIJ, MATMPICSN, MATSEQCSN, MATSEQADJ, MATMPIADJ, 26 MATLASTTYPE } MatType; 27 28 extern int MatCreate(MPI_Comm,int,int,Mat*); 29 extern int MatCreateSeqDense(MPI_Comm,int,int,Scalar*,Mat*); 30 extern int MatCreateMPIDense(MPI_Comm,int,int,int,int,Scalar*,Mat*); 31 extern int MatCreateSeqAIJ(MPI_Comm,int,int,int,int*,Mat*); 32 extern int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,int*,int,int*,Mat*); 33 extern int MatCreateMPIRowbs(MPI_Comm,int,int,int,int*,void*,Mat*); 34 extern int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,int*,Scalar**,Mat*); 35 extern int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,int*,Scalar**,Mat*); 36 extern int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,int*,Mat*); 37 extern int MatCreateMPIBAIJ(MPI_Comm,int,int,int,int,int,int,int*,int,int*,Mat*); 38 extern int MatCreateSeqAdj(MPI_Comm,int,int,int*,int*,Mat *); 39 extern int MatCreateMPIAdj(MPI_Comm,int,int,int*,int*,Mat*); 40 41 extern int MatDestroy(Mat); 42 43 extern int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*); 44 extern int MatShellGetContext(Mat,void **); 45 46 extern int MatPrintHelp(Mat); 47 extern int MatGetMaps(Mat,Map*,Map*); 48 49 /* ------------------------------------------------------------*/ 50 extern int MatSetValues(Mat,int,int*,int,int*,Scalar*,InsertMode); 51 extern int MatSetValuesBlocked(Mat,int,int*,int,int*,Scalar*,InsertMode); 52 53 typedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType; 54 extern int MatAssemblyBegin(Mat,MatAssemblyType); 55 extern int MatAssemblyEnd(Mat,MatAssemblyType); 56 #define MatSetValue(v,i,j,va,mode) \ 57 {int _ierr,_row = i,_col = j; Scalar _va = va; \ 58 _ierr = MatSetValues(v,1,&_row,1,&_col,&_va,mode);CHKERRQ(_ierr); \ 59 } 60 #define MatGetValue(v,i,j,va) \ 61 {int _ierr,_row = i,_col = j; \ 62 _ierr = MatGetValues(v,1,&_row,1,&_col,&va);CHKERRQ(_ierr); \ 63 } 64 /* 65 Any additions/changes here MUST also be made in include/finclude/mat.h 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=65,MAT_NO_NEW_DIAGONALS=66, 71 MAT_YES_NEW_DIAGONALS=67,MAT_INODE_LIMIT_1=68,MAT_INODE_LIMIT_2=69, 72 MAT_INODE_LIMIT_3=70,MAT_INODE_LIMIT_4=71,MAT_INODE_LIMIT_5=72, 73 MAT_IGNORE_OFF_PROC_ENTRIES=73,MAT_ROWS_UNSORTED=74, 74 MAT_COLUMNS_UNSORTED=75,MAT_NEW_NONZERO_LOCATION_ERR=76, 75 MAT_NEW_NONZERO_ALLOCATION_ERR=77,MAT_USE_HASH_TABLE=78} 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 MatUseScaledForm(Mat,PetscTruth); 148 extern int MatScaleSystem(Mat,Vec,Vec); 149 extern int MatUnScaleSystem(Mat,Vec,Vec); 150 151 extern int MatGetSize(Mat,int*,int*); 152 extern int MatGetLocalSize(Mat,int*,int*); 153 extern int MatGetOwnershipRange(Mat,int*,int*); 154 155 typedef enum {MAT_INITIAL_MATRIX, MAT_REUSE_MATRIX} MatReuse; 156 extern int MatGetSubMatrices(Mat,int,IS *,IS *,MatReuse,Mat **); 157 extern int MatDestroyMatrices(int, Mat **); 158 extern int MatGetSubMatrix(Mat,IS,IS,int,MatReuse,Mat *); 159 160 extern int MatIncreaseOverlap(Mat,int,IS *,int); 161 162 extern int MatAXPY(Scalar *,Mat,Mat); 163 extern int MatAYPX(Scalar *,Mat,Mat); 164 extern int MatCompress(Mat); 165 166 extern int MatScale(Scalar *,Mat); 167 extern int MatShift(Scalar *,Mat); 168 169 extern int MatSetLocalToGlobalMapping(Mat, ISLocalToGlobalMapping); 170 extern int MatSetLocalToGlobalMappingBlocked(Mat, ISLocalToGlobalMapping); 171 extern int MatZeroRowsLocal(Mat,IS,Scalar*); 172 extern int MatSetValuesLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 173 extern int MatSetValuesBlockedLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 174 175 extern int MatSetStashInitialSize(Mat,int, int); 176 177 /* Routines unique to particular data structures */ 178 extern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***); 179 extern int MatSeqAIJSetColumnIndices(Mat,int *); 180 extern int MatSeqBAIJSetColumnIndices(Mat,int *); 181 182 extern int MatStoreValues(Mat); 183 extern int MatRetrieveValues(Mat); 184 185 /* 186 These routines are not usually accessed directly, rather solving is 187 done through the SLES, KSP and PC interfaces. 188 */ 189 190 typedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,ORDER_RCM=3, 191 ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_FLOW,ORDER_NEW} MatOrderingType; 192 extern int MatGetOrdering(Mat,MatOrderingType,IS*,IS*); 193 extern int MatGetOrderingTypeFromOptions(char *,MatOrderingType*); 194 extern int MatOrderingRegister(MatOrderingType,MatOrderingType*,char*, 195 int(*)(Mat,MatOrderingType,IS*,IS*)); 196 extern int MatOrderingGetName(MatOrderingType,char **); 197 extern int MatOrderingRegisterDestroy(void); 198 extern int MatOrderingRegisterAll(void); 199 extern int MatOrderingRegisterAllCalled; 200 201 extern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS); 202 203 extern int MatCholeskyFactor(Mat,IS,double); 204 extern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*); 205 extern int MatCholeskyFactorNumeric(Mat,Mat*); 206 207 /* 208 Context of matrix information, used with MatILUFactor() and MatILUFactorSymbolic() 209 Note: If any entries are added to this context, be sure 210 to adjust MAT_ILUINFO_SIZE in finclude/mat.h 211 212 Note: The integer values below are passed in double to allow easy use from 213 Fortran 214 */ 215 typedef struct { 216 double levels; /* ILU(levels) */ 217 double fill; /* expected fill; nonzeros in factored matrix/nonzeros in original matrix*/ 218 double diagonal_fill; /* force diagonal to fill in if initially not filled */ 219 } MatILUInfo; 220 221 extern int MatLUFactor(Mat,IS,IS,double); 222 extern int MatILUFactor(Mat,IS,IS,MatILUInfo*); 223 extern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*); 224 extern int MatILUFactorSymbolic(Mat,IS,IS,MatILUInfo*,Mat*); 225 extern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*); 226 extern int MatLUFactorNumeric(Mat,Mat*); 227 extern int MatILUDTFactor(Mat,double,int,IS,IS,Mat *); 228 229 extern int MatSolve(Mat,Vec,Vec); 230 extern int MatForwardSolve(Mat,Vec,Vec); 231 extern int MatBackwardSolve(Mat,Vec,Vec); 232 extern int MatSolveAdd(Mat,Vec,Vec,Vec); 233 extern int MatSolveTrans(Mat,Vec,Vec); 234 extern int MatSolveTransAdd(Mat,Vec,Vec,Vec); 235 236 extern int MatSetUnfactored(Mat); 237 238 typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3, 239 SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8, 240 SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16, 241 SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType; 242 extern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec); 243 244 245 /* 246 These routines are for efficiently computing Jacobians via finite differences. 247 */ 248 typedef enum {COLORING_NATURAL, COLORING_SL, COLORING_LF, COLORING_ID, 249 COLORING_NEW} MatColoringType; 250 extern int MatGetColoring(Mat,MatColoringType,ISColoring*); 251 extern int MatGetColoringTypeFromOptions(char *,MatColoringType*); 252 extern int MatColoringRegister(MatColoringType,MatColoringType*,char*,int(*)(Mat,MatColoringType,ISColoring *)); 253 extern int MatColoringRegisterAll(void); 254 extern int MatColoringRegisterAllCalled; 255 extern int MatColoringRegisterDestroy(void); 256 extern int MatColoringPatch(Mat,int,int *,ISColoring*); 257 258 /* 259 Data structures used to compute Jacobian vector products 260 efficiently using finite differences. 261 */ 262 #define MAT_FDCOLORING_COOKIE PETSC_COOKIE + 22 263 264 typedef struct _p_MatFDColoring *MatFDColoring; 265 266 extern int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *); 267 extern int MatFDColoringDestroy(MatFDColoring); 268 extern int MatFDColoringView(MatFDColoring,Viewer); 269 extern int MatFDColoringSetFunction(MatFDColoring,int (*)(void),void*); 270 extern int MatFDColoringSetParameters(MatFDColoring,double,double); 271 extern int MatFDColoringSetFrequency(MatFDColoring,int); 272 extern int MatFDColoringGetFrequency(MatFDColoring,int*); 273 extern int MatFDColoringSetFromOptions(MatFDColoring); 274 extern int MatFDColoringPrintHelp(MatFDColoring); 275 extern int MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *); 276 extern int MatFDColoringApplyTS(Mat,MatFDColoring,double,Vec,MatStructure*,void *); 277 278 /* 279 These routines are for partitioning matrices: currently used only 280 for adjacency matrix, MatCreateSeqAdj() or MatCreateMPIAdj(). 281 */ 282 #define MATPARTITIONING_COOKIE PETSC_COOKIE + 25 283 284 typedef struct _p_MatPartitioning *MatPartitioning; 285 286 typedef enum {MATPARTITIONING_CURRENT,MATPARTITIONING_PARMETIS,MATPARTITIONING_NEW} MatPartitioningType; 287 288 extern int MatPartitioningCreate(MPI_Comm,MatPartitioning*); 289 extern int MatPartitioningSetType(MatPartitioning,MatPartitioningType); 290 extern int MatPartitioningSetAdjacency(MatPartitioning,Mat); 291 extern int MatPartitioningSetVertexWeights(MatPartitioning,double*); 292 extern int MatPartitioningApply(MatPartitioning,IS*); 293 extern int MatPartitioningDestroy(MatPartitioning); 294 extern int MatPartitioningRegister(MatPartitioningType,MatPartitioningType *,char*,int(*)(MatPartitioning)); 295 extern int MatPartitioningRegisterAll(void); 296 extern int MatPartitioningRegisterAllCalled; 297 extern int MatPartitioningRegisterDestroy(void); 298 extern int MatPartitioningView(MatPartitioning,Viewer); 299 extern int MatPartitioningSetFromOptions(MatPartitioning); 300 extern int MatPartitioningPrintHelp(MatPartitioning); 301 extern int MatPartitioningGetType(MatPartitioning,MatPartitioningType*,char**); 302 303 extern int MatPartitioningParmetisSetCoarseSequential(MatPartitioning); 304 305 /* 306 If you add entries here you must also add them to finclude/mat.h 307 */ 308 typedef enum { MATOP_SET_VALUES=0, 309 MATOP_GET_ROW=1, 310 MATOP_RESTORE_ROW=2, 311 MATOP_MULT=3, 312 MATOP_MULT_ADD=4, 313 MATOP_MULT_TRANS=5, 314 MATOP_MULT_TRANS_ADD=6, 315 MATOP_SOLVE=7, 316 MATOP_SOLVE_ADD=8, 317 MATOP_SOLVE_TRANS=9, 318 MATOP_SOLVE_TRANS_ADD=10, 319 MATOP_LUFACTOR=11, 320 MATOP_CHOLESKYFACTOR=12, 321 MATOP_RELAX=13, 322 MATOP_TRANSPOSE=14, 323 MATOP_GETINFO=15, 324 MATOP_EQUAL=16, 325 MATOP_GET_DIAGONAL=17, 326 MATOP_DIAGONAL_SCALE=18, 327 MATOP_NORM=19, 328 MATOP_ASSEMBLY_BEGIN=20, 329 MATOP_ASSEMBLY_END=21, 330 MATOP_COMPRESS=22, 331 MATOP_SET_OPTION=23, 332 MATOP_ZERO_ENTRIES=24, 333 MATOP_ZERO_ROWS=25, 334 MATOP_LUFACTOR_SYMBOLIC=26, 335 MATOP_LUFACTOR_NUMERIC=27, 336 MATOP_CHOLESKY_FACTOR_SYMBOLIC=28, 337 MATOP_CHOLESKY_FACTOR_NUMERIC=29, 338 MATOP_GET_SIZE=30, 339 MATOP_GET_LOCAL_SIZE=31, 340 MATOP_GET_OWNERSHIP_RANGE=32, 341 MATOP_ILUFACTOR_SYMBOLIC=33, 342 MATOP_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=34, 343 MATOP_GET_ARRAY=35, 344 MATOP_RESTORE_ARRAY=36, 345 346 MATOP_CONVERT_SAME_TYPE=37, 347 MATOP_FORWARD_SOLVE=38, 348 MATOP_BACKWARD_SOLVE=39, 349 MATOP_ILUFACTOR=40, 350 MATOP_INCOMPLETECHOLESKYFACTOR=41, 351 MATOP_AXPY=42, 352 MATOP_GET_SUBMATRICES=43, 353 MATOP_INCREASE_OVERLAP=44, 354 MATOP_GET_VALUES=45, 355 MATOP_COPY=46, 356 MATOP_PRINT_HELP=47, 357 MATOP_SCALE=48, 358 MATOP_SHIFT=49, 359 MATOP_DIAGONAL_SHIFT=50, 360 MATOP_ILUDT_FACTOR=51, 361 MATOP_GET_BLOCK_SIZE=52, 362 MATOP_GET_ROW_IJ=53, 363 MATOP_RESTORE_ROW_IJ=54, 364 MATOP_GET_COLUMN_IJ=55, 365 MATOP_RESTORE_COLUMN_IJ=56, 366 MATOP_FDCOLORING_CREATE=57, 367 MATOP_COLORING_PATCH=58, 368 MATOP_SET_UNFACTORED=59, 369 MATOP_PERMUTE=60, 370 MATOP_SET_VALUES_BLOCKED=61, 371 MATOP_DESTROY=250, 372 MATOP_VIEW=251 373 } MatOperation; 374 extern int MatHasOperation(Mat,MatOperation,PetscTruth*); 375 extern int MatShellSetOperation(Mat,MatOperation,void *); 376 extern int MatShellGetOperation(Mat,MatOperation,void **); 377 378 /* 379 Codes for matrices stored on disk. By default they are 380 stored in a universal format. By changing the format with 381 ViewerSetFormat(viewer,VIEWER_FORMAT_BINARY_NATIVE); the matrices will 382 be stored in a way natural for the matrix, for example dense matrices 383 would be stored as dense. Matrices stored this way may only be 384 read into matrices of the same time. 385 */ 386 #define MATRIX_BINARY_FORMAT_DENSE -1 387 388 /* 389 New matrix classes not yet distributed 390 */ 391 /* 392 MatAIJIndices is a data structure for storing the nonzero location information 393 for sparse matrices. Several matrices with identical nonzero structure can share 394 the same MatAIJIndices. 395 */ 396 typedef struct _p_MatAIJIndices* MatAIJIndices; 397 398 extern int MatCreateAIJIndices(int,int,int*,int*,PetscTruth,MatAIJIndices*); 399 extern int MatCreateAIJIndicesEmpty(int,int,int*,PetscTruth,MatAIJIndices*); 400 extern int MatAttachAIJIndices(MatAIJIndices,MatAIJIndices*); 401 extern int MatDestroyAIJIndices(MatAIJIndices); 402 extern int MatCopyAIJIndices(MatAIJIndices,MatAIJIndices*); 403 extern int MatValidateAIJIndices(int,MatAIJIndices); 404 extern int MatShiftAIJIndices(MatAIJIndices); 405 extern int MatShrinkAIJIndices(MatAIJIndices); 406 extern int MatTransposeAIJIndices(MatAIJIndices, MatAIJIndices*); 407 408 extern int MatCreateSeqCSN(MPI_Comm,int,int,int*,int,Mat*); 409 extern int MatCreateSeqCSN_Single(MPI_Comm,int,int,int*,int,Mat*); 410 extern int MatCreateSeqCSNWithPrecision(MPI_Comm,int,int,int*,int,ScalarPrecision,Mat*); 411 412 extern int MatCreateSeqCSNIndices(MPI_Comm,MatAIJIndices,int,Mat *); 413 extern int MatCreateSeqCSNIndices_Single(MPI_Comm,MatAIJIndices,int,Mat *); 414 extern int MatCreateSeqCSNIndicesWithPrecision(MPI_Comm,MatAIJIndices,int,ScalarPrecision,Mat *); 415 416 extern int MatMPIBAIJSetHashTableFactor(Mat,double); 417 extern int MatSeqAIJGetInodeSizes(Mat,int *,int *[],int *); 418 419 420 #endif 421 422 423 424