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