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