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