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