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