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