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