1 /* $Id: mat.h,v 1.165 1999/01/12 23:18:23 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 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 /* Routines unique to particular data structures */ 176 extern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***); 177 extern int MatSeqAIJSetColumnIndices(Mat,int *); 178 extern int MatSeqBAIJSetColumnIndices(Mat,int *); 179 180 extern int MatStoreValues(Mat); 181 extern int MatRetrieveValues(Mat); 182 183 /* 184 These routines are not usually accessed directly, rather solving is 185 done through the SLES, KSP and PC interfaces. 186 */ 187 188 typedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,ORDER_RCM=3, 189 ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_FLOW,ORDER_NEW} MatReorderingType; 190 extern int MatGetReordering(Mat,MatReorderingType,IS*,IS*); 191 extern int MatGetReorderingTypeFromOptions(char *,MatReorderingType*); 192 extern int MatReorderingRegister(MatReorderingType,MatReorderingType*,char*, 193 int(*)(Mat,MatReorderingType,IS*,IS*)); 194 extern int MatReorderingGetName(MatReorderingType,char **); 195 extern int MatReorderingRegisterDestroy(void); 196 extern int MatReorderingRegisterAll(void); 197 extern int MatReorderingRegisterAllCalled; 198 199 extern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS); 200 201 extern int MatCholeskyFactor(Mat,IS,double); 202 extern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*); 203 extern int MatCholeskyFactorNumeric(Mat,Mat*); 204 205 /* 206 Context of matrix information, used with MatILUFactor() and MatILUFactorSymbolic() 207 Note: If any entries are added to this context, be sure 208 to adjust MAT_ILUINFO_SIZE in finclude/mat.h 209 210 Note: The integer values below are passed in double to allow easy use from 211 Fortran 212 */ 213 typedef struct { 214 double levels; /* ILU(levels) */ 215 double fill; /* expected fill; nonzeros in factored matrix/nonzeros in original matrix*/ 216 double diagonal_fill; /* force diagonal to fill in if initially not filled */ 217 } MatILUInfo; 218 219 extern int MatLUFactor(Mat,IS,IS,double); 220 extern int MatILUFactor(Mat,IS,IS,MatILUInfo*); 221 extern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*); 222 extern int MatILUFactorSymbolic(Mat,IS,IS,MatILUInfo*,Mat*); 223 extern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*); 224 extern int MatLUFactorNumeric(Mat,Mat*); 225 extern int MatILUDTFactor(Mat,double,int,IS,IS,Mat *); 226 227 extern int MatSolve(Mat,Vec,Vec); 228 extern int MatForwardSolve(Mat,Vec,Vec); 229 extern int MatBackwardSolve(Mat,Vec,Vec); 230 extern int MatSolveAdd(Mat,Vec,Vec,Vec); 231 extern int MatSolveTrans(Mat,Vec,Vec); 232 extern int MatSolveTransAdd(Mat,Vec,Vec,Vec); 233 234 extern int MatSetUnfactored(Mat); 235 236 typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3, 237 SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8, 238 SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16, 239 SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType; 240 extern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec); 241 242 243 /* 244 These routines are for efficiently computing Jacobians via finite differences. 245 */ 246 typedef enum {COLORING_NATURAL, COLORING_SL, COLORING_LF, COLORING_ID, 247 COLORING_NEW} MatColoringType; 248 extern int MatGetColoring(Mat,MatColoringType,ISColoring*); 249 extern int MatGetColoringTypeFromOptions(char *,MatColoringType*); 250 extern int MatColoringRegister(MatColoringType,MatColoringType*,char*,int(*)(Mat,MatColoringType,ISColoring *)); 251 extern int MatColoringRegisterAll(void); 252 extern int MatColoringRegisterAllCalled; 253 extern int MatColoringRegisterDestroy(void); 254 extern int MatColoringPatch(Mat,int,int *,ISColoring*); 255 256 /* 257 Data structures used to compute Jacobian vector products 258 efficiently using finite differences. 259 */ 260 #define MAT_FDCOLORING_COOKIE PETSC_COOKIE + 22 261 262 typedef struct _p_MatFDColoring *MatFDColoring; 263 264 extern int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *); 265 extern int MatFDColoringDestroy(MatFDColoring); 266 extern int MatFDColoringView(MatFDColoring,Viewer); 267 extern int MatFDColoringSetFunction(MatFDColoring,int (*)(void),void*); 268 extern int MatFDColoringSetParameters(MatFDColoring,double,double); 269 extern int MatFDColoringSetFrequency(MatFDColoring,int); 270 extern int MatFDColoringGetFrequency(MatFDColoring,int*); 271 extern int MatFDColoringSetFromOptions(MatFDColoring); 272 extern int MatFDColoringPrintHelp(MatFDColoring); 273 extern int MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *); 274 extern int MatFDColoringApplyTS(Mat,MatFDColoring,double,Vec,MatStructure*,void *); 275 276 /* 277 These routines are for partitioning matrices: currently used only 278 for adjacency matrix, MatCreateSeqAdj() or MatCreateMPIAdj(). 279 */ 280 #define PARTITIONING_COOKIE PETSC_COOKIE + 25 281 282 typedef struct _p_Partitioning *Partitioning; 283 284 typedef enum {PARTITIONING_CURRENT,PARTITIONING_PARMETIS,PARTITIONING_NEW} PartitioningType; 285 286 extern int PartitioningCreate(MPI_Comm,Partitioning*); 287 extern int PartitioningSetType(Partitioning,PartitioningType); 288 extern int PartitioningSetAdjacency(Partitioning,Mat); 289 extern int PartitioningSetVertexWeights(Partitioning,double*); 290 extern int PartitioningApply(Partitioning,IS*); 291 extern int PartitioningDestroy(Partitioning); 292 extern int PartitioningRegister(PartitioningType,PartitioningType *,char*,int(*)(Partitioning)); 293 extern int PartitioningRegisterAll(void); 294 extern int PartitioningRegisterAllCalled; 295 extern int PartitioningRegisterDestroy(void); 296 extern int PartitioningView(Partitioning,Viewer); 297 extern int PartitioningSetFromOptions(Partitioning); 298 extern int PartitioningPrintHelp(Partitioning); 299 extern int PartitioningGetType(Partitioning,PartitioningType*,char**); 300 301 extern int PartitioningParmetisSetCoarseSequential(Partitioning); 302 303 /* 304 If you add entries here you must also add them to finclude/mat.h 305 */ 306 typedef enum { MATOP_SET_VALUES=0, 307 MATOP_GET_ROW=1, 308 MATOP_RESTORE_ROW=2, 309 MATOP_MULT=3, 310 MATOP_MULT_ADD=4, 311 MATOP_MULT_TRANS=5, 312 MATOP_MULT_TRANS_ADD=6, 313 MATOP_SOLVE=7, 314 MATOP_SOLVE_ADD=8, 315 MATOP_SOLVE_TRANS=9, 316 MATOP_SOLVE_TRANS_ADD=10, 317 MATOP_LUFACTOR=11, 318 MATOP_CHOLESKYFACTOR=12, 319 MATOP_RELAX=13, 320 MATOP_TRANSPOSE=14, 321 MATOP_GETINFO=15, 322 MATOP_EQUAL=16, 323 MATOP_GET_DIAGONAL=17, 324 MATOP_DIAGONAL_SCALE=18, 325 MATOP_NORM=19, 326 MATOP_ASSEMBLY_BEGIN=20, 327 MATOP_ASSEMBLY_END=21, 328 MATOP_COMPRESS=22, 329 MATOP_SET_OPTION=23, 330 MATOP_ZERO_ENTRIES=24, 331 MATOP_ZERO_ROWS=25, 332 MATOP_LUFACTOR_SYMBOLIC=26, 333 MATOP_LUFACTOR_NUMERIC=27, 334 MATOP_CHOLESKY_FACTOR_SYMBOLIC=28, 335 MATOP_CHOLESKY_FACTOR_NUMERIC=29, 336 MATOP_GET_SIZE=30, 337 MATOP_GET_LOCAL_SIZE=31, 338 MATOP_GET_OWNERSHIP_RANGE=32, 339 MATOP_ILUFACTOR_SYMBOLIC=33, 340 MATOP_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=34, 341 MATOP_GET_ARRAY=35, 342 MATOP_RESTORE_ARRAY=36, 343 344 MATOP_CONVERT_SAME_TYPE=37, 345 MATOP_FORWARD_SOLVE=38, 346 MATOP_BACKWARD_SOLVE=39, 347 MATOP_ILUFACTOR=40, 348 MATOP_INCOMPLETECHOLESKYFACTOR=41, 349 MATOP_AXPY=42, 350 MATOP_GET_SUBMATRICES=43, 351 MATOP_INCREASE_OVERLAP=44, 352 MATOP_GET_VALUES=45, 353 MATOP_COPY=46, 354 MATOP_PRINT_HELP=47, 355 MATOP_SCALE=48, 356 MATOP_SHIFT=49, 357 MATOP_DIAGONAL_SHIFT=50, 358 MATOP_ILUDT_FACTOR=51, 359 MATOP_GET_BLOCK_SIZE=52, 360 MATOP_GET_ROW_IJ=53, 361 MATOP_RESTORE_ROW_IJ=54, 362 MATOP_GET_COLUMN_IJ=55, 363 MATOP_RESTORE_COLUMN_IJ=56, 364 MATOP_FDCOLORING_CREATE=57, 365 MATOP_COLORING_PATCH=58, 366 MATOP_SET_UNFACTORED=59, 367 MATOP_PERMUTE=60, 368 MATOP_SET_VALUES_BLOCKED=61, 369 MATOP_DESTROY=250, 370 MATOP_VIEW=251 371 } MatOperation; 372 extern int MatHasOperation(Mat,MatOperation,PetscTruth*); 373 extern int MatShellSetOperation(Mat,MatOperation,void *); 374 extern int MatShellGetOperation(Mat,MatOperation,void **); 375 376 /* 377 Codes for matrices stored on disk. By default they are 378 stored in a universal format. By changing the format with 379 ViewerSetFormat(viewer,VIEWER_FORMAT_BINARY_NATIVE); the matrices will 380 be stored in a way natural for the matrix, for example dense matrices 381 would be stored as dense. Matrices stored this way may only be 382 read into matrices of the same time. 383 */ 384 #define MATRIX_BINARY_FORMAT_DENSE -1 385 386 /* 387 New matrix classes not yet distributed 388 */ 389 /* 390 MatAIJIndices is a data structure for storing the nonzero location information 391 for sparse matrices. Several matrices with identical nonzero structure can share 392 the same MatAIJIndices. 393 */ 394 typedef struct _p_MatAIJIndices* MatAIJIndices; 395 396 extern int MatCreateAIJIndices(int,int,int*,int*,PetscTruth,MatAIJIndices*); 397 extern int MatCreateAIJIndicesEmpty(int,int,int*,PetscTruth,MatAIJIndices*); 398 extern int MatAttachAIJIndices(MatAIJIndices,MatAIJIndices*); 399 extern int MatDestroyAIJIndices(MatAIJIndices); 400 extern int MatCopyAIJIndices(MatAIJIndices,MatAIJIndices*); 401 extern int MatValidateAIJIndices(int,MatAIJIndices); 402 extern int MatShiftAIJIndices(MatAIJIndices); 403 extern int MatShrinkAIJIndices(MatAIJIndices); 404 extern int MatTransposeAIJIndices(MatAIJIndices, MatAIJIndices*); 405 406 extern int MatCreateSeqCSN(MPI_Comm,int,int,int*,int,Mat*); 407 extern int MatCreateSeqCSN_Single(MPI_Comm,int,int,int*,int,Mat*); 408 extern int MatCreateSeqCSNWithPrecision(MPI_Comm,int,int,int*,int,ScalarPrecision,Mat*); 409 410 extern int MatCreateSeqCSNIndices(MPI_Comm,MatAIJIndices,int,Mat *); 411 extern int MatCreateSeqCSNIndices_Single(MPI_Comm,MatAIJIndices,int,Mat *); 412 extern int MatCreateSeqCSNIndicesWithPrecision(MPI_Comm,MatAIJIndices,int,ScalarPrecision,Mat *); 413 414 extern int MatMPIBAIJSetHashTableFactor(Mat,double); 415 extern int MatSeqAIJGetInodeSizes(Mat,int *,int *[],int *); 416 417 418 #endif 419 420 421 422