1 /* $Id: mat.h,v 1.145 1997/10/14 04:29:18 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 MatIncreaseOverlap(Mat,int,IS *,int); 145 146 extern int MatAXPY(Scalar *,Mat,Mat); 147 extern int MatAYPX(Scalar *,Mat,Mat); 148 extern int MatCompress(Mat); 149 150 extern int MatScale(Scalar *,Mat); 151 extern int MatShift(Scalar *,Mat); 152 153 extern int MatSetLocalToGlobalMapping(Mat, ISLocalToGlobalMapping); 154 extern int MatSetLocalToGlobalMappingBlocked(Mat, ISLocalToGlobalMapping); 155 extern int MatZeroRowsLocal(Mat,IS,Scalar*); 156 extern int MatSetValuesLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 157 extern int MatSetValuesBlockedLocal(Mat,int,int*,int,int*,Scalar*,InsertMode); 158 159 /* Routines unique to particular data structures */ 160 extern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***); 161 162 /* 163 These routines are not usually accessed directly, rather solving is 164 done through the SLES, KSP and PC interfaces. 165 */ 166 167 typedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,ORDER_RCM=3, 168 ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_FLOW,ORDER_NEW} MatReordering; 169 extern int MatGetReordering(Mat,MatReordering,IS*,IS*); 170 extern int MatGetReorderingTypeFromOptions(char *,MatReordering*); 171 extern int MatReorderingRegister(MatReordering,MatReordering*,char*,int(*)(Mat,MatReordering,IS*,IS*)); 172 extern int MatReorderingGetName(MatReordering,char **); 173 extern int MatReorderingRegisterDestroy(); 174 extern int MatReorderingRegisterAll(); 175 extern int MatReorderingRegisterAllCalled; 176 177 extern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS); 178 179 extern int MatCholeskyFactor(Mat,IS,double); 180 extern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*); 181 extern int MatCholeskyFactorNumeric(Mat,Mat*); 182 183 extern int MatLUFactor(Mat,IS,IS,double); 184 extern int MatILUFactor(Mat,IS,IS,double,int); 185 extern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*); 186 extern int MatILUFactorSymbolic(Mat,IS,IS,double,int,Mat*); 187 extern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*); 188 extern int MatLUFactorNumeric(Mat,Mat*); 189 extern int MatILUDTFactor(Mat,double,int,IS,IS,Mat *); 190 191 extern int MatSolve(Mat,Vec,Vec); 192 extern int MatForwardSolve(Mat,Vec,Vec); 193 extern int MatBackwardSolve(Mat,Vec,Vec); 194 extern int MatSolveAdd(Mat,Vec,Vec,Vec); 195 extern int MatSolveTrans(Mat,Vec,Vec); 196 extern int MatSolveTransAdd(Mat,Vec,Vec,Vec); 197 198 extern int MatSetUnfactored(Mat); 199 200 typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3, 201 SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8, 202 SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16, 203 SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType; 204 extern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec); 205 206 typedef enum {SAME_NONZERO_PATTERN,DIFFERENT_NONZERO_PATTERN,SAME_PRECONDITIONER} MatStructure; 207 208 /* 209 These routines are for efficiently computing Jacobians via finite differences. 210 */ 211 typedef enum {COLORING_NATURAL, COLORING_SL, COLORING_LF, COLORING_ID, 212 COLORING_NEW} MatColoring; 213 extern int MatGetColoring(Mat,MatColoring,ISColoring*); 214 extern int MatGetColoringTypeFromOptions(char *,MatColoring*); 215 extern int MatColoringRegister(MatColoring,MatColoring*,char*,int(*)(Mat,MatColoring,ISColoring *)); 216 extern int MatColoringRegisterAll(); 217 extern int MatColoringRegisterAllCalled; 218 extern int MatColoringRegisterDestroy(); 219 extern int MatColoringPatch(Mat,int,int *,ISColoring*); 220 221 /* 222 Data structures used to compute Jacobian vector products 223 efficiently using finite differences. 224 */ 225 #define MAT_FDCOLORING_COOKIE PETSC_COOKIE + 22 226 227 typedef struct _p_MatFDColoring *MatFDColoring; 228 229 extern int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *); 230 extern int MatFDColoringDestroy(MatFDColoring); 231 extern int MatFDColoringView(MatFDColoring,Viewer); 232 extern int MatFDColoringSetFunction(MatFDColoring,int (*)(void),void*); 233 extern int MatFDColoringSetParameters(MatFDColoring,double,double); 234 extern int MatFDColoringSetFrequency(MatFDColoring,int); 235 extern int MatFDColoringGetFrequency(MatFDColoring,int*); 236 extern int MatFDColoringSetFromOptions(MatFDColoring); 237 extern int MatFDColoringPrintHelp(MatFDColoring); 238 extern int MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *); 239 extern int MatFDColoringApplyTS(Mat,MatFDColoring,double,Vec,MatStructure*,void *); 240 241 /* 242 These routines are for partitioning matrices: currently used only 243 for adjacency matrix, MatCreateSeqAdj() or MatCreateMPIAdj(). 244 */ 245 typedef enum {PARTITIONING_NATURAL, PARTITIONING_CURRENT, PARTITIONING_NEW} MatPartitioning; 246 extern int MatGetPartitioning(Mat,MatPartitioning,int,ISPartitioning*); 247 extern int MatGetPartitioningTypeFromOptions(char *,MatPartitioning*); 248 extern int MatPartitioningRegister(MatPartitioning,MatPartitioning*,char*, 249 int(*)(Mat,MatPartitioning,int,ISPartitioning *)); 250 extern int MatPartitioningRegisterAll(); 251 extern int MatPartitioningRegisterAllCalled; 252 extern int MatPartitioningRegisterDestroy(); 253 254 /* 255 If you add entries here you must also add them to FINCLUDE/mat.h 256 */ 257 typedef enum { MATOP_SET_VALUES=0, 258 MATOP_GET_ROW=1, 259 MATOP_RESTORE_ROW=2, 260 MATOP_MULT=3, 261 MATOP_MULT_ADD=4, 262 MATOP_MULT_TRANS=5, 263 MATOP_MULT_TRANS_ADD=6, 264 MATOP_SOLVE=7, 265 MATOP_SOLVE_ADD=8, 266 MATOP_SOLVE_TRANS=9, 267 MATOP_SOLVE_TRANS_ADD=10, 268 MATOP_LUFACTOR=11, 269 MATOP_CHOLESKYFACTOR=12, 270 MATOP_RELAX=13, 271 MATOP_TRANSPOSE=14, 272 MATOP_GETINFO=15, 273 MATOP_EQUAL=16, 274 MATOP_GET_DIAGONAL=17, 275 MATOP_DIAGONAL_SCALE=18, 276 MATOP_NORM=19, 277 MATOP_ASSEMBLY_BEGIN=20, 278 MATOP_ASSEMBLY_END=21, 279 MATOP_COMPRESS=22, 280 MATOP_SET_OPTION=23, 281 MATOP_ZERO_ENTRIES=24, 282 MATOP_ZERO_ROWS=25, 283 MATOP_LUFACTOR_SYMBOLIC=26, 284 MATOP_LUFACTOR_NUMERIC=27, 285 MATOP_CHOLESKY_FACTOR_SYMBOLIC=28, 286 MATOP_CHOLESKY_FACTOR_NUMERIC=29, 287 MATOP_GET_SIZE=30, 288 MATOP_GET_LOCAL_SIZE=31, 289 MATOP_GET_OWNERSHIP_RANGE=32, 290 MATOP_ILUFACTOR_SYMBOLIC=33, 291 MATOP_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=34, 292 MATOP_GET_ARRAY=35, 293 MATOP_RESTORE_ARRAY=36, 294 295 MATOP_CONVERT_SAME_TYPE=37, 296 MATOP_FORWARD_SOLVE=38, 297 MATOP_BACKWARD_SOLVE=39, 298 MATOP_ILUFACTOR=40, 299 MATOP_INCOMPLETECHOLESKYFACTOR=41, 300 MATOP_AXPY=42, 301 MATOP_GET_SUBMATRICES=43, 302 MATOP_INCREASE_OVERLAP=44, 303 MATOP_GET_VALUES=45, 304 MATOP_COPY=46, 305 MATOP_PRINT_HELP=47, 306 MATOP_SCALE=48, 307 MATOP_SHIFT=49, 308 MATOP_DIAGONAL_SHIFT=50, 309 MATOP_ILUDT_FACTOR=51, 310 MATOP_GET_BLOCK_SIZE=52, 311 MATOP_GET_ROW_IJ=53, 312 MATOP_RESTORE_ROW_IJ=54, 313 MATOP_GET_COLUMN_IJ=55, 314 MATOP_RESTORE_COLUMN_IJ=56, 315 MATOP_FDCOLORING_CREATE=57, 316 MATOP_COLORING_PATCH=58, 317 MATOP_SET_UNFACTORED=59, 318 MATOP_PERMUTE=60, 319 MATOP_SET_VALUES_BLOCKED=61, 320 MATOP_DESTROY=250, 321 MATOP_VIEW=251 322 } MatOperation; 323 extern int MatHasOperation(Mat,MatOperation,PetscTruth*); 324 extern int MatShellSetOperation(Mat,MatOperation,void *); 325 extern int MatShellGetOperation(Mat,MatOperation,void **); 326 327 /* 328 Codes for matrices stored on disk. By default they are 329 stored in a universal format. By changing the format with 330 ViewerSetFormat(viewer,VIEWER_FORMAT_BINARY_NATIVE); the matrices will 331 be stored in a way natural for the matrix, for example dense matrices 332 would be stored as dense. Matrices stored this way may only be 333 read into matrices of the same time. 334 */ 335 #define MATRIX_BINARY_FORMAT_DENSE -1 336 337 /* 338 New matrix classes not yet distributed 339 */ 340 /* 341 MatAIJIndices is a data structure for storing the nonzero location information 342 for sparse matrices. Several matrices with identical nonzero structure can share 343 the same MatAIJIndices. 344 */ 345 typedef struct _p_MatAIJIndices* MatAIJIndices; 346 347 extern int MatCreateAIJIndices(int,int,int*,int*,PetscTruth,MatAIJIndices*); 348 extern int MatCreateAIJIndicesEmpty(int,int,int*,PetscTruth,MatAIJIndices*); 349 extern int MatAttachAIJIndices(MatAIJIndices,MatAIJIndices*); 350 extern int MatDestroyAIJIndices(MatAIJIndices); 351 extern int MatCopyAIJIndices(MatAIJIndices,MatAIJIndices*); 352 extern int MatValidateAIJIndices(int,MatAIJIndices); 353 extern int MatShiftAIJIndices(MatAIJIndices); 354 extern int MatShrinkAIJIndices(MatAIJIndices); 355 extern int MatTransposeAIJIndices(MatAIJIndices, MatAIJIndices*); 356 357 extern int MatCreateSeqCSN(MPI_Comm,int,int,int*,int,Mat*); 358 extern int MatCreateSeqCSN_Single(MPI_Comm,int,int,int*,int,Mat*); 359 extern int MatCreateSeqCSNWithPrecision(MPI_Comm,int,int,int*,int,ScalarPrecision,Mat*); 360 361 extern int MatCreateSeqCSNIndices(MPI_Comm,MatAIJIndices,int,Mat *); 362 extern int MatCreateSeqCSNIndices_Single(MPI_Comm,MatAIJIndices,int,Mat *); 363 extern int MatCreateSeqCSNIndicesWithPrecision(MPI_Comm,MatAIJIndices,int,ScalarPrecision,Mat *); 364 365 366 #endif 367 368 369 370