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